Forem: Giovanni Crisalfi

Emacs Indigo: bindings for the Indigo cheminformatics library

Giovanni Crisalfi — Sun, 09 Nov 2025 12:53:16 +0000

After several months of development, I'm sharing the first pre-release of emacs-indigo, a native Emacs module that brings the Indigo cheminformatics library to Emacs Lisp. It's now at a point where the core functionality is solid enough to share.

What it does

The package provides Emacs Lisp bindings to Indigo through a native C module. You can work with molecules directly in Emacs: load structures, convert between formats (SMILES, MOL, CML), calculate properties, perform substructure matching, and render visualizations.

Memory management is handled automatically through indigo-let*, a resource management macro that takes care of cleanup even when working with persistent molecule handles:

(indigo-let* ((:molecule mol "CCO")
              (:atoms atoms mol))
  (indigo-map #'indigo-symbol atoms))
;; => ("C" "C" "O")

Current implementation

Core molecular operations (properties, calculations, format conversions)
Iterator system for structure traversal (atoms, bonds, rings, stereocenters)
Rendering and visualization (SVG, PNG output)
Reaction handling and atom mapping
Format support: SMILES, MOL, CML, reaction SMILES

I'm currently working on a lazy stream abstraction for idiomatic iterator handling, avoiding the need to eagerly copy results into temporary lists.

Installation

Installation was a key focus: in the end, I reduced it to a simple one-liner that only requires GCC/Make and an Emacs installation with module support. The build system handles Indigo dependencies automatically.

Status

This is an early implementation. Core functionality is solid enough and ready for experimentation, though some features (PKA functions, advanced analysis) still need work. I'd welcome feedback from anyone working at the intersection of chemistry and Emacs.

Repository: https://github.com/gicrisf/emacs-indigo

Windmenu: A Minimalist Windows Launcher

Giovanni Crisalfi — Tue, 28 Oct 2025 19:11:25 +0000

I've spent years bouncing between different operating systems, and I always found a pillar in dmenu's simplicity and portability. That minimal, keyboard-driven launcher that lets you summon any application without touching the mouse. I wanted something like that on Windows too.

On Launchers

An operating system should be an extension of volition: you think of a program, a fragment of data, and it manifests in the fewest steps possible, with the least amount of latency possible. It should aspire to be like a mental glove that transduces intent into execution, orchestrating a rhizome of tapered mechanical fingers in digital space.

When you approach the keyboard, you already know what you want to run: a browser, a text editor, a music player. Running a program is the very first action you take. On Linux desktops, this immediacy is understood, and not just in minimalist tiling window managers for power users, but in mainstream environments too.

KDE demonstrates this perfectly: while offering comprehensive mouse-driven interaction, it also provides KRunner, a keyboard-driven launcher so smooth I wouldn't even need dmenu there. GNOME, on the other hand, pursues an even deeper level of immediacy, since it drops you straight into the activities overview when you login into the system. Clean, direct.

But the built-in Windows search? It's a mess. Microsoft has been incorporating React Native into Windows 11 for parts of the Settings app and Start Menu. They're spinning up a JavaScript runtime and rendering engine for system UI components. On first launch in a session, if your CPU is busy, it visibly lags. The previous menu weren't perfect, but they were lighter on system resources. The new one loads ads, web results, and "helpful" suggestions you never asked for, all while consuming CPU cycles that could be doing actual work. And if you don't disable web search, it lags whenever you search for anything - doesn't matter how powerful your machine is, doesn't matter the state of the CPU.¹

Someone might say:

Computers are powerful nowadays, you can't even notice that!

Wrong. You can notice, and that line of thinking is why we have paradoxically less performant commercial OS than 30 years ago.

My own ritual, for example, usually begins with Emacs; when I'm on Windows, this means running the GUI version through WSL-1 and a X server. I didn't want to open a terminal emulator to launch a GUI: a hotkey, some typing, done. That's how it should be. ²

This specific need actually drove the whole custom command system. If a launcher couldn't handle arbitrary commands, it couldn't solve my problem; and that's what I wanted to achieve on Windows: to transplant the actual dmenu philosophy - a rectangle with text, high contrast, no translucent blur effects, no fade animations, no compositing - just a well-contrasted surface with program names that appears instantly when you press the hotkey.

There are third-party launchers for Windows already: PowerToys Run has beautiful UI, but beauty wasn't the point. I wanted minimalism: do one thing (launch programs or scripts), do it well, do it fast. This meant building with pure Win32 APIs. No frameworks, no rendering engines, no external UI libraries. Something lean enough it could theoretically run on Windows 3.1.

Win32 UI

I started from the UI. Creating windows, rendering text, drawing rectangles, managing keyboard input. It worked, but it was non-trivial and painful to do in Rust with a lot of unsafe calls. Then I found wlines by JerwuQu: a dmenu-like launcher for Windows, written in pure C with only Win32 APIs. Exactly what I wanted.

This reframed the problem. Instead of building a monolithic launcher, I could split it into two pieces:

Application launcher (windmenu): Discovers programs, handles hotkeys, manages execution
Generic selector (wlines): Displays items, handles navigation, returns selection

Windmenu's job became clear: organize input for wlines (the list of available programs) and manage the output (execute the selected program).

Wlines as Subprocess

The initial implementation was straightforward. Windmenu would build a command-line invocation of wlines with all the menu items and configuration flags, spawn it as a subprocess, and read the selected item from stdout:

// Simplified version of the original approach
use std::process::{Command, Stdio};

let child = Command::new("wlines.exe")
    .args(&["-sbg", "#285577", "-sfg", "#ffffff", "-p", "Select option:"])
    .stdin(Stdio::piped())
    .stdout(Stdio::piped())
    .spawn()?;

if let Some(mut stdin) = child.stdin {
    stdin.write_all(b"Option 1\nOption 2\nOption 3")?;
}

let output = child.wait_with_output()?;
let selection = std::str::from_utf8(&output.stdout)?;

This worked. It was performant on my development machine. But on older machines with mechanical drives, or systems under load, the lag was noticeable. The bottleneck was the process creation overhead. Every time you pressed the hotkey:

Windows had to create a new process
Load the wlines executable from disk
Initialize the UI subsystem
Parse all the command-line arguments
Render the window

Steps 1-4 happened every single time, even though the executable and most of the state never changed.

Forking Wlines

The solution was simple in concept: don't restart wlines every time. Keep it running as a background process (like a unix daemon) and communicate with it via named pipes. Instead of spawning a subprocess, windmenu opens a connection to \\.\pipe\wlines_pipe and sends the menu items directly to the already-initialized wlines daemon:

// Current daemon-based approach (simplified)
let pipe = OpenFileW(
    to_wide_string("\\\\.\\pipe\\wlines_pipe").as_ptr(),
    GENERIC_WRITE,
    0,
    // ... flags
);

WriteFile(pipe, items.as_bytes(), ...);

The daemon is already running, already has its window hidden and ready, already has fonts loaded. When the command arrives, it just shows the window and renders the items.

This approach required forking wlines. The original was designed as a one-shot command-line tool: like dmenu, it configured everything via command-line arguments. I extended it to:

Run as a background process
Listen on a named pipe for commands
Keep the window hidden until needed
Read configuration from a text file
Support vim keybindings (hjkl navigation)

The fork lives at github.com/gicrisf/wlines. Still pure C, which makes sense for this kind of low-level UI work.

My fork can compile as either a daemon or a traditional one-shot binary. Windmenu supports both modes: it prefers the daemon method (faster), but if the daemon isn't running and you've configured wlines_cli_path in windmenu.toml, it falls back to the subprocess approach. Use the fast daemon setup normally, keep the traditional method as fallback, or use it exclusively if you prefer. The architecture doesn't force you into one approach.

Two-Daemon Architecture

The two-daemon architecture wasn't just about performance. It was about preserving dmenu's fundamental philosophy: a generic, reusable selector interface. On Linux, dmenu is not locked to launching applications. You can pipe anything to it: password manager entries, file search results, window manager commands, music playlists. It's a moldable interface that displays input and returns selection, while bash scripts handle the actual logic.

On Windows, this approach isn't as straightforward. You could pair AutoHotkey with PowerShell scripts, but AutoHotkey requires administrator permissions for certain operations. Since I needed an active process to capture hotkeys anyway, it made sense to build something more integrated: a dedicated daemon that handles application discovery, configuration, and custom commands.

The split:

wlines-daemon.exe: Generic selector

Displays items, handles navigation
Returns selection
Doesn't care what you're selecting

windmenu.exe: Application launcher (one use case)

Monitors for hotkeys
Discovers applications (Start Menu, Windows Store apps)
Sends program list to wlines-daemon
Executes the selected program

They communicate via named pipes (\\.\pipe\wlines_pipe). External scripts can still access wlines directly, but windmenu makes it easier: bind PowerShell scripts to custom commands in the TOML config. For example, you can run WSL commands:

# Execute commands in WSL
[[commands]]
name = "WSL: Update packages"
args = ["wsl", "-e", "bash", "-c", "sudo apt update && sudo apt upgrade"]

# Open WSL home directory
[[commands]]
name = "WSL Home"
args = ["wsl", "-e", "bash", "-c", "cd ~ && exec bash"]

...or execute PowerShell snippets:

# Run a beep using PowerShell
[[commands]]
name = "Beep"
args = ["powershell", "-Command", "[Console]::Beep(440, 500)"]

Managing both daemons required a unified interface. I built a Daemon trait with separate implementations for WindmenuDaemon and WlinesDaemon:

pub trait Daemon {
    fn get_process_name(&self) -> &str;
    fn start(&self) -> Result<(), DaemonError>;
    fn stop(&self) -> Result<(), DaemonError>;
    fn restart(&self) -> Result<(), DaemonError>;
    fn get_status(&self) -> DaemonStatus;
    // Startup method management...
}

This trait-based approach made the CLI natural to implement: windmenu daemon all restart controls both, windmenu daemon wlines restart controls just wlines. The code mirrors the command structure (which was deliberate, because I modeled the entire interface after systemd).

Systemd-Inspired CLI

I needed to manage two daemons (windmenu and wlines) with complete lifecycle control: start, stop, restart, status checking, startup configuration. Windows Services require administrator privileges to install and manage, making deployment friction-heavy. I wanted Windmenu to work in restricted corporate environments where users can't install system services.

So I built a daemon manager into the CLI itself, taking inspiration from the best daemon manager I knew: systemd.

windmenu daemon self start
windmenu daemon self status

The pattern is consistent: windmenu daemon <target> <action>. The target can be self (windmenu daemon), wlines (wlines daemon), or all (both daemons). The actions mirror systemd's verbs:

# Start both daemons
windmenu daemon all start

# Restart just wlines
windmenu daemon wlines restart

# Check status of everything
windmenu daemon all status

This CLI design made the code architecture cleaner too. The Daemon trait I mentioned earlier emerged directly from thinking about what operations systemd exposes. If systemd needs start, stop, restart, status, and enable/disable for any service, then my Daemon trait should provide the same operations for any daemon.

The implementation uses Clap's derive macros for argument parsing, which generates help text automatically:

#[derive(Parser)]
enum Commands {
    Daemon {
        #[command(subcommand)]
        daemon_type: DaemonType,
    },
    Test {
        #[command(subcommand)]
        test_type: TestType,
    },
    Fetch {
        #[command(subcommand)]
        fetch_type: FetchType,
    },
}

#[derive(Subcommand)]
enum DaemonType {
    Self_ { #[command(subcommand)] action: DaemonAction },
    Wlines { #[command(subcommand)] action: DaemonAction },
    All { #[command(subcommand)] action: DaemonAction },
}

#[derive(Subcommand)]
enum DaemonAction {
    Start,
    Stop,
    Restart,
    Status,
    Enable { method: StartupMethod },
    Disable { method: StartupMethod },
}

This declarative approach keeps the CLI interface consistent with minimal boilerplate. The structure in the code mirrors the structure users type at the command line.

The consistency makes the tool predictable. If you've used systemd, the daemon management commands feel familiar. If you haven't, the hierarchical structure (windmenu <category> <target> <action>) makes the available operations discoverable through tab completion and --help flags.

Reparse Points

The launcher needs to find applications before it can launch them. Windows Store apps presented an unexpected challenge: unlike classic Win32 applications that live in Program Files, modern Windows apps hide in %LOCALAPPDATA%\Microsoft\WindowsApps as reparse points (symbolic links with extra metadata).

The naive approach (treating them like regular shortcuts) failed immediately. These aren't .lnk files; they're special filesystem objects that Windows handles differently. The solution required detecting reparse points using GetFileAttributesW and the FILE_ATTRIBUTE_REPARSE_POINT flag:

pub fn is_reparse_point(path: &str) -> bool {
    unsafe {
        let wide_path = to_wide_string(path);
        let attrs = GetFileAttributesW(wide_path.as_ptr());


        if attrs == INVALID_FILE_ATTRIBUTES {
            return false;
        }

        (attrs & FILE_ATTRIBUTE_REPARSE_POINT) != 0
    }
}

This lets Windmenu find modern apps like Windows Terminal, Calculator, and Settings alongside traditional desktop applications. The scanning happens once at startup, keeping the hotkey response instant.

Themes

Wlines originally configured everything via command-line arguments, like dmenu. For daemon mode, I added a text configuration file so wlines wouldn't parse dozens of flags on every invocation.

This meant having to maintain two config files: windmenu.toml for the launcher, wlines-config.txt for the UI. Different formats (verbose TOML for Rust, concise text for C), different field names. Users would need to understand both and remember which settings go where.

I solved this by auto-generating wlines-config.txt from a [theme] section in windmenu.toml:

[theme]
lines = 12
padding_x = 8
width_x = 1000
background_color = "#1e1e2e"
foreground_color = "#cdd6f4"
selected_background_color = "#89b4fa"
selected_foreground_color = "#1e1e2e"
text_background_color = "#313244"
text_foreground_color = "#cdd6f4"
font_size = 20

The theme.rs module translates these descriptive field names into wlines's format and generates wlines-config.txt on startup. Windmenu's config re-implements all of wlines's configuration fields. No reason to manually edit the generated file.

Themes become shareable: a [theme] section is just text. Copy someone's theme into your windmenu.toml, restart the daemon. Done.

Wlines stays independent. It's a standalone component with its own config file that doesn't need windmenu. Use it with your own scripts for password management or file selection. The auto-generation is windmenu's convenience layer, not a constraint on wlines.

Static Linking

Initially, I compiled with Rust's MSVC toolchain on Windows. The binaries ran fine, but they required the Visual C++ redistributables (vcruntime140.dll, api-ms-win-crt-*.dll). I accepted this limit at first (most Windows machines have these installed anyway).

Later in, while I was developing the NSIS installer (we'll see right after), I couldn't tolerate it. I wanted binaries that work everywhere: copy windmenu.exe to any Windows 10/11 machine and run it. No redistributables, no runtime dependencies, no installation friction.

Rust's MSVC toolchain uses Microsoft's linker (link.exe), which defaults to dynamic linking for compatibility. The GNU toolchain (mingw) avoids this by using gcc and static linking by default. Building natively on Windows with the GNU toolchain still pulled in Microsoft CRT dependencies. Cross-compiling from Linux to Windows with mingw-w64 produced cleaner results. The .cargo/config.toml forces static linking:

[target.x86_64-pc-windows-gnu]
linker = "x86_64-w64-mingw32-gcc"
rustflags = [
    "-C", "panic=abort",
    "-C", "link-args=-static",
    "-C", "link-args=-Wl,-Bstatic",
    "-C", "link-args=-l:libmsvcrt.a",
    "-C", "link-args=-l:libucrt.a",
    "-C", "link-args=-l:libpthread.a",
    "-C", "link-args=-l:libgcc.a",
    "-C", "link-args=-nostartfiles",
    "-C", "link-args=-Wl,--gc-sections",
    "-C", "link-args=-Wl,--as-needed"
]

The -l:lib*.a syntax forces static linking of specific libraries. The explicit target means Cargo places output in target/x86_64-pc-windows-gnu/release/ instead of target/release/. Dead code elimination (--gc-sections) and selective linking (--as-needed) reduce binary size.

Verifying dependencies with dumpbin /DEPENDENTS:

Microsoft (R) COFF/PE Dumper Version 14.42.34435.0
Copyright (C) Microsoft Corporation.  All rights reserved.


Dump of file target\x86_64-pc-windows-gnu\release\windmenu.exe

File Type: EXECUTABLE IMAGE

  Image has the following dependencies:

    KERNEL32.dll
    SHELL32.dll
    USER32.dll
    api-ms-win-core-synch-l1-2-0.dll
    bcryptprimitives.dll
    msvcrt.dll
    ntdll.dll
    USERENV.dll
    WS2_32.dll

These dependencies could be reduced further, but I don't expect people to (really) run this from Windows 3.1, and I'm not willing to give up Rust's threading primitives. This compromise works: system DLLs present on all Windows 10+ machines, no redistributables required.

Installation

The project includes NSIS installer scripts with automated build tools for both PowerShell and Bash. The scripts handle dependency downloads (fetching wlines-daemon.exe from releases), Rust compilation, and packaging:

.\build-installer.ps1

Windows startup methods are fragmented, and each has different privilege requirements and failure modes:

Method	Privilege Required
Registry	user
Task Scheduler	user
Startup folder (User)	user
Startup folder (All users)	admin

Group Policy might block Task Scheduler but leave registry keys open. IT policies might lock down the registry but allow startup folder scripts. Some systems restrict everything except one method. Four options mean at least one works (hopefully).

The graphical installer covers the basics: binaries, dependencies, startup method options, uninstall support, and Start Menu shortcuts. It cleans up all startup methods on uninstall while preserving user-edited configuration files.

For users who prefer manual control, windmenu's CLI offers the same functionality:

windmenu daemon all enable registry
windmenu daemon all enable task
windmenu daemon wlines enable user-folder

The NSIS installer provides a graphical interface for these operations, while the CLI remains available for scripting and power users.

What's Next

The current version of Windmenu is stable and daily-driveable. It's fast, configurable, and stays out of the way.

Some features I'm considering:

Frecency-based sorting: Frequently and recently used apps should float to the top
WiFi network switching: At some point during development, I thought "What if I could control WiFi networks from the launcher?" This led to implementing the wlan.rs module using Windows Native WiFi API. It wraps unsafe FFI calls in a safe Rust API with proper RAII cleanup via the Drop trait. Right now it supports forcing WiFi scans (useful for refreshing available networks), but what I really want is full network management (selecting and connecting to specific networks directly from Windmenu without touching the system tray). The infrastructure is there, waiting for the connection management pieces to be wired up.
Fast file search: Using ripgrep, maybe, avoiding the bloat of Windows indexing
System tray control: Managing visibility and lifecycle of system tray applications

But the core seems solid (on my machine, anyway). It does what I needed: provides a dmenu-like experience on Windows without compromise.

Conclusions

Building Windmenu scratched a personal itch while exploring Windows system programming in Rust. What started as "I want dmenu on Windows" became a deep dive into Windows internals, daemon architecture, and building distributable system tools.

This project has been a learning journey, particularly around Win32 APIs, process management, and Rust's concurrency primitives on Windows. I'm still learning the nuances of Windows system programming, so if you spot areas for improvement or have suggestions about better approaches, I'd genuinely appreciate the feedback.

If you're tired of Windows start menu, give Windmenu a try. It's fast, minimal, and keyboard-first.

Windmenu is available on GitHub. The installer includes everything you need to get started. If you find it useful, contributions and feedback are always welcome.

There's also Copilot integration in the search now. Another AI layer sitting between you and your programs, analyzing search behavior to suggest actions. The taskbar search is being replaced with "Ask Copilot" - more processing, more latency, more things you didn't ask for. ↩
Of course, ideas flourished while I was working on it and now I do many other things with it, but this illustrates the core need. (We'll talk about how I use Emacs on Windows another time, I don't want to go off topic). ↩

Kaomel: a snappy kaomoji picker for Emacs

Giovanni Crisalfi — Wed, 13 Aug 2025 18:01:31 +0000

I always liked kaomojis, but I never liked using the mouse to pick an emoji of any kind. Actually, I just don't like using the mouse. So I thought I could access the kaomoji world through Emacs keymagic. What started as "wouldn't it be nice to have a kaomoji picker in Emacs?" became a journey that would consume more weekends than initially planned.

Origins

The idea struck me in July 2023, but considering Emacs's long history, I knew someone had probably built something like this already. Sure enough, I found kaomoji.el, but its dataset was much smaller than my local collection, and it required Helm while I was using Vertico.

I could have forked it, but that would mean rewriting the interface layer and adapting to their dataset structure: basically everything. So I chose to design from scratch.

In my mind, the real goal was bigger: plug my dataset into any input interface. Why not dmenu? Why not windmenu? (I'm working on it.) Why not the CLI? I want my kaomojis everywhere. Sure, I prefer staying in Emacs, but we all know sometimes you're forced to venture outside your parentheses-wrapped sanctuary.

Before diving into implementation, I had to establish the non-negotiables. Two constraints would drive every subsequent decision: interface flexibility and dataset extensibility. These weren't features you could retrofit; they were architectural decisions that needed to be right from the start.

The first concept seemed simple enough: parse a JSON dataset of kaomojis, present them through a fuzzy-searchable interface, then insert the selection at point or copy to clipboard. These problems could have adapted perfectly to any textual interface.

But as I dove into the implementation, what seemed like a weekend project revealed layers of interesting problems that would define the entire architecture.

Architecture

Completion flexibility meant the package had to work equally well with Vertico, Helm, or any future completion framework. This wasn't about supporting every possible interface, it was about designing abstractions that didn't lock users (and developers) into specific tools.
Dataset extensibility meant the structure had to accommodate languages I hadn't thought of yet. Today it's Japanese, English and Italian; tomorrow it might need Arabic script or emoji modifiers. The data model needed to be future-proof.

Dataset

My first challenge was the data itself. I looked around for existing kaomoji datasets, hoping someone had already solved this problem. What I found was a constellation of different approaches. Projects like kao used structured text files that were clean and human-readable, serving their Japanese-focused community well:

@?          （？〜？         顔文字
@あ?        (๑•ૅㅁ•๑)ぁ？    顔文字
@あめ       ⋰⋰ ☂ (ృ ˘ ꒳ ˘  ృ 　)ु  ⋱⋱    顔文字
@ありがとう  (*ゝω・)ﾉ ｱﾘｶﾞ㌧♪    顔文字

This wouldn't work for my multilingual ambitions (someone searching for "thank you" or "grazie" would find nothing) but I appreciated the clarity of the tab-separated format.

The dataset that came closest to my vision was from the kaomoji-vscode extension. It had the structured JSON I wanted, with tags that could support search.

The original extension was designed to randomly pick one kaomoji from the array when a user selected a tag. This made sense for their use case—users would get variety without having to choose between dozens of similar emoticons. But what caught my attention wasn't the random selection; it was how the structure kept the dataset maintainable and compact by grouping related kaomojis under semantic tags.

From the beginning, I knew the JSON would just be a source format, a way to organize and maintain the data that I'd transform into an optimized Emacs Lisp vector at runtime. This pre-processing approach gave me the freedom to make the dataset more compact and maintainable without being constrained by the original structure in the Lisp realm:

[{
    "tag": "laugh 笑 哈哈",
    "yan": [
        "o(*≧▽≦)ツ┏━┓",
        "(/≥▽≤/)",
        "ヾ(o◕∀◕)ﾉ"
    ]
}]

But even this felt limited: tags weren't atomic; instead, they contained multiple languages and concepts in a single string. The "yan" field (containing the actual kaomojis) was an array, meaning each tag mapped to multiple emoticons. Having multiple kaomojis per semantic tag actually made sense: why should "laugh" map to just one emoticon when there are dozens of ways to express laughter?

The original VSCode extension would randomly select one kaomoji from this array when users picked a tag, adding an element of surprise and preventing the interface from becoming overwhelming. But I wanted users to see and choose from all available options (the whole point was having that rich, searchable collection at your fingertips).

This led me to think about the final Emacs Lisp structure: a vector where every kaomoji would have its full context available for instant search. In Emacs, users expect instant fuzzy matching across everything. That meant I needed a flat, searchable structure. The redundancy would be worth the maintainability.

Here's what a single processed entry looks like in the Emacs Lisp data structure (hash-table metadata stripped for clarity):

#s(hash-table data 
  ("tag" [
    #s(hash-table data ("orig" "laugh " "hira" "laugh " "kana" "laugh " 
                        "hepburn" "laugh " "kunrei" "laugh " "passport" "laugh "
                        "en" "laugh " "it" "ridere"))
    #s(hash-table data ("orig" "笑" "hira" "わらい" "kana" "ワライ" 
                        "hepburn" "warai" "kunrei" "warai" "passport" "warai"
                        "en" "笑" "it" "笑"))
    #s(hash-table data ("orig" "哈" "hira" "ごう" "kana" "ゴウ" 
                        "hepburn" "gou" "kunrei" "gou" "passport" "gou"
                        "en" "哈" "it" "哈"))
  ])
  ("yan" ["o(*≧▽≦)ツ┏━┓" "(/≥▽≤/)" "ヾ(o◕∀◕)ﾉ"]))

