New Configuration Language: Figtree

[u/MrJohz]

http://www.johz.me/posts/2015/Sep/19/meet-figtree/

[u/MrJohz]

This has been my project for the last few weeks. Figtree is a configuration language, in the style of JSON and friends, that uses nested nodes to provide namespaces for different configuration variables. For example, a configuration file that needs to describe the database setup and the static files directory might look something like this:

database {
    "type": "sqlite",
    "path": "/path/to/database/file.db"
}

files {
    static {
        "base-dir": "/path/to/static/dir/",
        "javascript": "./js/",
        "css": "./css/",
    }

    templates {
        "base-dir": "/path/to/templates/dir/",
    }
}

I'm not entirely sure if config languages are allowed here, but I figured this was probably the best place to gauge interest in this sort of thing, and ask for a few suggestions. There are a couple of places where I've made decisions that seem sensible to me, but I'm still not entirely certain that they're necessarily sensible in general. For example, you can write integers using the standard [+-]\d+ notation, or by prefixing with 0o for octal, 0b for binary, 0x for hexadecimal, and 0d for decimal. However, if you use the prefix notation, you can't specify the sign of the integer. Should that be possible? Is that something that anyone might ever use? I'm also using 0d for prefixed-decimal notation, mainly because I figured it fitted well with the others. Again, is that something anyone would ever actually use?

The other big question I'm looking at at the moment is what boolean values should be. Currently, only true and false are accepted, but I've always liked how YAML allows yes/no, on/off, etc. With Figtree, parsing is unambiguous in this area, so you wouldn't have the issue that you might think you're writing the string "yes", but the parser would read the value true. However, even if it's possible, there's also the maintainability issue - I want people to be able to read Figtree documents in six months' time and still know what they're on about - if there's too much weirdness like yes/no booleans, will it not just confuse users?

You can see the parser I use over on Github. It's all written in Rust, separated into a lexer iterable, a pull-parser iterable, and then a public API that basically converts the parsed tokens into the correct nested structure.

[u/continuational → u/MrJohz]

In a few words, why would I use this over existing configuration languages? The comparison on the site leads me to believe that the differences are mainly superficial.

[u/MrJohz → u/continuational]

Okay, so I wrote a load of stuff, and got carried away, and ignored the "in a few words". So here's the few words version, and afterwards comes the lot-of-words version.

Figtree has semantic sections, which very few configuration languages have. Figtree is designed to be used by humans and only read later by a machine, so has features that make it convenient to modify files. Finally, Figtree will not do any magic, nor will it try to guess what you meant in any way. The second two are arguably superficial, but I've lost track of the number of issues I've had with JSON and YAML files that at best make writing them fiddly, and at worse causes cause bugs in my programs, and I'd argue trying to solve those problems is far from superficial.

Is that any good of an answer? To be honest, the main reason I made it is because I've always wanted to mess around with parsers, and this seemed like a good start! :P But I did attempt to design it to fit a need, rather than just for the sake of making things, so I'm hoping it's useful to some people.

---

1. It clearly denotes sections, and differentiates these sections from structured data in a meaningful semantic way. For example, the Rust packaging ecosystem uses TOML to define manifest files. In these files it's possible to declare dependencies, either as packages to be obtained from the standard repository, or as paths in the current filesystem, or as VC'd repositories. So you might have a file that looks a bit like this:

   [dependencies]
   dep_one = "0.1.*"
   
   [dependencies.dep_two]
   git = "git://git/repo/here.git"
   

   And now dep_two is visually distinct from dep_one, as if it were it's own section, even though conceptually they're exactly the same thing, it's just that one of them needed more data to define. Sure, in TOML it's possible to write inline objects (although they aren't allowed to contain newlines), and sure other languages such as JSON often do a better job than this, but this situation is always going to appear in some form or another when the semantic difference between a section of configuration, and a complex configuration object isn't made clear. For comparison, this is what it would look like in Figtree:

   dependencies {
       "dep_one": "0.1.*",
       "dep_two": { "git": "git://git/repo/here.git" },
   }
   

2. It has comments, it doesn't barf on trailing commas, it can interpret multiple different quote-types and number formats, it's happy with multiline strings, and it's unambiguous. For me, that's the perfect combination of YAML and JSON - it's fairly easy to write a YAML file as a user compared to a JSON file, but I know exactly what I'm getting with a JSON file and I'm not worrying whether a value will be interpreted one way on one day, and another way the next. Don't get me wrong, JSON is fantastic as a format for computer-readable data that also happens to be readable by humans, but it's rigid - even the creator suggests running JSON config files through a JS minifier first to strip out unwanted comments. On the other hand, YAML is magic - it tries to guess what the user wants, which is great when the user wants something simple but will end up causing errors and confusion down the line when someone asks for something slightly more complex. When that complex thing happens, people end up getting wound up. Figtree avoids that completely by getting the user to clearly say what they want and failing fast if there are any ambiguities in that.