Each time I write a small utility, either a command line one or for an MCP server, I need to store state and config in the file system. I’ve come up with many ways of doing it. You know, like, you want to store a default LLM prompt in a file. You want to store a D&D play log in a file, or a bunch of markdown files for D&D monsters. There’s more simple things: where do you put the log file?
There’s actually standard for how you do all of this, XDG. It’s think it’s from X-Windows land, but if you take a look at ~/.local and ~/.config, you’ll see that several applications use this scheme. I wanted a simple, tiny library that I could use in my Java projects to do it, so I implemented one with my pals Claude and ChatGPT. I haven’t used it yet, but it is tested. The next step in the xdgj project is to make sure it works with Spring, dragging in all the property handling and magic that comes from a Spring project.
Implementing it reminded me of one of the ways coding can be fun. This is a seemingly boring thing it’s doing, and seems so simple. The spec is wonderfully small. But it’s written in a way that requires a very close reading to catch all of the implications and how you implement it. This is especially true for section 4, which is a bit of a mess if you’re not used to this kind of spec writing. What’s going on in that section is that the spec writers are trying very hard to not take a position on how the spec is used and interpreted. And, thus, they don’t need to take on those responsibilities, nor think about them. It keeps things small and, as such spec writers would say, “minimal.” They might even say “elegant.”
Speaking of, the actual code for this “library” is tiny. It took a long time to get it that tiny! You start working on each method and type of functionality, writing the test cases as you go. You think of edge cases to test and re-code for. You go back and read the spec and realize you’ve missed something. Worse, you realize you’ve read something into the spec that wasn’t even there!1 Then you take a break, and realize that you can replace a lot of the code with just one chunk of code. You rewrite the tests, etc.
It’s fun!
Hopefully, I’ll never have to worry about util files management again.
-
In this case, the concept of an “application name” doesn’t exist in the spec and is not mentioned. It’s something every application that XDG uses, but it never shows up there. It’s implied, but not part of the spec. Put another way, the XDG spec will tell you where user data is stored - or logs - but it will not tell you how to arrange files there, what format they are in, or anything. It just tells you the “base directory relative to which user-specific data files should be written.” Does that mean you dump user files right there, or create a sub-directory for the application so you don’t overwrite other applications’ files? The spec seemingly does not care, nor does it speak of it. ↩︎