The kaomoji got tagged not just with "laugh" in English, but with わらい in hiragana, ワライ in katakana, and "ridere" in Italian.

This dataset structure made it trivial to add new languages later. Want French support? The mapping system is already there - just add "rire" to the semantic space alongside "laugh" and "わらい". The beauty is that users can mix and match these language preferences without any structural changes to the core data.

This multilingual-first approach became crucial when I realized different users would want different tag languages displayed. Some prefer English for readability, others want the original Japanese for authenticity, and some want romanization for typing efficiency. This new model had the proper flexibility from the beginning, making it straightforward to support all these preferences simultaneously.

Romanization

Early in development, I got excited about romanization. Why not convert "笑" to "warai" automatically, making the dataset searchable by romaji? My first approach was to integrate Python bindings for the Romkan package directly into the runtime vector build process: every time kaomel loaded, it would generate romanized versions on the fly.

But this felt heavy. Why introduce Python dependencies when I could handle romanization in pure Emacs Lisp? This led me to create romkan.el, my own package for Japanese-romaji conversion that worked entirely within Emacs.

Even after building a working Emacs Lisp solution, I realized there was an even cleaner approach. Instead of adding romkan as a runtime dependency (requiring users to install another package) I used it as a development tool. I ran the conversions once during dataset preparation, then baked the romanized results directly into the static dataset. This kept kaomel completely dependency-free while still providing full romanization support.

