Rune Utilization in Hoon

Enquiry

I investigated the Urbit kernel for the actual usage rates of various Hoon runes in practice by experienced senior developers. While I had done this a few years ago using a naïve regex match, this time I built the abstract syntax tree of every file in the kernel. This allowed me to include irregular syntax and exclude non-runes (like the spurious ^~ non-ketsig in rose+[" " `~]^~[leaf+"*" (smyt pax)]).

The survey was based on the contents of /sys as of ~2022.12.14. For the first pass, every file in /sys was built using ++reck and ++noah, e.g.

*%/out/ames/txt &txt (noah !>((reck /===/sys/vane/ames)))

I tabulated the number of instances of each currently-supported Hoon rune from the AST. While the particular values are noisy across commits, I expect secular trends to persist.

Table 1. Rune AST labels.

The raw data can be generated at need from the Urbit repo by the technique above.

Results

This technique converted irregular syntax to regular syntax, but did not desugar runes. This investigation thus reflects programmer intent at the object level of expression design. A subsequent attempt with ++open:ap to desugar runes would be instructive as to how Hoon “sees itself”.

Table 2. Observed rune frequency in /sys.

Rune frequency follows a power-law distribution with 18 runes representing 80% of total rune utilization. Indeed, several runes are hapax legomena in /sys (|? barwut, ~<) or do not occur at all (discussed below).

Figure 1. Observed rune frequency in /sys as a power law.

(Bear with me on that graph: it's rather hard to display order runes in any sort of coherent way I've come up with so far.)

Analysis

There aren't any real surprises here. The most frequent runes reflect the most common design patterns:

• % cen rune calls tend to route through %: cencol since the irregular form (fun 1 2) desugars to %:.
• :* coltar serves similarly as the desugaring of tuples constructed by [1 2 3].
• %= centis is invoked through the irregular $() expression resets. These are most commonly employed in gates and traps as a recursion, as well as to modify legs and in the nested core design pattern, e.g. this(value new-value).
• ^= kettis happens in face assignments a=1.
• ^- kethep compile-time typechecks use tics or explicit rune passage.
• %~ censig is used to pull an arm in a door.
• =< tisgal composes two expressions in inverted order. This arises from this:that wing search patterns.
• =/ tisfas seems to be slightly preferred in more contemporary code to =+ tislus, altho they carry out equivalent operations to pin a value to the subject.

Other common runes follow a similar logic based on common design patterns.

Table 3. Observed rune frequency in /sys, eighteen runes representing 80% of all Hoon code in /sys.

The least frequent runes include:

• |? barwut produces a lead trap. Like ^& ketpam, lead cores have not yet proven to be a useful expedient in practice.
• ~< siggar applies hints for the runtime to process. This can be helpful in debugging.
• ;= mictis produces Sail code, unnecessary within the kernel.
• ?# wuthax, as yet undocumented, is being developed as a replacement for ?= wuttis that can more powerfully match patterns in general, such as list detection.

A very few runes are never once used in the kernel. Some are simply intended for transient or labile userspace code, for instance.

• ^& ketpam produces a zinc core (covariant). While included for completeness of the variance system, zinc cores have not turned up in effective design patterns yet within Urbit.
• ;< micgal acts as a macro rune for sequencing computations in threads, similar to ;~ micsig.
• ~$ sigbuc is used for profiling code, and shouldn't be present in release code.
• ~= sigtis detects duplicates, and is used for cleaning up memory from duplicate nouns.
• !@ zappat branches on wing existence; while it seems like this would be useful in the kernel, it is not employed in practice.

Rune labels like %ktpm that that occur in the codebase may not be represented even once in the final AST. This is possible because ++ream and ++reck yield the names of terms as +$dime of %tas and @ud.

i=[%leaf p=%tas q=1.836.086.379]

Of the other uncommon runes, I note as well that .^ dotket to peek or scry is important in userspace but that the kernel rarely needs this expedient.

Conclusion

My original intent several years ago was to treat such a frequency map as a pedagogical tool. While there are compelling reasons not to treat rune frequency as a normative check on programmer behavior, knowing which runes are used the most in practice guides the sorts of Hoon which should be taught and documented most clearly first.

Subsequent investigations which may be illuminating include:

1. The change in rune utilization over time (based on age of commit).
2. The relative frequency differences in different vanes.
3. The desugared frequency of runes.
4. The characteristic rune frequency patterns in userspace code, or by programmer.

The kernel has important differences from userspace, but rune frequency in the kernel acts as a reference thumbprint for rune utilization by experienced senior developers in Urbit code.