More Tagged Union Subsets with Comptime in Zig

Even More Tagged Union Subsets with Comptime

May 18, 2026

One of the cooler things you can do with Zig's comptime is create what Mitchell Hashimoto calls "tagged union subsets." Hashimoto shows how he can take an existing tagged union, one representing all possible keyboard shortcut actions in Ghostty, and use comptime to derive more specific unions representing just those actions affecting a particular terminal window or just those actions affecting the entire application.

Having these more specific union types available means that he can write functions accepting only terminal-specific actions or only application-wide actions. These functions look something like this, where ScopedAction(.app) is a call to a function that runs at comptime and returns the more specific union type:

1// This function handles application-wide keyboard shortcuts. 2pub fn performAppAction(action: ScopedAction(.app)) void { 3 switch (action) { 4 .quit => ..., 5 .close_all_windows => ..., 6 .open_config => ..., 7 .reload_config => ..., 8 } 9} 10 11// This function handles shortcuts scoped to a terminal window. 12pub fn performTerminalAction(action: ScopedAction(.terminal)) void { 13 switch (action) { 14 .new_window => ..., 15 .close_window => ..., 16 .scroll_lines => ..., 17 } 18} This pattern is useful mainly because Zig has exhaustive switching. Given a function like performAppAction() above, Zig will yell at you (helpfully) if you add a new application-wide action but forget to add a matching case to the switch. If performAppAction() instead took an action of type Action, then Zig's yelling would lose specificity; Zig would yell at you if you were to add a terminal-specific action without a matching case. That's much less helpful, since in the context of performAppAction() we don't care about terminal-specific actions.

A Similar Problem with Trees

I recently ran into a situation that seemed to call for using tagged union subsets. I ended up with a solution heavily inspired by Hashimoto's but different in a few ways that I think are interesting.

I am working on a parser for MyST, a new Markdown format. Markdown parsers typically read an input document and produce HTML directly, but MyST has a spec that defines an AST for parsed MyST documents. Much of the code in my parser is concerned with constructing and traversing this AST.

The MyST AST has many different types of nodes. To represent this, I use a large tagged union of node types.

Some nodes (headings, inline emphasis, MyST directives) are allowed to have children while others (inline code, images) are not. While working on the parser, I have often found myself writing functions that transform the AST using a recursive operation on nodes in the tree. Functions in this vein want to do one thing with nodes of a particular type, but, for all other nodes, provided they have children, want to just recurse through to all descendants.

My first attempt at implementing these functions looked something like the following. In this example, I'm traversing the tree looking for myst_directive nodes to hand off to the code that implements MyST directives.

1fn transformDirectives(alloc: Allocator, node: *ast.Node) !*ast.Node { 2 switch (node.*) { 3 // The nodes we're looking for. We pass the node to a function that 4 // will implement the directive by adding children to the node. 5 .myst_directive => return try transformBuiltinDirective(alloc, node), 6 // Nodes with children. We need to recurse to look for more directives. 7 // `inline` is a fancy Zig keyword that allows the below switch 8 // prong to be polymorphic across all our node types with children. 9 inline .block, 10 .heading, 11 .paragraph, 12 .emphasis, 13 .strong, 14 ..., 15 => |node_payload| { 16 for (0..node_payload.children.len) |i| { 17 node_payload.children[i] = try transformDirectives( 18 alloc, 19 node_payload.children[i], 20 ); 21 } 22 return node; 23 }, 24 // Leaf nodes, nothing to do. 25 .text, 26 .image, 27 .code, 28 .inline_code, 29 ..., 30 => return node, 31 } 32} This switch has three cases. In order to correctly partition all the various node types into the three cases, I need to list them all out. This is verbose (especially because in real life there are many more types than shown above). Worse, since I have many functions like this one, every time I add a new node type to the AST, I need to update dozens of switch statements across my codebase to make sure every node type is correctly identified as either a node with children or a leaf node.

We might be tempted to make this better by eliding the leaf node types with an else case:

More Tagged Union Subsets with Comptime in Zig

Related Articles

Elevated error rates on requests to multiple models

Donald Trump and sons to be 'forever' exempt from tax audits

PopuLoRA: Co-Evolving LLM Populations for Reasoning Self- Play

Old Reddit Is Down

The ultimate female fantasy – A feminist critique of Beauty and the Beast