At this point, could I have done it all with the Python Romkan? Yes. Do I care? No.

Completion flexibility

The Emacs ecosystem has been shifting toward completing-read and frameworks like Vertico, but many packages still assume Helm as the primary interface. Helm, while powerful (and honestly beautiful), is essentially a parallel universe with its own conventions and complexity.

I decided to embrace the modern direction both because I think it represents the cleaner architectural path (and, as I said before, because I was using Vertico myself), while still supporting both approaches.

So I built kaomel with automatic Helm detection when available. The package picks Helm if it finds it, but users can force completing-read via kaomel-avoid-helm. This way, whether you're team Vertico or team Helm, kaomel works seamlessly with your preferred completion framework.

Text Alignment

One detail that consumed far more time than expected: text alignment. When you're displaying both English tags and kaomojis, string length calculations become tricky. The tag "laugh 笑" and the kaomoji "(/≥▽≤/)" don't behave the same way in terms of display width.

Emacs provides string-width for display-aware measurements, which was the key to solving this. Instead of naive character counting, I used string-width to calculate actual display width, then padded everything to achieve consistent alignment. Whether you're looking at "laugh 笑" or "ಠ_ಠ disapproval", the spacing stays visually consistent. These details matter when you're building something people use dozens of times per day.

Configuration

The configuration system turned out to be more important than I initially expected. I tried to provide a high degree of customization while building what I thought were sensible defaults. Instead of hard-coding interface choices, I made the key aspects customizable:

Which completion framework to use (kaomel-force-completing-read)
Which tag languages to display (kaomel-tag-langs) - supporting original, hiragana, katakana, English, Italian, and romanization formats
Whether to filter ASCII-only tags (kaomel-only-ascii-tags)
How aggressive tag trimming should be (kaomel-heavy-trim-tags)
Visual formatting options like separators (kaomel-tag-val-separator, kaomel-tag-tag-separator)
Custom prompts (kaomel-prompt) and candidate limits (kaomel-candidate-number-limit)

This was user-friendly design that happened to encourage clean abstractions. By making these choices configurable, I had to ensure the code worked correctly regardless of user preferences, which led to a more robust implementation.

For detailed documentation of each configuration option, see the Configuration section in the README.

Literate Programming

The early development followed a literate programming approach, with all exploration happening in an org-mode document mixing prose, code blocks, and results. This wasn't just note-taking, it was thinking through code, documenting each decision as it happened.

Each code block could be evaluated in place, with results appearing inline. Want to test JSON parsing? Write a block, execute it, see the output. Need to try different data structures? Compare approaches side-by-side with immediate feedback. This resembles the classic Lisp REPL workflow but with all the organizational benefits of org-mode. The development document became a living laboratory.

This approach proved invaluable for a project involving data transformations. Instead of jumping between files, everything lived in one navigable document. The prose explained the reasoning, the code showed the implementation, and the results validated the approach.

Developing in Emacs Lisp has a unique rhythm, and literate programming amplifies it. The edit-eval-test cycle is instant, encouraging experimental development. When I could test a search query instantly, I noticed performance issues early. When I could try different tag arrangements in real-time, I found the most readable format quickly. The org document is a thinking space where ideas can be explored, tested, refined, and documented simultaneously.

What's interesting is how this approach naturally captured feature evolution (which led to this blog post).

Tooling

As the lisp snippets crystallized into a proper package, I found myself needing tools that could work outside my personal Emacs environment.

I'm traditionally a shell person when developing anything, and I like keeping that solid shell alternative in Emacs development too. No surprise I'm a Doom Emacs admirer: there's something deeply satisfying about typing ./doom doctor and watching it methodically check your entire configuration, so I initially adopted that approach for kaomel.

# I used it to regenerate kaomel-data.el
# It just wrapped the `kaomel-dev-regenerate-data` batch call
./kaomel-data-gen.sh gen

But I further simplified this by embracing eldev fully. Eldev has builders specifically designed for generating files from sources, and I always prefer writing Lisp instead of bash wrappers:

(eldev-defbuilder kaomel-data-generator (source target)
  :short-name     "data"
  :source-files   "kaomel-data.json"
  :targets        ("kaomel-data.json" -> "kaomel-data.el")
  :collect        ":default"
  (load-file "kaomel-utils.el")
  (kaomel-dev--generate-data-file source target))

This integrates perfectly with eldev's build system:

eldev build          # Generates kaomel-data.el if kaomel-data.json changed
eldev test           # Run tests
eldev lint           # Run linter
eldev compile        # Compile to bytecode
eldev clean data     # Clean generated files

This approach comes in handy for CI/CD too (no need to figure out how to invoke Emacs batch commands from scratch when you already have a working interface through eldev).

Conclusions

After using it in my daily workflow and letting it mature through real-world use, it's time to share what became a surprisingly robust little package. The final package is focused: a main .el file plus a separate data file containing the processed kaomoji dataset. No complex dependencies beyond Emacs, no external processes, just pure Emacs Lisp doing what it does best: text manipulation and user interaction.

Kaomel try following principles I value in Emacs packages: focused functionality, standard-compliant interfaces, and respect for user choice. Instead of imposing a particular workflow, it integrates with whatever completion framework users prefer.

