Jun 4, 2020 • Arnout Roemers
The rmap library was one of my first Clojure libraries. It lets you create recursive maps, both programmatically and in literal form. They are recursive in the sense that entries in the map can refer to other entries.
The library has seen its first major update. It is far simpler now, and more powerful because of it. Version 2.0 of this library has been released, and this blog post will tell you what has changed and why. Since most of you won’t know the library already, let’s begin with some history.
The recursive property of maps in rmap work by lazily evaluating the values, using a macro. To give you an idea how it works, this is what it used to look like:
You give the
rmap macro a symbol and a map.
The map values can use the symbol to refer to the map itself, and thus other entries.
The macro returns a special kind of map, one that evaluates the entries on request and caches them.
While I haven’t touched the library in a while, I had a use for it again in my current project. When going through the source code I saw that it was showing its age. Both the API and the internals were complex and over-engineered. Again, it was one of my first libraries, so cut me some slack :)
Most of the complexity came from allowing recursive values to fetch other entries in any map-like manner.
In other words, the value expressions had access to the map datastructure itself.
But because it was a map with special evaluation rules, a completely new map type was created for this purpose.
The type needed to implement all kinds of interfaces, such as
IPersistentMap to name a few.
Because of the special semantics of the map, difficult decisions had to be made on what it means for an entry to be “evaluated”. Is the value cached? Where is it cached? Does this influence “ancestor” maps sharing the same entry? Does it influence already created “derivative” maps with the same entry? Or those created after the evaluation? Are the entries realized on equality checks?
In the end, the library was setup in such a way that the users could make all these choices themselves, only adding to the complexity.
When revisiting the rmap library, I thought about how to simplify it.
Going back and forth between several designs, I found a solution that I have already partially hinted at.
It is somewhat inspired by the Integrant library.
What if the library does not allow the recursive values to use a map to access the other entries, but a single, simple and clearly defined way instead?
A plain function for example, called
ref for example?
This is exactly how rmap 2.0 is setup. It changes the library in the following ways:
With the new version the beginning of the former example now looks like this:
rmap macro the values now refer to other values using the
(ref [key] [key not-found]) function and the result is a plain Clojure map.
This seemingly small change to the user has a profound impact on the implementation.
From 691 to 75 lines of code, actually.
It also makes all those caching choices go away and by that offer far simpler semantics, as you will now see.
You can see in the 2.0 example that the recursive values in the map are still lazy, i.e. not instantly evaluated. Let’s see what happens if we continue our 2.0 example like we did with the old rmap:
Instead of getting the “Clojure is awesome” string, you get back an unevaluated recursive value.
This is because we now use a plain Clojure map and recursive values are now first-class objects.
To get the desired result, a map with recursive values needs to be “valuated” first.
For this the library has the
All it does is “updating” a Clojure map by evaluating all recursive values.
To evaluate a recursive value a
ref function is needed.
valuate! function it creates such a
ref function and is passed to the recursive values.
ref function passes itself along recursively while evaluating referred entries.
It is exactly at this
ref function where caching takes place, and nowhere else.
This ensures that a recursive value is evaluated only once, even if it referred to multiple times.
Let’s use this
valuate! function on our basic map:
Now we have our expected result, again in a standard Clojure map. This simplicity makes the semantics very clear. The original map is also not affected. Descendent maps act like normal maps, since recursive values are first class. If you want the values to evaluate in the context of another map, you simply valuate an updated map, like so:
A companion function of
It behaves similar to
valuate!, but returns a map where only the entries of specified keys and its dependencies are evaluated.
One last macro is provided by rmap 2.0, which is
It is the same as
rmap (without a bang), but is instantly valuated.
rmap! macro may be all you need for your purposes.
The other macros and functions are provided to give you all the building blocks you might need.
This way the library aims to be both simple and easy.
And that wraps up an overview of rmap 2.0. You will read more about it soon on this blog though, as there are two more libraries to be announced, and one of them complements nicely with the new rmap!
You can find more detailed documentation here.
As always, have fun!
If you do like to have a special map implementation that does caching, automatic evaluation and such, it is certainly possible to create one based on the rmap 2.0 core API.
The example below gives you a map-like read-only datastructure that allows access patterns like
(get my-map :key),
(my-map :key) and
However, this approach does reintroduce a “hidden” cache again, along with its mutable properties; something rmap 2.0 tries to avoid, at least in its core. The library does have a similar wrapper, but this is experimental for now.