Toml: Tom's Obvious, Minimal Language
github.com
github.com
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 large, complex config, but I'm hoping to address that in a later version of the spec (perhaps 2.0).
Happy to answer any questions you all have about TOML!
1. Would a file path type make any sense to add? TOML is ideal for configurations, and so many configuration options use file paths. I know there are questions about platform dependency, and I don't have all the right answers for how that would work, but I could see it being possible somehow?
2. Data versioning is a big deal to me. For now there's always an option of just adding a "version" key and updating it, but can you think of a better way to do that with TOML?
I'm always overly critical of JSON (despite overall being a fan) because it doesn't specify bit sizes of numbers. I notice that TOML has specified 64 bit numbers. It's nice to see that.
2. This is still a big question, and we've been having a robust argument about it on GitHub [1]. It's a problem that so far has evaded an elegant solution, but usually when that's the case, it just means we haven't been creative enough about it yet! Or did you mean versioning of the data IN the config file? Can you elaborate?
2. So basically, the majority of people don't want to type version numbers (I see where they are coming from, but respectfully disagree). I'm not sure if there exists a solution in that case. As for my comment, I was really talking about both kinds of versioning. Mainly that, if my data is version 2.3.1, I'd expect that to also lock the version of TOML, requiring a new version of my data for bumps to the underlying data structure. Again syntax is the hard part, as I'm having trouble imagining a way to actually do this. Furthermore I've seen data formats in the past that let you version "parts" of a format, I personally like this, but don't think it's a good fit for TOML.
static-files = path/to/static/files
And have it work on all platforms gives a distinct advantage over specifying paths as strings.
The one exception on Windows may be paths in a CMD.EXE command line, where / may be confused for a switch character, but I would think a config file should not be passing paths on a command line but instead passing them directly into a program - and then the forward slash will work fine.
(Folks downvoting, PLEASE JUST LET PEOPLE HAVE JOKES EVERY NOW AND THEN)
If you think that your brand of funny is worth braving people's disapproval, do it knowing what the reaction is going to be. If you don't like people disapproving, then go elsewhere, or engage here in a way that people prefer.
Over the many years of the usage of INI I think occasionally we've seen developers add their own touches to how they support types, sections, groups, multi-dimensional arrays or other structures within config files that certainly indicated a need for some more standardized advancement here.
I really hope this gains a lot of traction, because there are so many scenarios where things like XML or JSON are forced into roles they really don't belong in.
One thing that I would say is that it might be worth indicating a standard header that can be used at the very least in cases when it is not stored in a file with a .toml extension. It would not surprise me at all to see TOML widely used with extensions that describe better the intent of the file rather than the format.
I just wanted to say thank you real quick.
We use TOML in [Habitat](https://github.com/habitat-sh/habitat) to define default and overridable configuration. It's super easy and expressive.
The [Habitat Core Plans](https://github.com/habitat-sh/core-plans) have quite a few examples about how it gets used in the project. If you are looking for examples of larger configuration files with .toml, then that might be a good place to look for some real world use.
Thank you again!
https://github.com/habitat-sh/habitat/blob/master/components...
See the relevant part of the spec here: https://github.com/toml-lang/toml#user-content-array-of-tabl...
What are the limitations for large complex configs, and do you think there's currently a better configuration format for them? Feel free to link elsewhere if there's a canonical location for this discussion.
That said, the alternative right now in other formats is basically a { bunch { of { braces } } which is also not the most amazing thing for long nested tables.
Good to know this is recognized. Looking forward to a better syntax to an indeed difficult problem
e.g. CSVs handle 2D tables reasonably efficiently, since you just specify values:
field_a, field_b, field_c
1, 2, 3
3, 4, 5
May be the config shouldn't be large and complex in the first place?
My biggest question is, why hasn't TOML used much more widely or becoming de facto standard? Am I missing something obvious?
As for adoption, it takes a long time for something like TOML to be adopted. Inertia is powerful in the development space. I also haven't had as much time as I would like to push TOML forward and evangelize it. My hope is that at some point there will be a tipping point and you'll see most projects start with a TOML config and only change to something else when TOML can't meet the project's needs.
https://github.com/perlbot/App-EvalServerAdvanced/blob/maste...
The rest of the sandbox is configured with TOML however. Just seccomp rules that I haven't figured out the perfect way yet.
1. Extensible, custom types
2. Streamy, efficient, compressed and fast, leverages platform's existing native/optimized JSON parsers
3. Wide platform reach
4. Made by Rich Hickey
According to the repo history, it did... 5 years ago, until someone noticed and corrected it.
Really? I had kind of the inverse reaction to it. Indeed useful, but definitely not understandable
In php:
$a[] = 1;
$a[] = 2;
# $a == array(1, 2)
http://example.org/?a[]=1&b[]=2
[[a]]
item = 1
[[a]]
item = 2 https://example.org?foo=bar&foo=bazA nice config parser will error out or at least warn loudly when encountering an unknown parameter. This helps prevent typos.
Config files should absolutely not have or need comments. If you need them directly in the config file, something is wrong. Applications should document their default settings in a different way, preferably in a README or generated documentation that also explains how to use environment variables to override the defaults. That sort of separate companion doc is the right place for notes about defaults or "why" certain config values exist in the file. The same is true for using JSON to store parameter files, etc. It's actually quite important to keep metadata about the config / params / etc. specifically out of those files, so that they are absolutely nothing but value files. Information about why a file contains those values belongs elsewhere, and it's an anti-pattern IMO to rely on comments in the config / param file.
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.
In past lives I have had to hack around so many different things to make something work they way I intended that I knew there would likely be a better solution to at some point.
As we get closer to things like infrastructure as code and configuration as code being the norm I would like to take this comment to remind people there is no such thing as self commenting code!
Even if this configuration should be “obvious” given constraints today when someone comes back to this months or years from now it’s likely some of those constraints could have changed or been removed completely - ignoring this is how you end up not changing things out of fear that something will break without real understanding.
Comments are almost never a problem unless they’re not updated when significant changes are made
I agree context is everything, and that’s why it’s a bad idea to embed usage info or instructions about the contents or meaning of a parameter file into that very file.
Somewhere else, something has to choose to load that file, and that is where the documentation belongs (in addition to readable, separate artifacts that are generated from the file).
For example, suppose you need to rewrite the parameter file from YAML to Toml, or you need to add a new layer of nesting and some post-processing logic at load time.
The meaning of these things has no context inside the parameter file itself. It only has meaning at the point some other system consumes it. Another system could consume the exact same file and choose to interpret all the parameters with different meanings in that program, regardless of what any comments says in the param file.
We'll see how it goes!
Cheers
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.
> “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").”
This is the exact anti-pattern that happens as a result of relying on comments in the config file. Your goal of adding that comment about why you changed foo directly in the config file is dangerous and is a very bad practice.
Instead, whatever config file it is that you are modifying (whether for third parties to consume or just for own local Postgres or video game or anything), that file should be turned into a proper package. Place it in a version control repo, and readme and usage documentation for the “why” of the parameter values, and make a tool so that if the end user wants that exact config file, they can “install” it.
For any customized overrides of single settings at run time (so specifically not changes to a config file), it should happen via the end user overriding ENV variables, not mucking around in config files and trusting ad hoc comments found inside them.
Whether documenting semantics of fields belongs in a config file or code (I say both!), it simply doesn't make any sense to say that comments about why specific values in specific files are the way they are belong in the code that parses them. (How can the parsing code have knowledge of all config files out there?)
For local config files that are not shipped with the package, they should still be source controlled in a separate repo (yes, even if you personally are the only one using it, like your local Postgres configuration or something), and you should use a good practice to 'deploy' any changes to your config from the repo into the actual location where the application can recognize that config -- meaning that documentation about the "why" of the parameters once again should absolutely not be embedded inside the config file itself.
A text file sitting next to the config file? I can't see any benefit to that arrangement over just using comments in the file.
Comments that exist in the file in the repo but get stripped out by the deploy process? Again, there seems to be no point to doing this.
Commit log messages? I agree commit logs can sometimes be valuable to see the context of a change, but 1) they're fundamentally about documenting _changes_, not the contents themselves, and 2) the UI is really clunky: git blame, find the line you want context for, then git show on that commit.
If you don't embed those comments you bereft that file of context -- why, as you admitted "is everything".
>Somewhere else, something has to choose to load that file, and that is where the documentation belongs (in addition to readable, separate artifacts that are generated from the file).
Well, that's not really relevant. People who change configuration are 99% of the time not the same as those who write/read/or even have access to the code that reads it.
Imagine Apache or Postgresql configuration for example.
Admins change those all the time, but don't have anything to do with the Apache or Postgresql project, and don't ever care to read their code.
On top of that, my particular settings in some config file, are based on MY local server and needs and my context, and not on something Postgresql or Apache devs will know themselves.
But more generally, it’s bad that a lot of applications don’t offer documented ways to modify config through ENV variables.
A config file should always be code reviewed, versioned and checked into SCM. One side effect is that end users, sys admins, etc., should never be given the chance to inject their customizations through locally modifying the base config file. That should be straight disallowed, so that distributing config files (such as the default, or bundles of other settings commonly used in unison) is part of packaging and deployment, and end users use other mechanisms that allow overriding defaults in a case by case manner.
Then you are talking about perhaps a shell script that sets dozens of ENV vars to override what comes from a (never modifiable) config file, and sure you might document the why of your choices in that shell script with comments, and at no point would anyone need or want comments in the actual config file(s).
Expand this to everything a sysadmin has to manage it just doesn't scale.
This is a glib strawman that has nothing to do with what I said at all.
If you intend to modify config files directly, then you should be able to find the relevant documentation, source code comments, etc., on what the config entries mean or why a value is chosen as the default without needing comments in the config file. This is in no way related to your wild idea that “most developers who use postgres should be familiar with its source code..” (which is not at all what I said and is not at all a reasonable characterization. Reading a tiny bit of source code or docs to find one type of comments is utterly and completely different than your gross mischaracterization that it’s somehow a claim that people would need to be deeply familiar with a bunch of source code.)
I guess this is right if config files are only machine read and written. When I am prototyping, config auto-gen tends to come pretty late in the project (for me), and I like being able to comment things.
I also like types and time-date parameters (which JSON doesn't provide unambiguously), so by the time I've done, I've reinvented YAML+, and that's a mess, so I actually appreciate TOML quite a bit... (At the very least - I get to be a retard[0] about config later in the process)
[0] To the inevitable person that's going to call me an able-ist for using the term, I'm using the term in a self-denigrating way, ...
No, I meant omitting these features is very useful for humans reading and writing config files. Comments utterly don't belong in config files. They belong in the sections of code that load specific config files and convert their contents into defaults or parameters.
A config file is just some file. Its contents have no conventional meaning. It only takes on a meaning in the context of the specific system that uses it.
Also, it can be really hard to find where exactly a configuration value is used. You may have to trace through a ton of code to find the place, and then you can't be sure that's the only place it's used.
Configuration comments are crucial, both for onboarding new users (explaining what the default is if you don't set a value, explaining what the configuration value actually controls, etc) and for experienced users to tell others why this esoteric configuration is set the way it is.
A configuration file is literally just a stack of magic numbers and strings. Why are we setting threadpool to 10 and not 1000? Why are we disabling X feature? What the heck does TPS_Report=true do?
You need comments.
Plus, the documentation in the application code that loads the config and manipulates would function as the exact same reference documentation for any developer trying to understand how the config is used or why a choice is made.
This prevents the documentation about what the config is supposed to be used for from being coupled with the implementation detail of what particular config file looks like, what language it’s written in, etc.
Just as you say, a config file is a stack of magic constants. They have no meaning at all sitting in that file. The place to look for their meaning is the documentation of the code that loads the file, which should tell the user everything they need to know about modifying or providing their own file.
I agree that code review for configuration changes is necessary. That same code review process can ensure that the comments in the config file are also correct.
Also worth noting is that not all config files are committed to version control as-is. If a deployment process bakes the config file from variables, it can be even more disconnected and difficult to find the change.
Yeah, I'll put in a PR for my local Transmission config file and see how far that gets me ;)
Config files should be understandable and readable by the end users so they can customize their local installs.
And what are users who don't have access to the source, or who aren't programmers, supposed to do?
So then, instead of forcing someone else to dig around a file like that, why would you put the docs about your modified config file somewhere else, and in a format that’s much easier to read?
For example you could make a whole git repository solely to hold a certain config file, allowing it to be versioned and even including an “install” script so that some other tool like docker could be used to faithfully reproduce a config setup.
Basically the only examples I have seen anywhere in this thread where people think in-line config comments matter are large desktop applications like Transmission or Postgres which have the unfortunately bad practice of letting users modify complex config files (instead of forcing all overrides of defaults to be ENV variable based).
And even in these cases, it seems more like lazy people who just personally prefer to sling a config file around rather than doing some minimal best practice like putting it in a repo to wrap it up like a mini-package and give much better documentation to someone who might “install” that config than what crappy in-line comments can give, and to enforce code review even for your own local config changes.
Configuration via environment variables is as far from best practice as I can imagine. It prevents proper validation of settings (e.g. a typo can’t be detected because you don’t know which environment variables are used by other programs), not to mention the possible security implications. Besides, these environment variables would have to be set somewhere, like a startup shell script, which I bet would end up with explanatory comments anyway.
This trend of using environment variables is a result of trying to make applications stateless, therefore easier to run in containers. However with something like K8s ConfigMaps, it seems totally unnecessary.
I’d say they are almost identical risks, and for all practical purposes there is no difference. Putting comments inside the config file only makes discovery much harder than putting it in a user guide, man page, etc. with no offsetting benefit of consistency.
> “Configuration via environment variables is as far from best practice as I can imagine”
You are arguing against perhaps the most dominant notion of config best practices in the modern era when you say that [0]. Quoting from the 12 Factor App best practices on config:
> “Another approach to config is the use of config files which are not checked into revision control, such as config/database.yml in Rails. This is a huge improvement over using constants which are checked into the code repo, but still has weaknesses: it’s easy to mistakenly check in a config file to the repo; there is a tendency for config files to be scattered about in different places and different formats, making it hard to see and manage all the config in one place. Further, these formats tend to be language- or framework-specific.
The twelve-factor app stores config in environment variables (often shortened to env vars or env). Env vars are easy to change between deploys without changing any code; unlike config files, there is little chance of them being checked into the code repo accidentally; and unlike custom config files, or other config mechanisms such as Java System Properties, they are a language- and OS-agnostic standard.”
You say,
> “This trend of using environment variables is a result of trying to make applications stateless, therefore easier to run in containers. However with something like K8s ConfigMaps, it seems totally unnecessary.”
I don’t think those are the reasons for putting config into the environment at all. I think a main reason is specifically so that end users modify config with ENV vars that disallow scattered and non-reproducible collections of config (e.g. if you share the command or script that defined the environment, the settings are enforced; if you share something that relied on a local config file you had modified but no one else knows about, they can’t get your settings).
[0]: < https://12factor.net/config >
I don’t know that it’s “dominant”, nor that it’s good merely because it’s “from the modern era”. But even if all that is true, 12 factor apps constitute a small subset of configurable software that is deployed worldwide, and hardly a silver bullet for all kinds of software (it even defines itself as a methodology specific to SaaS applications).
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.
If you want to provide config customizeability as part of an API or interface to third party users (and you should!) then doing it by comments in a file that users modify is insanely bad. Instead, document usage instructions for overriding defaults with ENV vars — customization should never involve mangling a config file outside of version control, and absolutely not by third party devs, system administrators, etc.
In fact, I think your response highlights exactly why relying on comments in config files is such a bad anti-pattern.
My VSCode config files are stored as JSON. They are hand modified all the time.
package.json is a user editable config file, used by millions of JS developers every day.
The .babelrc file to configure the JS transpiler is a user configurable json file.
.eslincrc, used to configure one of the world's most popular JS linters, user editable json file.
Those are all the ones sitting in one folder, and they would all be vastly improved with comments.
Especially the package.json, entire scripts live within package.json files, you run them with the command
npm run <scriptname>
> customization should never involve mangling a config file outside of version control, and absolutely not by third party devs, system administrators, etc.
Config files in general? Of course they need comments.
What about users wanting to set custom key bindings in computer games?
Back in the day, customizing Quake settings was huge. All user editable config files. Little Jimmy's DOS 6.0 games folder wasn't using version control.
Even more recently, users modify config files, often times to fix or get around bugs in a games UI.
How about setting up a mail server? Those are all user editable config files. People running a local mail server aren't going through code review or version control. A sendmail config without comments would be even more impossible to read!
Or just simply .bashrc files.
Config files are used all over the place. Being able to document what happened is incredibly valuable. Not every file in the world needs version control.
> Instead, document usage instructions for overriding defaults with ENV vars
Environment variables are set through configuration files! That is just kicking the ball down the road.
The rest of your examples just rehash the same fallacy mentioned in other comments (which I’ve given adequate responses to already). Large apps that use a local config file are no exception to what I’m saying. That’s still a terrible way to expose customization to an end user, and even if you are modifying some big local config file, like with Postgres, you should be putting your config file into a separate version control repo, versioning it, having comments as part of that repo, treat it like a mini package that gets deployed or installed when you make any changes (which should be code reviewed always, even if you’re just talking about your own config file for some app on your home PC).
Environment variables should not be set through config files, that’s terrible. Rather environment variables being set explicitly should be the way you override whatever default would have been chosen from the config file.
How else do you propose environment variables be set?
Some script someplace has to set those environment variables.
A script that configures environment variables is awfully similar to a fancy config file. Indeed, in the interest of keeping code clean and organized, if a lot of constants, in the form of environment variables, are being set by a script, it might be a good idea to put them all in one file and just import that.
At which point you now have an actual config file!
> That’s still a terrible way to expose customization to an end user,
How would you do bashrc?
There are a lot of small problems for which config files a perfectly fine. Especially configurations aimed at technical users.
Creating a UI around configuration means developer time and effort, and that UI has the potential to have bugs. That UI needs to document what each configuration setting does, and what all the possible valid values are.
If all the config is trivial, and stored in a plain text file, then a text editor is perfectly valid UI for advanced users, and comments in that file serve the same purpose as documentation.
Hell you could make a transformer that takes a config file with documentation and pops out a UI. At which point you've unnecessarily complicated the UI of a text editor.
Indeed one of the niceties of VSCode versus Visual Studio is that VSCode has all its configurations stored in an editable text file. In Visual Studio settings were hidden behind a horrible UI that recently got search put in place. Until that happened, the common way to find a setting in VS was to look up on google where the setting was.
On a related note, Visual Studio uses what is called MSBuild files, fancy XML files that configure the build settings, and instructions, dependencies, etc, for a project. There is a nice UI around it. The nice UI likes to corrupt the configuration file. Advanced users quickly learn that modifying the file by hand is far superior.
> (which should be code reviewed always, even if you’re just talking about your own config file for some app on your home PC).
Bullshit! I am not creating a repro for my config file for my linter. I do however want this comment:
// imports React Native builtin functions
Also comments in repros suck.
Repro comments do not comment on specific lines in a file, they are on the entire check-in.
External tools are needed to determine what commit modified a given line in a file. Hopefully that last commit has a comment about not just what that change to that line did, but what that line is for in general. Heaven forbid if multiple lines were changed.
If I am in the middle of editing a config file, I now need to task switch to another tool, potentially play "guess the commit", and piece together what that line in the config file actually does.
If I'm running some multi-million dollar system off of that config, sure, it can be worth it. But there is a HUGE productivity loss there in comparison to
// boolean, false leaves tabs alone, true converts spaces to tabs
Your entire viewpoint seems to be around mission critical software, which is great for mission critical software. But requiring git be installed so users can setup tabs vs. spaces is insane.
At which point you now have an actual config file!"
I think this is specifically not what is recommended, e.g. read through [0].
> "How would you do bashrc?"
.bashrc is source code that gets executed, not config. Similar with .emacs, etc. Personally, I keep all of these things in a single git repo and then the local files are symlinked to the version controlled files, so that I can document any parameter changes through a PR in GitHub, and it's easy to distribute config files to new places (just clone these types of configs from git). A nice bonus is that putting comments into the config directly is not needed. Anyone (whether my future self or a friend who wants to use my configs from GitHub, etc.) can look at the readme / user guide for the git repo, and not need to go on a fishing expedition for ad hoc comments in the actual files.
> "Especially configurations aimed at technical users."
You can't have it both ways. If users are technical, then they can find what they need in readmes, user guides, and source code comments. There would be no benefit for the comments to be directly in the file, while having comments scattered all over and possibly out of sync from the intended usage instructions would be a downside.
On the other hand, if the user is not technical enough to modify settings in that way, then a user guide and some type of additional API for customization is needed. Overall this suggests the comments belong at the user guide / readme level, since that would be a beneficial way of working for both groups.
> "Bullshit! I am not creating a repro for my config file for my linter. I do however want this comment:"
This just seems like you use bad practices. I have a pretty heavily customized pylint setup for linting my code, and I absolutely do check it in. I actually wrapped it in a simple setuptools package so that I can say, "pip install <my private github URL>" and actually install my custom linting tools (and their settings) as a full (versioned) Python package complete with an exported shell script to control it. Then I can, for instance, just have a conda environment like "my-linter" that has absolutely nothing except for my installed linting tools, and make a bash alias that will source that environment, run the linter, and then deactivate. I'm even considering putting it all inside a Docker container instead of a Python environment.
> "Repro comments do not comment on specific lines in a file, they are on the entire check-in."
Maybe you are using different tools, but this is not true in any source control tool I have ever used. Certainly not true in GitHub or Gitlab.
I honestly don't know what you're talking about with the whole "guess the commit" stuff. Just navigate to a file in GitHub and look at the history (or do this from the command line once you feel comfortable reading file history). If looking at a file in GitHub is too much work for you, well, I can't help you. That's just not reasonable and speaks to extremely bad coding practices if inline comments in config are being used to circumvent meaningful code review that leaves useful commit history.
> "Your entire viewpoint seems to be around mission critical software, which is great for mission critical software. But requiring git be installed so users can setup tabs vs. spaces is insane."
This baffles me. I am not even sure I can parse this as a coherent comment. Requiring git to be installed? What? If you change a file from tabs to spaces, hopefully some linter complains at you based on whatever your team's conventions are. But if you mean changing a setting in a settings file somewhere, then yes, it ought to be checked into something. Why would you think it's reasonable to just hand-edit config like this with zero version history? That's just not reasonable.
To be clear, I am not talking about mission critical software for any of this. I am talking about any type of config you manage. I do all this just on my local machine for my Jupyter config, linting config, emacs, bashrc, etc., all just for my local laptop that I use for recreational programming and random personal computing. Obviously, it matters even more for commercial software.
[0]: < https://12factor.net/config >
Heck Github desktop doesn't even support it, I'd have to check in the file, go to the website, then add a comment. My linter files get thrown in the repro as a matter of fact, so they are at least checked in, but the other two things are more work than I want to worry about for some throw away file that I don't care about.
As to commit histories, I've spend hours of my life digging through commit comments (in multiple different source control systems) trying to find out what the hell some setting did. Often times the config file ended up being grabbed from a branch in some other project, and the revision history is gone.
I've also spent probably dozens of hours of my life tracking down what some random environment variable does. Joy.
Realize you are an extreme outlier. The majority of people in the world do not commit every single config file for their personal projects, nor do they use commit messages as a way to track individual settings changed in the file.
> Why would you think it's reasonable to just hand-edit config like this with zero version history? That's just not reasonable.
Because that is what the majority of people on the earth do. Because it works just fine. Because I have a thousand things to worry about trying to run a startup and the commit history of some file that I really don't care about isn't that important. Being able to write a comment is a nice to have so if by some odd chance I come back to the file years later I know what the heck I did.
I think it is reasonable because life is full of trade offs, and limitations on time, and not everything can be perfect.
> .bashrc is source code that gets executed, not config. Similar with .emacs, etc. Personally, I keep all of these things in a single git repo and then the local files are symlinked to the version controlled files, so that I can document any parameter changes through a PR in GitHub, and it's easy to distribute config files to new places (just clone these types of configs from git). A nice bonus is that putting comments into the config directly is not needed. Anyone (whether my future self or a friend who wants to use my configs from GitHub, etc.) can look at the readme / user guide for the git repo, and not need to go on a fishing expedition for ad hoc comments in the actual files.
I agree github is useful to distribute files, easy to checkout from. But the bashrc on my server is one I copied and pasted by hand, because that is Good Enough(tm) for use on a machine that I'll use the shell for maybe a grand total of 30 minutes a year. Setting up git and going through two factor auth for a file that is literally Never Ever Going To Be Changed serves no purpose. The world would not be better place because a bashrc on a VM is under source control.
Also I'd then have an external facing server with a copy of a personal repro laying around, which could be an information disclosure problem if someone breaks into the server and I check something into github that I shouldn't. (Even non-obvious stuff, like machine names or paths used on internal machines is a type of information disclosure that increases risk.)
(really my VPS provider just had a crap default config that didn't show the current working directory at all, so the bashrc there is a single line)
Likewise, with most of my config files, they are throw away, or write once edit rarely.
FWIW it sounds like you are using github comments instead of inline comments. This only matters if you care about why a line change was made. If you just want to know what a line does, then using comments on github provides no more functionality than adding a comment to the file, except looking up comments on github takes longer.
Checking config files into repros to easily spread them among projects makes sense if you have enough overlap. But saying that github line comments are the one true way to comment lines in a config files is making an absolute statement that you know what is best for everyone's situation. Such a scheme adds no extra value if someone just wants to know what a given line does right now. And I can't think of ever having wanted to look at the history of my linter config. If I am copying it over to a new project, I want to know what lines to keep and what lines to delete based on the type of project I'm doing. Comments in the config file would allow that. Except I don't have comments because JSON doesn't have comments.
In which case I'm now thinking of github line comments as an ugly hack around JSON not having comments.
> It's actually quite important to keep metadata about the config / params / etc. specifically out of those files, so that they are absolutely nothing but value files. Information about why a file contains those values belongs elsewhere
Okay, I'll bite: Why? In every area of programming, we learn that mental context changes are harmful. We learn to avoid gotos, not abuse exceptions, add meaningful comments, and seperate concerns all in large part so when we look at a file, we can understand what's going on without referencing other files.
Now you say "oh, unless there are some config values in that file, then it's important for it to be as cryptic as possible!" Surely you see why that sounds a bit odd? Should we also base64 encode the file? Do you also hate descriptive variable names in config files?
Well, that's like your opinion, man.
If I have something set to some value in my configuration, I want those reading the configuration file (not parsing it, reading it in a text editor, e.g. to make an edit) to know why it's so.
>Applications should document their default settings in a different way
Comments in configuration files are not there to explain default settings, but to document why a setting (default or not, but usually already edit to suit your specific environment) has the value you set it to.
>Information about why a file contains those values belongs elsewhere, and it's an anti-pattern IMO to rely on comments in the config / param file.
That's a statement, not an argument. Why does it "belong elsewhere"? So that you have an extra layer, that few will bother to check?
It is apparently possible to include, and then remove them before usage apparently but I've never tried.
[0]: https://plus.google.com/+DouglasCrockfordEsq/posts/RK8qyGVaG...
Using JSMin would have been a much better idea. At this point though the only downside is that I haven't yet done this for saving JSON. It's a harder problem but I don't see why it wouldn't also be doable.
edit: Apparently this library allows you to have comments, and will even preserve them when saving the JSON file.
And it’s not like there isn’t any potential problems with some YAML or TOML library you import. Rails Yaml comes to mind.
I have been working on a TOML reader/writer for golang that supports read/change/write and format (like go fmt) that sometime I will get enough time to actually finish and release. =)
Just a curious thought:
Sometimes it’s handy to have a text file for small bits of numerical data. Would it be possible to extend TOML to have a “csv” section (array of arrays)?
[x,y,z]
1,2,3
4,5,6
7,8,9
[data: x,y,z]
1,2,3
4,5,6
7,8,9It's a horrible joke and I've yet to actually use it, but it makes me happy :)
In my opinion, one of the more useful features was the addition of Joda-style datetimes [2][3][4][5], which disambiguates between various kinds of datetime constructs aren't interchangeable yet commonly conflated. It's fair criticism that the addition of rich datetime types exceeds the language's original 'minimal' goal, but too many other languages and formats these days just punt to RFC3339 and leave no guidance or tooling on how to represent dateless times or timeless dates without introducing a ton of side-effects. This is a place where language standard libs, with few exceptions, have repeatedly dropped the ball, and similarly, language or library-agnostic, generic guidance is nowhere to be found.
TOML raises the bar here, by providing a concept and notation to specify these values at rest, and gives parser writers, as opposed to the users, the task of finding a way to represent these values in whatever way is idiomatic for the given language.
[1] https://github.com/toml-lang/toml/blob/master/CHANGELOG.md [2] https://github.com/toml-lang/toml/pull/414 [3] https://github.com/toml-lang/toml/pull/362 [4] https://github.com/toml-lang/toml/issues/412 [5] https://github.com/toml-lang/toml/issues/263
For some reason, though, I just struggle with the syntax. It says it's "obvious" but it wasn't to me. I think it says something that the README is full of "this TOML would be represented like this JSON", to help you understand what's going on. Every time I saw that, I was like "oh, now I get it." I don't know if that means JSON is just inherently more understandable, or I'm just more used to it, though.
Are there obvious downsides to JSON for config that I'm missing? What are the advantages of TOML over JSON? Maybe eventually it'll "click", though.
I think the following mean the same thing:
[[foo]]
bar = {baz = 5}
[[foo.bar]]
baz = 5
[[foo]]
[[bar]]
baz = 5
for me, there are two. firstly, TOML supports comments.
secondly, TOML or INI is very readable without indentation. i have learned that removing indentation from configuration files makes non-technical people much more comfortable editing the file by hand. when many non-technical people see braces and indentation, they feel overwhelmed and associate it with complexity.
i don't really use TOML's more advanced features, though. i basically just use it like INI.
(Well, I guess there's not that much to win/lose in the area of config languages, but still) (Also, I think it works pretty well, so this is not to downplay TOML!)
I think the moral of the story is: just put your whacky ideas out there and see what happens. You never know when you'll hit a chord.
Pip's choice was made for them in the form of PEP 518 [2]. The authors of PEP 518 explain their rationale [2][3], which largely boils down to XML being too wordy and awkward to hand-edit, JSON awkward to hand-edit, various formats used by existing python tooling were underspecified and implementation-dependent, and YAML's python parsers being fairly complex and hard to vendor.
[1] https://news.ycombinator.com/item?id=7938388 [2] https://www.python.org/dev/peps/pep-0518/ [3] https://www.python.org/dev/peps/pep-0518/#other-file-formats
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 remaining formats, TOML seemed to be the most popular and had the most traction, so I went with that.
It feels like Scala (Lightbend is the company behind Scala) in the sense that there are 100 ways to achieve the same thing and having different levels of "code elegance", but for me it's a plus, since I'm a Scala fan.
# THIS IS INVALID
a.b = 1
a.b.c = 2
name.first = "Bob"
name.last = "Smith"
# Can't do this because name.first has already been defined
# name.first.alternative = "Robert"
# This is too ambiguous
name.alternative = "Robert"
# And this is backwards to me
name.alternative.first = "Robert"
first.name = "Bob"
last.name = "Smith"
alternative.first.name = "Robert"
Because it avoids these problems, your "name.alternative.first" example seems perfectly sensible to me. Alternatively, the name might be an array:
[[name]]
first = "Bob"
last = "Smith
[[name]]
first = "Robert"
Your explanation is perfect and I understand the justification why it isn't possible now - so thanks for that! The array alternative provided by xinau is also an acceptable replacement - maybe even better to be honest, especially in this particular scenario.
>It's probably best to think of TOML as convenient syntax for creating a JSON-like structure. What kind of JSON would you expect as the result of your config examples?
I came back from lunch and realized what I was trying to do didn't make sense while trying to convert it to JSON. Having name.first be both a value and contain an object doesn't make sense - unless it were to contain an array value but then why have the object and not just have the value? All very silly. So I guess my "only issue with TOML" is that I never sat down and tried to express what I wanted to express in any other way. It made a lot more sense in my head than on paper. :)
One key can't have multiple values with different types. For example in json:
{ "name" :
{ "first" : "Bob",
"last" : "Smith"
}
}
{ "name" :
{ "first" : "Bob",
"first.alternative": "Robert",
"last" : "Smith"
}
}
{ "name" :
{ "first" : ["Bob", "Robert"],
"last" : "Smith"
}
}
But this is only a guess.
I've been trying to push RON as an alternative, and it works very well for WebRender, Amethyst, and other projects in Rust.
For the projects I've used TOML on, it was a nice breath of fresh air and a terrific improvement over JSON (still mad about JSON's lack of comments). Simplicity wins!
Homogeneous arrays can come in the following forms
- Shallow, literal type (a list of lists, regardless of the nested lists contain)
- Full, literal type (a list of dicts of strings)
- Logical type
There are many times where a list is the best type for my data but I want to take advantage of logical types for easier configuration by my users.
Below is an example of what I mean by "homogeneous logical types":
`Cargo.toml` has you specify dependencies using a dict
[dependencies]
foo = { "version" = "1.0" }
[dependencies]
foo = "1.0"
enum Dependency {
Version(String),
Specification(HashMap<String, String>),
}I'm not sure I understand your complaint, though, can you give me another example of how it's biting you in real life?
Except the name would be duplicated with the content I'm storing.
As for an example, its effectively Cargo. My use case is very similar (dependency reporting) but my content is slightly different (as I said, the value would effectively duplicate the key)
list = [
"1.0",
"2.7",
{ version = "1.4", path = "..." },
"9.9",
]
https://arp242.net/weblog/yaml_probably_not_so_great_after_a...
Probably because they are the only two features that need delimiters at start and end. The rest are only one-liners or simply stop if the next of the same type starts.
I think the big problem is that YAML is dynamically typed. If I had schema-enforced config files, I'd be perfectly happy to say that for boolean typed data all the values of YES and NO and ON and OFF and T and F and 0 and 1 can all be reasonably interpreted as a Boolean True and False. The problem happens when a string-typed or integer-typed member can also have their ON value interpreted into Boolean TRUE.
Enter TOML: I can paste a bunch of "var_x = 2"-type statements (there's like 50) directly from Python, read them as a dictionary and find-replace all appearances in like 5 minutes while I'm waiting for an Uber.
Thanks Tom!
Stylistically, I agree with you as TOML is clean and well thought. Moreover, TOML has support for more data types that JSON lacks leading to ugly workarounds (floats as strings anyone?). The main advantage of JSON is that its encoding/decoding is included in JS as it is, and it's generally deeply ingrained in the Node community.
Of course nothing is impossible, but I think that the ship has sailed. I was just dreaming of what could have been :-) Subtle details in NPM's behavior would've probably been designed differently if it was necessary to make updates to the package file without destroying layout and context.
[[designers]]
name = Guido
lang = Python
[[designers]]
name = Larry
lang = PerlThat all said, for flatter schema's I do personally think TOML is more readable than it's JSON, YAML and XML counterparts. If there is one thing I did like about Windows back when I used to run it, it was the syntax of INI files (which TOML was heavily influenced by).
Ultimately though, there is no perfect solution for all problems.
Yes. But for nested data, I find TOML becomes the least readable and I have to fall back to YAML or JSON.
Maybe we need just one more ML...
I loathe YAML for readability. When I'm 2 pages down on a yaml tree I have no clue how many indents exist before what I'm working on. Likewise, when I scroll up, I quickly lose track of what the actual parent to the data I was working on is. I've found it to be an absolute mess.
JSON doesn't even fit for me, because it's not human intended (imo). Being able to document (comments) configuration is a requirement for me on any config language.
Still there FWIW.
For the most part the language seems like a smarter slightly more flexible INI which I like (although there's no real standard for INI, most formats don't allow for nested arrays or tables,) but why embrace bracket notation for arrays, but not a keyed syntax with the same brackets for tables?
Something like this would have been be a lot cleaner to me:
[designers]
[name = Guido, lang = Python]
[name = Larry, lang = Perl] {
"designers": [
{"name": "Guido", "lang": "Python"},
{"name": "Larry", "lang": "Perl"}
]
}This JSON is also much more readable than the “dot attribute” Toml syntax too, which I think is one of the least intuitive and hardest to read ways of creating nested data structures, certainly vastly less readable than the equivalents in YAML or JSON.
I’ve never understood why anyone would say Toml is easier to read than YAML or JSON. It’s drastically harder to read and more confusing.
[site]
name = "My Great Website"
url = "https://example.com"
author = "Watts Martin"
email = "foo@bar.com"
links = [
{ name = "tom", url = "http://tom.example.com" },
{ name = "bob", url = "http://bob.example.com" }
]
[database]
server = "localhost"
username = "dbuser"
password = "dbpassword"
{
"site": {
"name": "My Great Website",
"url": "https://example.com",
"author": "Watts Martin",
"email": "foo@bar.com",
"links": [
{ "name": "tom", "url": "http://tom.example.com" },
{ "name": "bob", "url": "http://bob.example.com" }
]
},
"database": {
"server": "localhost",
"username": "dbuser",
"password": "dbpassword"
}
}
The equivalent YAML doesn't look bad:
site:
name: My Great Website
url: 'https://example.com'
author: Watts Martin
email: foo@bar.com
links:
- name: tom
url: 'http://tom.example.com'
- name: bob
url: 'http://bob.example.com'
database:
server: localhost
username: dbuser
password: dbpassword
I can agree Toml is sometimes better than YAML, but I cannot agree it is better than JSON. For me JSON is so simple, so easy to read, it has the nice feature of preventing comments and multi-line strings to keep things extremely simple and to enforce that documentation about the values in the file has to be located outside the file, as it absolutely should (documentation should be at the site that uses the config/param file, not inside it).
Plus, I find JSON indentation to be a real joy to assist with reading and seeing the nested structure. That indentation is optional in Toml, but I think pretty much always the use of that indentation ought to be enforced as a convention for people using Toml. Lacking the indentation is really not good for config / parameter files.
"YAML Ain't Markup Language"
It works great based on my small amount of testing, and TOML is awesome! I wish more people start using it.
- 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
No, there is no facility for variable templating, interpolation, references, or anything of the like in toml.
If you wanted that, you could implement it in your application by doing post-processing on strings, or you could not use TOML.
> What is the keyword for null?
If you have "x = 1", you can always comment it out with "# x = 1". There's no specific support for null.
it would be kinda silly to have it anyways since null is a language construct more than anything else, and e.g. some lanuages support mixed strings + nulls in one array, but many don't.
https://github.com/lantiga/clj-toml/blob/0.4.0-instaparse/sr...
What a lovely language! I may have to use it..
> Newline means LF (0x0A) or CRLF (0x0D0A).
Complicating things from the start. Not a good sign.
A language for configs is different from a data interchange language: the former is intended to be written and edited by humans.
See https://arp242.net/weblog/json_as_configuration_files-_pleas...
And you can't expect windows users to always check their editor is lf compliant. Toml is not just for programmers
Changelog: https://github.com/toml-lang/toml/blob/master/CHANGELOG.md#0...
https://github.com/adambard/learnxinyminutes-docs/issues/315...
They're incredibly useful if you need to specify an exact floating point value, and about rounding or precision issues.
Other languages than perl support them, but that article does a good job of demoing them
In any case I'm glad to see it in several open source projects (Mailtrain for example). It's so much easier to read for humans than JSON.