The current package works well for daily use and feels ready for a 1.0.0 release, but I think there's room for more features. During early phases, I sketched out several ideas that could add value: easier selection for frequently used kaomojis, usage statistics, more sophisticated tagging. The clean separation between data processing and interface presentation means adding new features wouldn't require fundamental changes to the core architecture (at least, they shouldn't).

What started as a simple utility became an occasion to explore different completion systems, Unicode strings handling, and (once again) the particular pleasures of lisp development. After using it daily for months, it's proven stable and useful enough to share. Also, I now have perfect kaomoji selection at my fingertips ｡◕‿◕｡

Kaomel is available on GitHub and I've submitted the recipe to MELPA. If you're curious about the implementation details or want to contribute, the codebase is here.

Building Testable Telegram Bots with Zustand

Giovanni Crisalfi — Mon, 04 Aug 2025 00:08:51 +0000

When most developers think of Zustand, they picture React hooks and component state. But what if I told you that Zustand's vanilla store could power a sophisticated Telegram bot with predictable state management and reactive behavior?

How It All Started

This project began with two unrelated moments that collided perfectly. I was deep-diving into Zustand's internals, trying to understand how createStore worked under the hood (the vanilla API that powers React hooks). Around the same time, my girlfriend complained about yet another obnoxious QR code website with ads, paywalls, and questionable privacy practices.

"Challenge accepted!" I announced to my reflection in the black screen of my laptop. The challenge hadn't even been issued. I was literally having a conversation with myself, in my mind, and it totally changed the trajectory of my next few days. But that's how the best projects start, with a completely unprompted moment of caffeinated hubris at 2 AM.

But instead of building another web app, I thought: What if I made this a Telegram bot? It would be easier for her whole team to use than deploying a desktop app or a website and it would be easier for me to craft, since I wouldn't need to worry about UI niceties.

Bot Complexity Gets Messy Fast

Building a Telegram bot seems simple at first. Handle a message, generate a response, send it back. But as features grow, you quickly encounter:

Stateful conversations (settings modes, multi-step flows)
Async operations (file I/O, in this case: QR generation)
Request tracking (knowing what's processing, completed, or failed)
User preferences (per-chat settings, format choices)

I considered existing libraries and frameworks, but I had a specific goal: I wanted something heavily testable from day one. My girlfriend's team would depend on this for their workflow, so I couldn't risk shipping something buggy or unreliable. Moreover, I was pretty busy with work, so I had just a weekend to make it operational and leave it live on my server before Monday. I needed architectural patterns that would give me confidence in the code's correctness.

The question became urgent during the initial development phase when I asked myself: How do you unit-test a bot? Traditional bot code is a nightmare to test: it's all side effects, network calls, and stateful interactions mixed together. Of course, pure functions are infinitely easier to test than side-effect heavy code.

After some studying, I thought that the Elm unidirectional pattern would work perfectly not only for UIs, but for bots too. (Don't worry if you're not familiar with Elm, I'll explain the pattern in the next section.) Writing a backend in Elm isn't that immediate and I wanted a dynamic language with a rich library system to go as fast as possible.

I considered TypeScript; it would give me the type safety I wanted while keeping the flexibility of a dynamic ecosystem. But then it hit me: I had been using Zustand to encapsulate business logic in React apps through pure state actions (I wrote about this approach in detail in my post on Building Robust React Apps with Zustand and Immer). What if I could apply the same approach to a bot? Zustand's vanilla createStore API could give me pure functions for business logic while keeping all the messy I/O operations separate and reactive.

This looked like the perfect occasion to practice TypeScript and explore Zustand outside React. I was curious whether Zustand's specific advantages (vanilla store API, Immer integration, reactive subscriptions) could bring the same clarity to bot development that they bring to React apps.

What started as a quick weekend project became an architectural experiment that showed me how Zustand could work beautifully in backend contexts.

Let me walk you through what I experimented.

Zustand in the outer world

Zustand's createStore function works perfectly outside React:

import { createStore } from 'zustand/vanilla';
import { produce } from 'immer';

export const store = createStore<State & Actions>((set, get) => ({
  // Initial state
  chats: [],
  requests: [],

  // Actions
  newRequest: ({ id, chatId, text, format }) => set(
    produce((state) => {
      state.requests.push({
        id, chatId, text, format,
        state: RequestState.New,
        response: null
      });
    })
  ),

  processRequest: (id) => set(
    produce((state) => {
      const req = state.requests.find(r => r.id === id);
      if (req) req.state = RequestState.Processing;
    })
  )
}));

No hooks, no components, just pure state management.

The code is TEA!

The bot follows a unidirectional data flow that any Elm developer would recognize:

User Message → Update → Model → View (Bot Messages)

This is The Elm Architecture (TEA) adapted for Telegram: same principles, different runtime. If you're more familiar with Redux, it's the same pattern (Redux was inspired by Elm): actions trigger reducers that update state, which then triggers view updates (in this case, Telegram messages instead of DOM updates).

Here's how a QR request flows through the system:

// 1. User sends message
bot.on('message', (msg) => {
  const { id, chat, text } = msg;

  // 2. Create request (triggers state change)
  store.getState().newRequest({ id, chatId: chat.id, text, format });

  // 3. Start processing (triggers another state change)
  store.getState().processRequest(id);

  // 4. Generate QR asynchronously
  store.getState().genQr({ text, format })
    .then(response => store.getState().completeRequest({ id, response }))
    .catch(error => store.getState().abortRequest({ id, error }));
});

(Yeah, I like sugarfree promises.)

Reactive State Subscriptions

Instead of manually checking state or using callbacks, the bot reacts to state changes, like those mechanical turrets in Portal that snap the moment they detect your movements through the glass.

"Are you still there?"

First, we set up a subscription that listens for any changes to the store:

store.subscribe((state) => {
  const currentRequests = state.requests;

  currentRequests.forEach(currentRequest => {
    const previousRequest = previousRequests.find(r => r.id === currentRequest.id);

    if (previousRequest?.state !== currentRequest.state) {
      handleStateChange(currentRequest, previousRequest);
    }
  });

  previousRequests = currentRequests;
});

This subscription fires whenever the store state changes. We compare the current requests with the previous snapshot to detect state transitions (when a request moves from New to Processing, or from Processing to Completed).

When a state change is detected, the bot automatically responds:

const handleStateChange = (request, previous) => {
  switch (request.state) {
    case RequestState.Processing:
      bot.sendMessage(request.chatId, "🔄 Generating your QR code...");
      break;

    case RequestState.Completed:
      bot.sendPhoto(request.chatId, fs.createReadStream(request.response));
      break;

    case RequestState.Error:
      bot.sendMessage(request.chatId, "❌ Something went wrong!");
      break;
  }
};

Note: This is a simplified representation. The actual implementation also manages animated loading indicators, handles file cleanup, and includes additional error recovery logic (check the code to see how).

State Machine Pattern in Action

Each request follows a clear lifecycle:

export enum RequestState {
  New = 0,
  Processing = 1,
  Completed = 2,
  Error = 3
}

These states create a simple but effective state machine that prevents invalid transitions and makes the bot's behavior predictable. You can't accidentally send a "completed" message for a request that's still processing.

Now that I think about it, there are more idiomatic ways to represent a RequestState in TypeScript, like string literal unions ('new' | 'processing' | 'completed' | 'error'), but I did like the idea of using a C-like enum when I wrote the bot, so... We'll leave it as it is.

Multi-Mode Conversations

The bot supports different conversation modes (normal QR generation vs. settings configuration) through state:

export enum ChatMode {
  Normal = 0,
  Settings = 1
}

// When user enters settings
bot.onText(/\/settings/, (msg) => {
  store.getState().setChatMode(msg.chat.id, ChatMode.Settings);

  // Bot commands change dynamically
  bot.setMyCommands([
    { command: '/set_png', description: 'Set PNG format' },
    { command: '/set_svg', description: 'Set SVG format' }
  ], { scope: { type: 'chat', chat_id: msg.chat.id } });
});

The store tracks each chat's mode, and the reactive subscription updates bot behavior accordingly.

Testing: The Real Reason I Chose This Architecture

Traditional bot code mixes core logic with I/O operations:

bot.on('message', async (msg) => {
  if (isProcessing[msg.chat.id]) return;

  isProcessing[msg.chat.id] = true;
  await bot.sendMessage(msg.chat.id, 'Processing...');

  try {
    const qr = await generateQR(msg.text);
    await bot.sendPhoto(msg.chat.id, qr);
  } catch (error) {
    await bot.sendMessage(msg.chat.id, 'Error!');
  }

  delete isProcessing[msg.chat.id];
});

Testing this requires mocking the bot, filesystem, and network calls:

describe('Traditional Bot Handler', () => {
  let mockBot;
  let mockFs;

  beforeEach(() => {
    mockBot = {
      sendMessage: jest.fn().mockResolvedValue({}),
      sendPhoto: jest.fn().mockResolvedValue({})
    };
    mockFs = {
      writeFile: jest.fn().mockResolvedValue(undefined)
    };
    isProcessing = {}; // Reset global state
  });

  it('should handle message processing', async () => {
    const msg = { chat: { id: 123 }, text: 'test' };

    // Test becomes complex due to async operations and mocks
    await messageHandler(msg);

    expect(mockBot.sendMessage).toHaveBeenCalledWith(123, 'Processing...');
    // How do we test the QR generation without actual file I/O?
    // How do we verify the processing state without exposing internals?
    // How do we test error scenarios without triggering real network failures?
  });
});

The traditional approach forces you to mock everything and makes it difficult to isolate application logic from side effects.

With Zustand's pure functions, testing becomes straightforward:

describe('QR Request Lifecycle', () => {
  beforeEach(() => {
    store.setState(store.getInitialState());
  });

  it('should handle request lifecycle correctly', () => {
    store.getState().newRequest({ 
      id: 1, chatId: 123, text: 'test', format: QrFormat.Png 
    });

    expect(store.getState().requests).toHaveLength(1);
    expect(store.getState().requests[0].state).toBe(RequestState.New);

    store.getState().processRequest(1);
    expect(store.getState().requests[0].state).toBe(RequestState.Processing);

    store.getState().completeRequest({ id: 1, response: '/path/to/qr.png' });
    expect(store.getState().requests[0].state).toBe(RequestState.Completed);
    expect(store.getState().requests[0].response).toBe('/path/to/qr.png');
  });

  it('should prevent overload', () => {
    // Create 5 requests (hitting the limit)
    for (let i = 1; i <= 5; i++) {
      store.getState().newRequest({ 
        id: i, chatId: 123, text: `test${i}`, format: QrFormat.Png 
      });
    }

    expect(store.getState().state).toBe(BotState.Idle);

    // 6th request should trigger overload
    store.getState().newRequest({ 
      id: 6, chatId: 123, text: 'test6', format: QrFormat.Png 
    });

    expect(store.getState().state).toBe(BotState.Overloaded);
  });
});

Why This Works

My philosophy was simple: don't test Telegram APIs (that's their job), test my core functionality.

Predictable Testing:

No side effects - Functions only change state, nothing else
No mocking - No external dependencies to stub
Fast execution - No network calls or file I/O in core operations
Deterministic - Same input always produces same output

Separation of Concerns:

Application logic lives in pure store actions
Side effects (Telegram API calls, file generation) happen in reactions
Easy isolation - Test core logic separately from integration

This testing approach caught several bugs during development:

Edge cases in overload handling
Invalid state transitions that could crash the bot
Race conditions in concurrent request processing
Subtle bugs in request lifecycle management

Built for the Future

The beautiful part? This architecture seems scalable. Same store, different clients. Same logic, different interfaces. The store that powers the Telegram bot could power:

A CLI tool
A React web interface for bulk QR generation

and other React-based UIs like Electron-ish desktop apps or React Native mobile apps.

The core logic (request lifecycle, QR generation, state management) remains identical across all clients.

Library Choice

You might be wondering about my library choice. I used the lower-level node-telegram-bot-api rather than the higher-level Telegraf. This decision actually reinforces the architectural approach.

I chose the lower-level node-telegram-bot-api:

import TelegramBot from 'node-telegram-bot-api';

const bot = new TelegramBot(process.env.TELEGRAM_TOKEN, { polling: true });

bot.onText(/\/start/, (msg) => {
  bot.sendMessage(msg.chat.id, 'Welcome!');
});

bot.on('message', (msg) => {
  // Raw message handling - you build the patterns
});

Compare that to Telegraf's opinionated patterns:

import { Telegraf } from 'telegraf';

const bot = new Telegraf(token);

bot.start(ctx => ctx.reply('Welcome!'));
bot.on('text', async (ctx) => {
  await ctx.reply('Processing...');
  try {
    const qr = await generateQR(ctx.message.text);
    await ctx.replyWithPhoto({ source: qr });
  } catch (error) {
    await ctx.reply('Error!');
  }
});

Why node-telegram-bot-api?

Unopinionated
Direct mapping to Telegram Bot API
Lightweight
Composable primitives (simple functions you can combine your own way)

Why Telegraf?

Battle-tested patterns
Rich middleware ecosystem (sessions, rate limiting, analytics)
Built-in error handling and recovery

Where Zustand/TEA Architecture Shines

We've already covered the testing advantages extensively. Beyond that, this architectural approach provides two key benefits that framework solutions typically can't match:

1. Multi-Client Architecture

// Same store powers bot AND future React web app
const store = createStore(/* ... */);

// Bot uses it
store.subscribe(handleBotStateChanges);

// React app uses it too
function useQRStore() {
  return useStore(store);
}

2. Observable State Machine

The reactive architecture makes it trivial to add new capabilities. Want to build a dashboard to monitor all bot activity? Just add another subscription:

// Every state transition is visible and reactive
store.subscribe((state) => {
  currentRequests.forEach(request => {
    if (request.state === RequestState.Completed) {
      sendQRToUser(request);
      logAnalytics(request);
      updateDashboard(request);
    }
  });
});

The Trade-off

Custom Architecture (with low-level APIs):

Control over every architectural decision
Support for every client type (bot + web + CLI)
Tracking for every state transition
Testing for every business rule
Maintainability for every future change
Setup for every pattern you need
Building for every abstraction you want

Telegraf Framework:

Rapid development
Rich ecosystem (middleware, scenes)
Battle-tested patterns
Built-in error handling
Framework lock-in
Less architectural flexibility
Harder to extend beyond bots

You could theoretically use Telegraf for the Telegram plumbing while keeping your state architecture, but at that point, it would be more reasonable to just embrace the framework style. I think the hybrid approach would add complexity without clear benefits.

Conclusions

Functional programming patterns aren't just for pure functional languages and some frontend libraries aren't just for frontend projects. State management, reactive programming, and unidirectional data flow solve problems wherever complex state exists, including bots.

The choice between framework convenience (Telegraf) and architectural control (custom Zustand) depends on your long-term goals. If you're building a system, not just a bot, the architectural investment provides a solid substrate for building complex systems.

Next time you're building something stateful outside the browser, consider bringing your frontend toolkit along.

Want to see the full implementation? Check out the source code and experiment with Zustand in your next non-React project.

Zeeman: a minimalistic periodic table focused on isotopes

Giovanni Crisalfi — Sun, 15 Jun 2025 12:59:01 +0000

There’s a peculiar frustration familiar to anyone who’s worked with spectroscopic techniques like EPR or NMR: the hunt for isotopic data. You need both the spin and natural abundance of every isotope for an element, but these critical numbers are scattered across PDFs, paper tables, or, even worse, different websites. It takes minutes to look them up! My programmer heart couldn’t bear such inefficiency.

Genesis

This profoundly inhuman struggle haunted me daily during my master’s thesis in Pharmaceutical Chemistry at the University of Bologna. Working with Prof. Lucarini’s group, we studied supramolecular compounds built from:

An organic host with a stable radical
An inorganic metallic guest

The stable radical made these compounds perfect for EPR spectroscopy, but the metal guests often had multiple isotopes, each with its own spin. While rewriting a DOS Monte Carlo simulator in Rust (a side project called Esrafel), I needed to simulate EPR spectra, which meant constantly cross-referencing isotope spins and abundances. My solution at the time? A Python CLI script that spat out isotope tables.

For the script, I paired a pristine natural abundance ASCII table from NIST with something far rougher: a hand-rolled dataset for spins I built from scratch. No tidy dataset existed, just inconsistent Wikipedia tables and textbook footnotes. I scraped, cleaned, and manually verified the values. Since I only cared about lab-relevant isotopes, I ignored the exotic ones only detectable in particle accelerators.

It worked fine, but it was CLI-only (fine for me, useless for anyone else). Years later, as a professional software developer, I was looking for a project to test my own abilities in representing data with a beautiful library, D3.js, especially using custom arcs and curves. Also, I thought that a table gets the job done, but a visual representation could make spin distributions intuitive at a glance. I envisioned a double pie chart: inner rings for isotopic abundance, outer arcs clustering isotopes by spin. The idea galvanized me, I had to build it.

So I did. Today I’m happy to finally share Zeeman: a free, interactive web app to make isotopic data as intuitive as a periodic table should be.

How It Works

Like any periodic table, start selecting an element; the central panel will update instantly with:

The element’s symbol
Its atomic number
A colorful thick inner ring
A sleek black outer ring

The inner ring displays isotopic abundances, while the outer ring represents nuclear spin clusters.

Navigation

Show Help: Explains the visualization logic.
Show Legend: Maps colors to nuclear spins.
Show Table, unlocks raw isotope data, displaying for each isotope:
- Mass number
- Relative atomic mass
- Spin
- Half-life
- Isotopic composition
Finally, the About button opens an about section.

Design Philosophy

Brutalist foundations:

Immediate, information-dense visualizations.
Flat, vibrant colors (no gradients)
High-contrast combinations

Under the Hood

For the tech-curious, this is the stack:

React - UI library (doesn't need introductions)
Zustand/Immer - state management with surgical updates and immutable safety
D3.js - powers my custom visualizations

I've already written about the beautiful Zustand/Immer combination.

By the way, Zeeman is open-source on GitHub. Contributions and forks are all welcome. Leave a star if you like the project!

On D3.js

Speaking of D3.js, it's not just another charting library, it's one of the most elegant libraries in the entire JavaScript ecosystem. New to it?

Explore live examples on Observable
Read the creator's canonical post Thinking with Joins to understand its data-binding paradigm

About that last link: While it references an older D3 version, every single line of the post remains relevant. The newer APIs simply wrap the same core logic more elegantly. As I use D3 for other work too, we'll likely discuss it again here.

Who’s Zeeman For?

Students exploring NMR/EPR isotope effects
Researchers needing quick access to isotope data
Educators creating interactive lessons

Where Next?

Mobile flow: Smoother touch interactions for lab tablets/phones
Desktop port: A single executable for offline use
Keyboard shortcuts: Faster navigation on desktop
Export: High-res graph images for publications

The name

The name pays homage to Pieter Zeeman, whose work on magnetic fields and atomic spectra laid the foundation for modern NMR/EPR techniques.

Conclusions

Zeeman bridges the gap between raw isotopic data and human intuition (no more scavenging through PDFs or wrestling with tables). It’s the tool I wish I’d had during my thesis, now polished for everyone from students to researchers.

Start exploring isotopes →

Building Robust React Apps with Zustand and Immer

Giovanni Crisalfi — Sun, 23 Mar 2025 22:30:20 +0000

Introduction

For years, I dodged React like the plague. In fact, I avoided JavaScript altogether, even in web-related tasks. Take static site generators, for example. For my old chemistry blog, I experimented with a variety of tools, year by year: Pelican, Jekyll, Hugo, Grav... In the end, I settled on Zola. Fast, robust, no JS needed, perfect for CI/CD workflows. Just prerendered HTML and sprinkle scripts for flair (e.g. comments, a masonry in the home page ecc.).

Rust’s elegance and stability, though less prominent in web development, shine through in Zola, more than compensating for any niche limitations.
This, however, is a particular case, since we're just presenting static content: basically, most of the work is collapsed on the backend. But actual web apps? Rust’s Yew or Dioxus are promising but young.

I love to find refuge in Elm's elegance and solidity, but recently, I’ve been drawn back to React and JavaScript, both professionally and in personal projects. Time constraints and the appeal of leveraging the extensive ecosystem of UI libraries have played a significant role in this shift. What I discovered was a React that had matured significantly, driven by its hook system and TypeScript support.

Particularly, I stumbled upon a couple of libraries that have the potential to transform even the most complex app development workflows: Immer and Zustand. In this post, I’ll show you how these two libraries interoperate seamlessly, enabling you to architect applications that transcend the entropic morass of lifecycle chaos that once defined React’s class components.

Zustand: a minimalist state solution

As a longtime admirer of Redux (and its Elm/Flux-inspired architecture), I initially leaned on its strict unidirectional flow. But Redux’s boilerplate often felt at odds with React’s evolving simplicity.

Let’s begin with the simplest case possible, something you can handle using a basic useState in React: a counter.

import { useState } from 'react';

function App() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increment</button>
    </div>
  );
}

export default App;

This example initializes a state variable count with an initial value of 0 and provides a button to increment it. How can you achieve the same with Zustand? First of all, you install Zustand.

npm install zustand
# or `bun add zustand`

The following code replicates the same behavior as the previous one.

import create from 'zustand';

const useStore = create((set) => ({
  count: 0,
  increment: () => set((state) => ({ count: state.count + 1 })),
}));

function App() {
  const { count, increment } = useStore();

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={increment}>Increment</button>
    </div>
  );
}

