Hugo's Dictionary API
Erynwells.me DevelopmentHugo’s templating system has support for dictionaries. Unfortunately the API for working with them is, frankly, awful. While working on developing some new templates for this site, I had to figure out how to build up dictionary data structures and it took me a long time to figure out how to do some basic operations with them.
Here’s a quick summary of what I found.
Creating Dictionaries
The function to create a dictionary is called dict
and it takes a
variable number of arguments that alternate between keys and values. It reminds
me of this bizarre and backwards NSDictionary API in Apple’s
Foundation framework. Keys must be strings (or string slices) and values can be
anything. So this:
creates a structure that looks like this JSON object:
You can also create an empty dictionary by calling dict
with no arguments.
Accessing Keys and Values
Statically, you can get a single item in a dictionary with dot syntax. Below,
$item
will get the value 1.
If you want to get a value with a key you get at render time, you can use the
index
function. In the snippet below, $item
will get the value of
"b"
, which is 2.
index
doesn’t make much sense to me as a verb for accessing values in a
dictionary. It sounds more like an array function, and indeed it’s the function
that gives you access to items in arrays. I would like to see another function
with a more dictionary-sounding name, like get
or value
or item
, even if
it were just an alias for index
underneath.
Adding Items to a Dictionary
This is a bit complex because, as far as I can tell, dictionaries are immutable.
So, if you want to update a dictionary, you need to combine two dictionaries and
then save it back to the original variable. The merge
function does
that. Here’s a snippet:
merge
takes a variable number of arguments, and merges dictionaries left to
right. So, items in dictionaries later in the argument list will override items
in dictionaries earlier in the list.
Just to underscore, you have to set the update dictionary back to the original
variable to complete the update, hence the $d = ...
.
All that is to say: at the end of that snippet, $item
will get the value 4.
A Complex Example: A Dictionary of Arrays
For the previously mentioned template changes I was making, I was updating the
terms
template for my category taxonomy. For each category, I wanted to show
one section per tag, and a list of all the posts with that tag underneath.
My categories are high level groups like “Tech,” “Music,” and “Travel.” Tags are more specific topics for the post like “Web” or “Compositions.” Pages only ever have one category but they can have multiple tags.
A terms
template lets you access an array of terms, and the pages associated
with those terms. You can access the tags attached to a page with the
.GetTerms
function. Here’s what I did, and then I’ll talk through it:
$pagesByTag
is my empty dictionary. It will hold tag names as keys, each
pointing to a slice (array) of page objects. For each page, I get its list of
tags. For each tag, I check $pagesByTag
to see if it already has a key/value
pair for that tag. If not, I create a new entry in $pagesByTag
with merge
.
If it does already, I get the slice for that tag with index
, add the Page to
the slice with append
, and then merge the updated slice back into
$pagesByTag
with merge
.
It’s not too bad once it’s all spelled out, but it does feel like more work than it should take for such simple operations.
I think this API could be improved substantially with some new functions that operate specifically on dictionaries and that have clear names that describe what they do.