I am using TOML in most of my projects and once the configuration files grew too large I just extended the syntax with “#@include filepath” declarations and split up the config files. Works great. https://github.com/nodemailer/wild-config/blob/master/README...
Toml: Tom's Obvious, Minimal Language
151–160 of 204 posts
Re: Toml: Tom's Obvious, Minimal Language
#152Earlier quoted context omitted.
>They belong in the sections of code that load specific config files and convert their contents into defaults or parameters. And what are users who don't have access to the source, or who aren't programmers, supposed to do?
Somehow these people are reading Toml files of config? That’s silly.
Non-open source software.
Ops teams deploying a service.
Programmers who don't know the language a program is written in.
Heck what about a config file for a game? If setting the resolution it'd be nice if valid values are shown in the comments.
The argument is about comments in JSON btw.
Re: Toml: Tom's Obvious, Minimal Language
#153Some questions I couldn't find answers for:
- Is interpolation supported? e.g. "key1" = "value" and then "key2" = "$key1". That would be very useful in avoiding repetition.
- What is the keyword for null? e.g. when I want to set the value to null
Re: Toml: Tom's Obvious, Minimal Language
#154Earlier quoted context omitted.
I have never disagreed with someone more than I do now. =) Config absolutely needs comments. Context is everything. Comments allow me to explain to other humans why the config is the way it is. Dumping that out to a separate file is begging for it to fall out of sync when there's no comment instructing anyone to go and update the other file. Plus that's just kind of silly.
I disagree. It’s an anti-pattern. For example, if you’re writing an application that loads a default config file to populate parameters at run time, then the software module that loads from the default file is the correct place to document it, because the meaning of defaults is relevant to that source code, not at all to someone reading the parameter file itself. A parameter file is just some blob of stuff. I agree c…
I very much disagreed with you two comments up, but this more fleshed out response actually makes a lot of sense. You just moved me from "I'm going to add a build rule that strips comments from all my JSON files so that I can have comments in my configs" to "The next time I want comments in JSON, I'm going to see if what mlthoughts2018 said makes sense in this case. Do I really need to comment this JSON file, or would it be better to put the comments somewhere else instead?"
We'll see how it goes!
Cheers
Re: Toml: Tom's Obvious, Minimal Language
#155Earlier quoted context omitted.
I have never disagreed with someone more than I do now. =) Config absolutely needs comments. Context is everything. Comments allow me to explain to other humans why the config is the way it is. Dumping that out to a separate file is begging for it to fall out of sync when there's no comment instructing anyone to go and update the other file. Plus that's just kind of silly.
I would even say config needs comments more than code does. Code can be self-documenting: by using good variable and function names, splitting or combining lines of code, or re-ordering blocks of code you can often make the intent of the code clearer without adding explicit comments. If you do something unexpected in a config file, it likely just shows as setting some name to a magic number or a magic string.
I definitely add way more comments to my projects' default config files than I do to my actual codebase, if we're talking total number of comments.
Re: Toml: Tom's Obvious, Minimal Language
#156Hey, Tom here (creator of TOML). Fun to see TOML on HN again! Since I first wrote a (mostly) joke proposal for TOML 5 years ago, TOML has been adopted by a number of prominent projects such as Cargo, Hugo, Pipenv, and others. TOML is especially well suited for projects that need a simple configuration file that maps unambiguously to a hash table. There are still some weaknesses in TOML that make it non-optimal for la…
A killer feature of TOML compared to JSON is that it allows comments. A config file without comments and examples ain't great. I found the double square bracket syntax useful and understandable. Agreed it's not obviously .INI or perfectly elegant but it certainly works and has its use-cases. Anyways, thank you @mojombo!
{
“_comment”: “The comment goes here!”,
“name”: “foo”
}
Re: Toml: Tom's Obvious, Minimal Language
#157I didn't know about TOML until I started using Hugo. I've been using YAML and TOML and I find both have their merits, especially for their simplicity. TOML looks like the classic INI file, and is fairly easy to use/learn. I've been trying to move toward TOML for everything. YAML is nice, but I had to be careful about white-space significance and also translation of "YES","NO", etc. https://arp242.net/weblog/yaml_prob…
Absolutely. That's what I mean about TOML mapping unambiguously to a hash table. Strings in TOML are always quoted. There is no fuzzy interpretation of things like YES and NO. That way madness lies. I also am not a fan of meaningful whitespace, which is why TOML doesn't do that. Glad you're finding TOML useful, good luck on your projects!
[deleted]
Re: Toml: Tom's Obvious, Minimal Language
#158Earlier quoted context omitted.
I have never disagreed with someone more than I do now. =) Config absolutely needs comments. Context is everything. Comments allow me to explain to other humans why the config is the way it is. Dumping that out to a separate file is begging for it to fall out of sync when there's no comment instructing anyone to go and update the other file. Plus that's just kind of silly.
I disagree. It’s an anti-pattern. For example, if you’re writing an application that loads a default config file to populate parameters at run time, then the software module that loads from the default file is the correct place to document it, because the meaning of defaults is relevant to that source code, not at all to someone reading the parameter file itself. A parameter file is just some blob of stuff. I agree c…
Maybe that makes sense for the app you are writing that is only consumed by others at your company, but if I'm installing your app from a package manager I absolutely do not want to have to read the config loading source code to figure out what all the parameters do. And even if the docs are nicely described in a man page and not in config file comments, I absolutely want to be able to comment on particular parameter changes ("# had to up foo to 18 because bar was frobbing baz at to high a rate").
Even if you use configuration management it's still nice to be able to comment things in config files since they show up both in the source and in the output files, which is very helpful when debugging.
Re: Toml: Tom's Obvious, Minimal Language
#159Earlier quoted context omitted.
A killer feature of TOML compared to JSON is that it allows comments. A config file without comments and examples ain't great. I found the double square bracket syntax useful and understandable. Agreed it's not obviously .INI or perfectly elegant but it certainly works and has its use-cases. Anyways, thank you @mojombo!
Json allows comments, but they have to be in string fields of an object so they survive reserialization.
So then… not actually comments at all?
A nice config parser will error out or at least warn loudly when encountering an unknown parameter. This helps prevent typos.
Re: Toml: Tom's Obvious, Minimal Language
#160Earlier quoted context omitted.
There's no one clear place to point to about how the decision was made for Cargo, but some nuggets have been left by authors [1]. The gist seems to be that JSON (and YAML, per that comment) was considered a poor format to author and maintain a config file in, and YAML had no lib in Rust and there was no appetite for anyone to write one. Pip's choice was made for them in the form of PEP 518 [2]. The authors of PEP 518…
I was one of the supporters of TOML back when this decision was made. I might have been the first one to suggest it, but I don't remember exactly. Basically, I wanted something that was (1) simple, (2) terse, (3) supported comments, and (4) supported recursive data structures. Requirement (1) eliminated YAML, requirement (2) eliminated XML, requirement (3) eliminated JSON, and requirement (4) eliminated INI. Of the r…
This seems reasonable, but I'd like to add that XML, while certainly not designed as a config language, could be made much more terse by using SGML, the markup metalanguage XML is derived from and of which XML is a subset. SGML has additional constructs for short forms such as tag omission/inference and short references (custom Wiki syntax) targetted at authoring, whereas XML only admits canonical angle bracket markup syntax which is what makes XML verbose and cumbersome for edititing by hand.