export default App;

useStore is created using zustand's create function.
It initializes a state with count: 0 and an increment function that updates count by 1.
In the App component, useStore is used to access count and increment.
The current count is displayed, and a button triggers increment when clicked.

This case resembles the previous one but has nuanced differences that become important in structured contexts. Unlike useState, which provides a dedicated value-setter pair, Zustand actions should encapsulate entire workflows rather than individual parameter updates (hence we call the action increment, not just setCount). More complex scenarios will illustrate this distinction clearly.

Effortless immutability with Immer

Zustand simplifies state management, yet its requirement for immutable updates in JavaScript can feel like a labyrinthine chore, especially when dealing with nested state — which is basically all the time. Immer operates like a tiny JavaScript alchemist, transmuting mutable-like code into immutable state updates.

Let’s revisit the counter example, but this time, imagine we need to manage a more complex state object:

import { useState } from 'react';

function App() {
  const [state, setState] = useState({ count: 0, history: [] });

  const increment = () => {
    setState((prevState) => ({
      count: prevState.count + 1,
      history: [...prevState.history, prevState.count],
    }));
  };

  return (
    <div>
      <p>Count: {state.count}</p>
      <button onClick={increment}>Increment</button>
    </div>
  );
}

export default App;

Here, we’re updating both count and history, which requires manually spreading and nesting state. This quickly becomes error-prone as state grows more complex.

With Immer, the same logic becomes cleaner and more intuitive. First, install Immer:

npm install immer

Now, let’s rewrite the increment function using Immer. Import produce:

import { produce } from 'immer';

Use produce:

const increment = () => {
    setState(
        produce((draft) => {
            draft.count += 1;
            draft.history.push(draft.count - 1);
        })
    );
};

produce takes a "draft" of the state, allowing you to write mutable-style code.
The draft is basically a proxy, and Immer automatically generates the next immutable state for you.
This eliminates the need for manual spreading and nesting.

Immer shines in scenarios where state is deeply nested or requires frequent updates. Its symbiosis with Zustand will become noticeable when we explore the middleware provided by Zustand itself.

I Saw the Canvas Glow: a practical example

Let’s design a slightly more complex scenario.

The challenge

We want a web app where users can interact with a canvas. When a user clicks on the canvas, a point is added.

// These are private variables declared somewhere
let isLoading: boolean;
let points: Point[];

// Points are added exclusively through this exported function
const addPoint = (point: Point) => {
    // Add the point to the list of points
    points.push(point)
}

// A function to reset the state
export const very_rude_reset = () => { points = [] };

// You maybe want a function to reset the state
export very_rude_reset = () => { points = [] };
// You may want additional functionality, but let's focus on the main part
// * adding points *

What’s the problem? Before storing the point, we need to perform a check on a remote server. This could take some time. However, we shouldn’t let this hinder us from developing a reactive application. The GUI must remain responsive and should provide feedback to the user, indicating that the app is working without appearing sluggish.

So, when a point is added, the app enters a loading state, waiting for the server’s response.

You can see the app in action right here.

How does all of this work?

To not overcomplicate the example, we simulate the server call with a timeout of 10 seconds, like this:

let isLoading: boolean;
let points: Point[];

export const addPoint = (point: Point) => {
    if (!isLoading) {
        // We're now loading again
        isLoading = true;

        // Instead of this fetch...
        // fetch('/api/update', {
        //     method: 'POST',
        //     headers: { 'Content-Type': 'application/json' },
        //     body: JSON.stringify(newPoint),
        // })
        // ...a handcrafted promise:
        new Promise((resolve) => {
            // Emulating a 10 seconds job
            setTimeout(() => {
                resolve();
            }, 10000);
        }).then(() => {
            // Adding point to the list of points...
            points.push(point)
        }).then(() => {
            console.log("Job completed after 10 sec. Ready again.");
            isLoading = false
        })
        ;
    }
}
// Other desirable actions...

See? Very simple. This way, we can test how out application behave in the worst case scenario.

Some (OOO people) might argue that this could be represented with a class and solved using encapsulation in an object, but we intentionally avoided that approach because we’re taking the functional path. Let’s look at the real implementation.

The component

We're working in React (you didn’t forget, did you?). Let’s take a look at the main App component, which handles canvas rendering and user interactions:

import { useRef, useEffect } from 'react'; // Everyday stuff
import { useStore } from './Store'; // <-- Zustand store!
// (We'll explore it right below)

function App() {
  const canvasRef = useRef<HTMLCanvasElement>(null);
  const { isLoading, points, addPoint, message } = useStore();

  // Effect for animations and aesthetic stuff
  // useEffect(() => { ... })

  // Handle left-click on the canvas to add a node
  useEffect(() => {
    const canvas = canvasRef.current;
    if (canvas) {
      const handleMouseClick = (event: MouseEvent) => {
        switch (event.button) {
          case 0: // Left click
            addNode({
              X: event.clientX,
              Y: event.clientY,
            });
            break;
          default:
            break;
        }
      };
      canvas.addEventListener('mousedown', handleMouseClick);
      return () => {
        canvas.removeEventListener('mousedown', handleMouseClick);
      };
    }
  }, []);

  // JSX with a title, message, canvas, and list of points
  return ("[...]")
}

You might have noticed the logic is missing here: that's because it is now fully encapsulated within Zustand.

The store

We’ve already seen how the create function works: you define both state variables and actions (functions that modify the state) inside the create function. Next, let’s examine the Immer integration:

import { create } from 'zustand';
import { immer } from 'zustand/middleware/immer';

export const useStore = create(
  immer((set, get) => ({ // <-- Immer middleware
    message: "Click on the mysterious globe.",
    setMessage: (msg: string) => {
      set((state) => {
        state.message = msg;
      });
    },
    // Adding points: we’re almost there, wait just a little more!
  }))
);

Essentially, we're wrapping the state creation inside another function, giving us Immer’s capabilities without explicitly calling produce. In this example, we’re focusing on the message=/=setMessage pair, as it’s the simplest way (I could think of) to demonstrate state mutation using the Immer middleware in Zustand.

Let’s encapsulate the logic we’ve seen earlier using this approach:

import { create } from 'zustand';
import { immer } from 'zustand/middleware/immer';

export const useStore = create(
    immer((set, get) => ({ // <-- Immer middleware
        // [message/setMessage as before]
        // State variable for points
        points: [],
        // Adding points
        addPoint: (point: Point) => {
            const log = get().setMessage;

            // `isLoading` is now stored inside the store,
            // so we use the `get()` function
            // provided by the Immer middleware (up here)
            if (!get().isLoading) {
                set((state) => {
                    state.isLoading = true;
                    state.points.push(point);
                });
                log("Point pushed. Now loading...");

                new Promise((resolve) => {
                    // Emulate a 10-second job
                    setTimeout(() => {
                        resolve();
                    }, 10000);
                }).then(() => {
                    log("Job completed after 10 seconds. You can click again.");
                    set((state) => { state.isLoading = false; });
                });
            } else {
                log("Not now, my friend. I'm busy.");
            }
        }
    }))
);

We’ve done it! The addPoint action demonstrates handling asynchronous operations, such as the 10-second loading period (or, more realistically, a server call). Zustand doesn’t care whether your functions are synchronous or asynchronous (as long as they make sense).

Conclusions

In the end, Zustand and Immer make a strong pair for state management in React. Missing Rust/Elm’s guarantees? You’ll never fully replicate them in JS, but TypeScript, paired with modern tooling, partially bridges the gap. Zustand cuts through the noise with its clean, focused approach. Immer smooths out the rough edges of immutable updates, especially in nested states. Together, they let you build solid, fast apps with less code and fewer mistakes.

The discussed example demonstrates how these tools can handle both synchronous and asynchronous operations seamlessly. To explore the implementation further, check out the repository here. If you find it useful and enjoyed this blog post, don't forget to leave a star!

Getting Started with Hy, the Python Lisp: a Matplotlib example - Ep. 2

Giovanni Crisalfi — Thu, 10 Aug 2023 15:17:04 +0000

In the previous episode, we briefly saw what Hy is, what it means that it is a dialect of Lisp, how to install it, and step by step, we wrote a small example to create a line plot in matplotlib, strictly following the imperative approach we would have used in Python.

(import matplotlib.pyplot :as plt)
(setv x-values [1 2 3 4 5])
(setv y-values [2 4 6 8 10])
(setv [fig ax] (plt.subplots))
(ax.plot x-values y-values :marker "o")
(ax.set-xlabel "X values")
(ax.set-ylabel "Y values")
(ax.set-title "Simple Line Plot")

(plt.savefig "img/hy-plt-example.png")

If you don't understand something about the code above, I recommend referring to the first part: maybe something just went unnoticed until now.
If, instead, everything is clear, we can proceed. Now, it's time to make things more spicy by adopting a functional approach.

More precisely, we will begin by encapsulating everything in a let.

What is a let?

Before rewriting our code, it is important to understand what a "let" is and why it is so useful.
If you are already familiar with this concept, feel free to skip this paragraph and proceed directly to the code.

A "let" is a Lisp operator that allows you to create a lexical context with new local variables. Basically, it's like saying you want to call a function that can access these variables and prioritize these variable declarations over other external ones with the same name.

How does it works?

A let expression has two parts. First comes a list of instructions for creating variables, each of the form (variable expression). Each variable will initially be set to the value of the corresponding expression. [...]
After the list of variables and values comes a body of expressions, which are evaluated in order.
(Graham, ANSI Common Lisp, 1996, p. 20)

In Hy terms,

(let [x 2]
  (print x))

The x variable defined in the head of the let is not accessible outside it.

Actually, the Hy let is pretty special, because it makes you write variables that have access to the ones defined previously in the same expression.
For example,

(let [x 2
      y 3
      z (+ x y)]
  (print x)
  (print y)
  (print z))

As you can see here, the z variable is defined in relation to x and y.
As the documentation explains,

Like the let* of many other Lisps, let executes the variable assignments one-by-one, in the order written

This means that, as let* in other lisps, let in Hy is functionally equivalent to a series of pure nested lets.

Let('s) plot

Being conscious of how let works in Hy, we can now rewrite the initial code:

(import matplotlib.pyplot :as plt)

(let [x-values [1 2 3 4 5]
      y-values [2 4 6 8 10]
      [fig ax] (plt.subplots)]

  (ax.plot x-values y-values :marker "o")
  (ax.set-xlabel "X values")
  (ax.set-ylabel "Y values")
  (ax.set-title "Simple Line Plot")
  (plt.savefig "img/hy-plt-example.png"))

Remember that let blocks can be nested. For example, in the case we want to plot two identical graphs but with different labels, we could write:

(import matplotlib.pyplot :as plt)

(let [x-values [1 2 3 4 5]
      y-values [2 4 6 8 10]]

  ; English version
  (let [[fig ax] (plt.subplots)]
    (ax.plot x-values y-values :marker "x")
    (ax.set-xlabel "X values")
    (ax.set-ylabel "Y values")
    (ax.set-title "First Title")
    (plt.savefig "img/hy-plt-example-en.png"))

  ; Italian version
  (let [[fig ax] (plt.subplots)]
    (ax.plot x-values y-values :marker "o")
    (ax.set-xlabel "Ascisse")
    (ax.set-ylabel "Ordinate")
    (ax.set-title "Secondo titolo")
    (plt.savefig "img/hy-plt-example-it.png")))

This code saves two figures: an English one, and an Italian one.

Macros

Lisp code, including Hy code, is expressed as a series of lists. Its minimalist syntax (or rather, the lack of it) allows for easy writing of macros.
But what is a macro?

The most common way to write programs that write programs is by defining macros. Macros are operators that are implemented by transformation. You define a macro by saying how a call to it should be translated. This translation, called macro-expansion, is done automatically by the compiler. So the code generated by your macros becomes an integral part of your program, just as if you had typed it in yourself. (Graham, ANSI Common Lisp, 1996, p. 162)

In other words, macros are operators that write code and lisps are particularly good for metaprogramming, which means the code itself is treated as data that can be manipulated by itself, allowing for powerful generative techniques. This means also that we can build up our own language to make the code drier or more comfortable.

Lisp is designed to be extensible: it lets you define new operators yourself. (Graham, ANSI Common Lisp, 1996, p. 3)

Going meta

Let's see how we can leverage the power of macros in this case.
If you require a series of similar plots with only the title and filename being changed, you can write:

(import matplotlib.pyplot :as plt)

(defmacro plot-with-title [title fname]
  (quasiquote (let [[fig ax] (plt.subplots)]
    (ax.plot x-values y-values :marker "o")
    (ax.set-xlabel "Ascisse")
    (ax.set-ylabel "Ordinate")
    (ax.set-title (unquote title))
    (plt.savefig (unquote fname)))))

(let [x-values [1 2 3 4 5]
      y-values [2 4 6 8 10]]

  (plot-with-title "First title" "img/hy-plt-example-one.png")
  (plot-with-title "Second title" "img/hy-plt-example-two.png"))

We can dream bigger by creating abstractions for all line plots.

(import matplotlib.pyplot :as plt)

(defmacro lineplot [x y title fname marker xlabel ylabel]
  (quasiquote (let [x-values (unquote x)
                    y-values (unquote y)
                    [fig ax] (plt.subplots)]

                (ax.plot x-values y-values :marker (unquote marker))
                (ax.set-xlabel (unquote xlabel))
                (ax.set-ylabel (unquote ylabel))
                (ax.set-title (unquote title))
                (plt.savefig (unquote fname)))))

(lineplot [1 2 3 4 5]
          [2 4 6 8 10]
          "Titolo"
          "img/hy-plt-example-one.png"
          "o"
          "X values"
          "Y values")

As long as the macro definition is under your eyes, it's easy to understand the order in which to write the arguments. In this example: first the values for x and y, then the title, followed by the path of the image to be saved, the marker, and the labels. But this is just a simplified situation: usually, the macro definition is hidden in a library out of sight, so named arguments should be preferred over positional arguments.

Unfortunately, this is not directly possible in Hy because, as described in the documentation,

defmacro cannot use keyword arguments, because all values are passed to macros unevaluated. All arguments are passed positionally, but they can have default values:

(defmacro a-macro [a [b 1]]
  `[~a ~b])

;; (a-macro 2)
;; [2 1]
;; (a-macro 2 3)
;; [2 3]
;; (a-macro :b 3)
;; [:b 3]

Thankfully, there's a nifty workaround to achieve to have both the default values and the positional arguments.
Instead of them being assigned in the macro, we write a simple wrapper function. Then we use the function for:

Defining the default values;
Giving names to macro's positional arguments.

(import matplotlib.pyplot :as plt)

(defmacro macro-lineplot [x
                          y
                          title
                          fname
                          marker
                          xlabel
                          ylabel]
  (quasiquote (let [x-values (unquote x)
                    y-values (unquote y)
                    [fig ax] (plt.subplots)]

                (ax.plot x-values y-values :marker (unquote marker))
                (ax.set-xlabel (unquote xlabel))
                (ax.set-ylabel (unquote ylabel))
                (ax.set-title (unquote title))
                (plt.savefig (unquote fname)))))

(defn lineplot [x
                y *
                [title "Title"]
                [fname "fname.png"]
                [marker "o"]
                [xlabel "X values"]
                [ylabel "Y values"]]
  (macro-lineplot x y title fname marker xlabel ylabel))

The asterisk (*) tells which parameters need the key:

If the symbol * is given in place of a parameter, it means that all the following parameters can only be set by name.

In other words, we have assigned default values that can be overridden by using the key's name.

Ultimately, assuming the macro is externalized in a library, the original code simplifies to these practical and fully functional lines:

(lineplot [1 2 3 4 5]
          [2 4 6 8 10]
          :title "Simple Line Plot"
          :fname "img/hy-plt-example-last.png")

Of course, this is the simplest example I could think of, and there is room for a lot of improvement, but I think it makes the potential of the language and macros quite evident.
Moreover, keep in mind that the thrill lies in the fusion of these two powerful languages. By keeping the hy package as a dependency, Hy macros can be imported and used directly in Python code. This allows you to easily share the wrapper function with non-Hy users.

Conclusion

In this post, we have discussed how to effectively use lexical scoped blocks and macros. Macros provide a powerful tool for metaprogramming, allowing you to extend the language and write code that is both cleaner and more expressive. By understanding and utilizing these features in Hy, you will be able to write more reliable code while still benefiting from Python libraries.

Originally posted on Zwitterionic Digressions

Getting Started with Hy, the Python Lisp: a simple Matplotlib example - Ep. 1

Giovanni Crisalfi — Mon, 07 Aug 2023 13:41:02 +0000

Hy is a Lisp dialect that combines the expressive power of Lisp with the convenience and extensive libraries of Python.

It's cool because it doesn't transpile in Python, but converts the code directly into its abstract syntax tree (AST), so interoperability with libraries is guaranteed, and you don't have to deal with an intermediate layer of Python code.

I won't deliver a long theoretical speech about the beauty of Lisp on this occasion. If you're already familiar with Lisp dialects like Emacs Lisp, Common Lisp, Clojure, or Scheme, this is the place for you. If you've never heard of Lisp, this is a good place to start exploring its fundamentals by working with code firsthand.

Installation

First of all, we need to install Hy. Installing Hy is as simple as installing any library in Python.

pip install git+https://github.com/hylang/hy.git

The package provides a CLI tool for running Hy code by simply passing it the file name. Additionally, the package includes a terminal REPL that can be launched by entering hy in the shell, along with some other useful features. For comprehensive details, check hy --help. It is also possible to install Hy in a virtual environment if you prefer not to directly touch the system. Assuming the reader is familiar with Python, I won't explain the process of creating and managing a virtual environment. Instead, we can proceed directly to the code.

Importing a library

Imagine wanting to plot a simple series of points with Python. There are many libraries to achieve this, but Matplotlib is probably the most famous and widely used. So, the first thing we would write in Python is:

import matplotlib.pyplot as plt

Doing so, we would import the module pyplot from the library matplotlib and temporarily name it plt for brevity. In Hy, achieving the same result is straightforward: as in every other Lisp, each expression is enclosed in parentheses, with the first element acting as a function and the following elements as arguments. This simplicity makes the result quite intuitive.

(import matplotlib.pyplot :as plt)

Setting variables

Here, we set the point coordinates. We do this in two lists: one for the x-axis and the other for the y-axis. In Python, we would have written:

x_values = [1, 2, 3, 4, 5]
y_values = [2, 4, 6, 8, 10]

In Hy:

(setv x-values [1 2 3 4 5])
(setv y-values [2 4 6 8 10])

As you can see, the variables must be set with the setv (set variable) function.

Unpacking values

Now we aim to assign fig and ax simultaneously, conventionally denoted as fig and ax, which are returned by a method of plt called subplots(). In Python words:

# Create a figure and axis object
fig, ax = plt.subplots()

In other words, we have to master two operations: unpacking data from a function's return and executing a method.

Unpacking data is really simple, assign one list to another, ensuring equal values in both:

(setv [a b] [1 2])
;; (print a) => 1
;; (print b) => 2

It works with tuples too:

(setv [a b] (tuple [1 2]))

Calling methods

Calling an object method is, also in this case, quite simple. You use the same (short) notation that distinguishes the call in Python: plt.subplots(). However, in this case, instead of placing parentheses after the term to clarify that we are invoking a function, we place them surrounding the function itself, like this: (plt.subplots). This is the lispy way. Putting things together:

(setv [fig ax] (plt.subplots))

Now that the ax object has been created, we can call one of its methods to plot our values. This time, the method has arguments. In Python, we would write:

# Plot the data as a line plot
ax.plot(x_values, y_values)

Remembering that in every Lisp, the initial term within the grouping of parentheses assumes the role of the function, succeeded thereafter by the arguments, the same principale extends to methods, wich are -- indeed -- function themselves:

(ax.plot x-values y-values)

In this case, we may also want to specify a specific argument by name. We can do this by using a notation that should be familiar to us as it has already been seen in the import above.

(ax.plot x-values y-values :marker "o")

We are about to reach the conclusion.

Putting all together

All that remains is to recall other methods of ax to define the labels and the title.

(ax.set-xlabel "X values")
(ax.set-ylabel "Y values")
(ax.set-title "Simple Line Plot")

Finally, let's gather all the code we have written and cap it with a savefig to admire our effort's fruit.

(import matplotlib.pyplot :as plt)
(setv x-values [1 2 3 4 5])
(setv y-values [2 4 6 8 10])
(setv [fig ax] (plt.subplots))
(ax.plot x-values y-values :marker "o")
(ax.set-xlabel "X values")
(ax.set-ylabel "Y values")
(ax.set-title "Simple Line Plot")

(plt.savefig "img/hy-plt-example.png")

Conclusions

This first part was meant to be a gentle introduction for anyone, so I made sure to faithfully follow the style that would be adopted in Python. While switching to Hy may not immediately showcase its advantages, with patience, its benefits will become clear. In the next episode, we will code using a functional approach and then we will abstract the logic into a small macro. This will spare us from writing all the tedious boilerplate.

The second part is available both here on dev.to and on my blog.

Stay connected!

Originally posted on Zwitterionic Digressions

Scribbling pixels with Aseprite

Giovanni Crisalfi — Mon, 22 May 2023 23:52:18 +0000

Originally posted on zwitterio.it

I have been fascinated by pixel art since I can remember.
For years, I've been having fun experimenting with pixel art programs, and I fell in love with dithering when I started messing with my blog generator code.
More generally, I have always loved visual art, but lacking what I thought were the necessary artistic skills for traditional painting methods, I never thought I could personally make it.
Yet, exposure to the works of talented people on the Fediverse made me wonder about scribbling in pixels.

What if I tried crafting pixels by hand too?
What could go wrong? (Everything can go wrong, I have no time for doing this!, says a side of my mind I choose to blatantly ignore).

I really love GIMP, but my past attempts with GIMP have never led me very far.
Maybe it was because it is more general-purpose, so, never having done pixel art by hand, I wouldn't know how to adapt the workspace to the needs of my pixels.

Then Nico posted a screenshot of her Desktop.
While I was admiring her icon pack, I noticed this name: Aseprite.
When I looked up for it, I was blown away by the UI of this software: so vintage, so cool, I had to try it.
(I know, I know, I'm the type who gets hooked by a book cover.)

Here I want to leave my very first attempt at using Aseprite: a simple 16x16 binary image representing a molecule of 1,4-dioxane (basically the first thing I could think of).

Those are just some pixels scattered in a white field, but for my eyes, they hold a poetic charm.

Immediately after, I embarked on something more exciting: the faithful reproduction of my Mastodon profile picture into its corresponding pixel art; it represents a 4-eyed me through the lens of a CGA0 4-color palette.

Things escalated quickly and I tried pixelating everything: old logos, random images, pictures of hallways and so on.

For this burst of passion, I am grateful to the pixel artists of the Fediverse, and particularly Nico, who accidentally introduced me to this lovely software. Because of them, I now aspire to craft many more works.

Start Qute Now

Giovanni Crisalfi — Tue, 13 Dec 2022 23:06:05 +0000

A few days ago, I started using Qutebrowser. I mean using it for real. It wasn't my first installation: I tried it other times in the past, but I had never considered leaving Firefox. This time I'm using it as a daily driver, migrating my entire workflow into it.

Originally posted on zwitterio.it

But why I had this mad idea of leaving Firefox in the first place? Because it was the only software left that made me use the mouse systematically, over and over. Yeah, of course, you can set a lot of keybindings in Firefox, and you can install addons like Vim Vixen for getting to use it with the keyboard only, but you still feel the friction because the support isn't native, therefore every command has to be channeled through a lot of javascript subway sewers. It's not Firefox's fault, though: Firefox isn't imagined for a keyboard-only approach because it's not developed with that kind of user in mind. There is nothing wrong with it. Maybe, if old extensions weren't been abandoned, we could have had a way to shape it as a real keyboard-driven browser, but the total turning on WebExtension wasn't a choice really made by Mozilla, so let's avoid digressing. The point is: Firefox isn't a keyboard-driven browser, so we have to look elsewhere.

Even though keyboard-obsessed users like me really are a small population, it usually corresponds to a tenacious community of programmers, which explains the relative abundance of keyboard-oriented browsers: aside from Qutebrowser, we should also mention Surf, Nyxt (before called Next), forks of old Firefox like PaleMoon with the proper extensions and many others.

Unfortunately, the quantity doesn't automatically means plenty of choices because those browsers usually have some limitations in one sense or another. Among those, Qutebrowser seems like the most solid one to me. Qutebrowser has a series of strong points: it runs on PyQt5, which means it uses QtWebEngine, which is, in turn, based on Chromium. Being tied to using Chromium's engine is the thing that makes me itchy the most, and yet I have to admit it increases Qutebrowser compatibility with a lot of services while making it reliable from a security point of view too.

Thanks to the dedication of the author and maintainer, Florian Bruhin, and to a small but unresting community of developers and users, Qutebrowser already covers the principal needs: themes, bookmarks, dark mode, a good adblocking based on Brave Browser's Rust libraries too. Despite all that, you cannot expect an instant solution for every not-so-common problem like it happens with Chromium and Firefox extensions. In those cases, you don't have an alternative to working by coding. And that's where my actual journey with Qutebrowser begins. In this regard, see SwapForQute, my first userscript for Qutebrowser.

SwapForQute (or just SFQ) is an userscript for qutebrowser that replaces your URLs with new ones following an easy to set configuration.

For a detailed explanation of how to install it, how it works, how to build keybindings and so on, check the repo on GitHub.

If you want to go deeper in the rabbit hole, see my Qutebrowser literate configuration too.

(Photo by Jay Zhang on Unsplash)

Get user inputs in Emacs Lisp

Giovanni Crisalfi — Sun, 13 Nov 2022 19:44:23 +0000

Originally posted on zwitterio.it

This post is intended to give beginners (or anyone else) an introduction on how to use lisp to manage user's inputs on Emacs.

A simple interactive function

Imagine you want to write a simple interactive function to cheer up an Emacs' user.

(defun cheer-me-up ()
  (interactive)
  (message "You're great, keep it up!"))

(cheer-me-up)

Everytime we launch this one, the same result will be showed in the minibuffer:

"You’re great, keep it up!"

It works, but it can be boring on the long run.
Enhance the function by proposing a new catchphrase every time you launch it.

(defun cheer-me-up (goodvibes)
  (interactive "sEnter good vibes as string: ")
  (message goodvibes))

This way, the function will reflect your communication and optimism on yourself, by repeating exactly the expression you pass.

Every time the function will be launched by the user, the minibuffer of Emacs will ask for good vibes.

That's pretty basic, because we're just asking for a string and rethrowing it to the user without any check.

But what if the user isn't writing good stuff on the first place?
Maybe he needs this function precisely because it's all melancholical and gloomy.

Demand good vibes

We could introduce a check that excludes bad words from the input and replace it with good ones, but it wouldn't be easy.
Doable, but not easy.
Let's keep it simple for the moment: what if we ask the user something else?
Not a phrase, for example, but a number?

We could list a great number of positive phrases and ask the user for a number, which will be the index of the phrase in the list.
In this case, the input should be an integer.
How do we do that?

First of all, let's declare a list named goodvibes:

;; list of positive phrases
(setq goodvibes
      '("You're great!" "Keep it up!" "People loves you!"
        ;; It's better to comment out the following ones
        ;; "Shut up, nothing you say has value" "The world is an insane fabric of pain and we should destroy everything"
        ;; Ok, we can keep the last one
        "Nature is good, she's not a cruel mother and you must be happy to be alive. Of course."))

Now we have a total of 4 elements in the list and we want to access them from the function.
The function asks for an index, which should be an integer between 0 and 3.
What if the user doesn't know anything about the list up here and asks for a fifth element?
What if the user gives us a float number insted of an integer? Or, worst, what if the user writes off a numberless string?

(defun cheer-me-up (index)
  (interactive "sChoose a number, receive good vibes~ ")
  ;; We are asking for a string from the user, so this could be anything.
  ;; We must be sure it's an integer.
  <<format-input-as-integer>>

  ;; Isn't it possible to convert the string to an integer?
  ;; Tell the user!
  <<signal-no-number-error>>

  ;; Now we need to know the integer is not inferior to 0 or superior to 3
  (if (and (> index 0) (<= index 3))
      ;; if we pass the condition, good, print out your message
      (message (nth index goodvibes))
    ;; Else block:
    ;; if the number exceeds the range from a way or another, tell the user.
    (<<signal-out-of-range-error>>)))

To manage those cases, we need to know two concepts:

How to format strings (here in the GNU docs);
How to signal errors (here in the GNU docs);

You might say:

But reading documentation is bOrInG!

Don't worry, this time we will explore the topics practically here below; just follow me through the comments.

Formatting strings

Formatting as integer is pretty simple if you know how to format strings. From the docs:

Formatting means constructing a string by substituting computed values at various places in a constant string.

In this case, we want to require that the value is of a particular type and it can be checked specifying a format. %d, for example,

replace the specification with the base-ten representation of a signed integer. The object can also be a floating-point number that is formatted as an integer, dropping any fraction.

So, if the user gives us 1, we're fine. And what if the user gives us 1.0? We're fine too! The floating point will be converted automatically to the closest integer. This means that 1.1 or 1.2 will be both converted to 1 too. In other context, you could manage those cases differently, because if the user is giving you floating points, maybe the decimal means something and you want to tell them something's wrong. This case is simple, so we will be chill about that.

;; assign the parsed value to the index var itself;
;; we're not going to need the raw input anymore;
(setq index (format "%d" index))

Of course, if the user gives us something that cannot be in any way interpreted as an integer, we have to tell them. To be honest, this part is already managed by the format command itself.

If you supply a value that doesn’t fit the requirements, an error is signaled.

So, we don't have to implement this code by ourselves:

;; If user's input is not a number, the `format` function will tell them;
;; We can proceed with our function.

Throwing an error

We still cannot vibe with our function results because another block, the last one, is missing.

What if the index is not in the desired range?
Of course, an error would be displayed this time too, but we need to explain clearly to the user what they have to do to not triggering it.

Signaling an error means beginning error processing. Error processing normally aborts all or part of the running program and returns to a point that is set up to handle the error (see How Emacs Processes Errors).

Errors are managed by error function (what a shock, isn't it?). A typical use of error from the docs:

(error "That is an error -- try something else")
     error→ That is an error -- try something else

We take inspiration for our use-case:

(error "Out of range error -- choose a number between 0 and 3.")

As nv-elisp points out on Reddit,

When using message you'll want to provide the format-string argument. Otherwise the user's strings will fail if they include format specifiers. e.g. if your goodvibes list includes "%dont mind me%", the %d will be interpreted as part of the format-string argument and will throw an error.

For an error caused by user input, it's better to use user-error. This will prevent the debugger from being hit any time a user inputs an out of range number.

So, in this case it would be more advisable to write user-error instead of simply error:

(user-error "Out of range error -- choose a number between 0 and 3.")

Wrapping up

We learned how to use format and error, two fundamental functions to manage user's inputs or for writing lisp for Emacs in general.
In particular, we should remember that:

error stops the process and throws up the specified error to the user;
format can have various specifications like:
- %s, for common strings;
- %d, for integers;
- %f, for "floats".

To be absolutely correct, I should remember you that there's not a single type of integers or floats or strings; for example, strictly abiding to what the docs are saying, %f refers to "the decimal-point notation for a floating-point number"; you can store floats in other ways, if you need.

Coming back to our function, that's how it finally appears:

(defun cheer-me-up (index)
  (interactive "sChoose a number, receive good vibes~ ")
  ;; We are asking for a string from the user, so this could be anything.
  ;; We must be sure it's an integer.
  ;; assign the parsed value to the index var itself;
  ;; we're not going to need the raw input anymore;
  (setq index (format "%d" index))

  ;; Isn't it possible to convert the string to an integer?
  ;; Tell the user!
  ;; If user's input is not a number, the `format` function will tell them;
  ;; We can proceed with our function.

  ;; Now we need to know the integer is not inferior to 0 or superior to 3
  (if (and (> index 0) (<= index 3))
      ;; if we pass the condition, good, print out your message
      (message (nth index goodvibes))
    ;; Else block:
    ;; if the number exceeds the range from a way or another, tell the user.
    ((user-error "Out of range error -- choose a number between 0 and 3."))))

This is the moment for a confession: in order to teach how the format function works, I somehow have disguised you. The interactive function, in fact, gives the chance to filter the values in place! That's what the "s" before "Choose" is there for (see Code Characters for interactive in the docs to learn more)
Knowing this, we could write everything more concisely, like that:

(defun cheer-me-up (index)
  (interactive "nChoose a number, take good vibes~ ")
  (if (and (> index 0) (<= index 3))
      (message (nth index goodvibes))
    ((user-error "Out of range error -- choose a number between 0 and 3."))))

I started with the "n" character, because it means you want to take a number as an argument.
The only difference from before is that this new function lacks the previous tolerance for floats, but I don't see this as a flaw.

Watch out!
format specifications and interactive first character's meanings are not exactly superimposable!
Using "f" in interactive means asking for a file, not for a float.

Keep it up!

Hoping this post was an enjoyable passage in your path through lispian parenthesis, I wish you good luck for your journey.

(nth 1 goodvibes)
;; => "Keep it up!"

(and a big thanks to Arialdo for his help in tracking down my typos)