Toml: Tom's Obvious, Minimal Language

https://github.com/toml-lang/toml

by wheresvic1 • 8 years ago

358 195 8 years ago

github.com

somedudeatwork• 8 years ago

I never really questioned the name, TOML, but I guess "Tom's Obvious, Minimal Language" works

gnuvince2• 8 years ago

To me, there was nothing obvious about the double bracket syntax, e.g.:

    [[designers]]
    name = Guido
    lang = Python

    [[designers]]
    name = Larry
    lang = Perl

cies• 8 years ago

Yups. And making a whole datetime RFC part of the spec kind of broke with the "minimal" thing. But apart from that I totally prefer it over INF/YML/JSON/XML for many purposes.

laumars2• 8 years ago

I agree about the double bracket syntax however I don't think that is part of the specification any more, instead nested structures use a dot notation inside single brackets. Both solutions do still feel like a hack though, but the dot notation is definitely less ugly.

That 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.

krapp• 8 years ago

Yeah, that's weird.

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]

agumonkey2• 8 years ago

indicates an 'open' array ?

mojombo28• 8 years ago

Yeah, it's not my favorite part either. We've made them mostly unnecessary by adding inline tables, but for heavy nesting of arrays of tables, you still need to use them, which is why I mentioned that there are still some weaknesses for large, complex config files. Hoping to make this better in 2.0.

fastball• 8 years ago

I'm more a fan of YAML.

"YAML Ain't Markup Language"

clhodapp• 8 years ago

TOML and YAML both have kinda weird names because both were initially incorrectly said to be a "markup language" and then subsequently renamed. The original names were "Yet Another Markup Language" and "Tom's Own Markup Language".

laurent123456• 8 years ago

(2013)

aloisdg2• 8 years ago

v0.5.0 is a new release!

Changelog: https://github.com/toml-lang/toml/blob/master/CHANGELOG.md#0...

mojombo28• 8 years ago

Yes, we just released it two days ago! I know v1.0.0 has been a long time coming, but it's important to me that we get it right, as specs have a very long-lasting impact (much more so than a specific version of a library). We are indeed working hard towards a proper 1.0 though!

mojombo28• 8 years ago

Hey, 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 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!

nixpulvis3• 8 years ago

Hi Tom, huge fan of this project.

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.

mojombo28• 8 years ago

1. How would the file path type differ from a regular string? Would you want specific semantic validation for each platform?

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?

[1] https://github.com/toml-lang/toml/issues/522

KirinDave2• 8 years ago

Hi Tom. Dave here. I like a lot of the features in TOML, but I'm curious, can I have a pony?

(Folks downvoting, PLEASE JUST LET PEOPLE HAVE JOKES EVERY NOW AND THEN)

mojombo28• 8 years ago

Hi Dave! Ponies come standard in TOML, you just have to know where to look. =)

nixpulvis3• 8 years ago

No soup for you.

kemitche• 8 years ago

Toml is better than a pony. Proof: http://toml.versus.horse

btilly2• 8 years ago

You aren't going to change what people around here like. And complaining about downvotes usually just attracts more.

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.

stevefan1999• 8 years ago

This project reminds me of the good old INI files.

mojombo28• 8 years ago

As it should! It was inspired by INI, but with a desire for a proper spec that unambiguously maps the config file to a hash table.

echohack5• 8 years ago

Hey Tom,

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!

mojombo28• 8 years ago

Amazing, thanks for the heads up! I'll add it to the list of projects using TOML [1] and take a look at your example configs to get some more real-world uses cases to look at when evaluating future changes to the spec.

[1] https://github.com/toml-lang/toml/wiki

jhabdas• 8 years ago

The one problem I've had, and perhaps I'm just doing something incorrectly, is going from a `[[something]]` back to a `[thing]` without TOML thinking that `thing` is part of `something` it's not.

mojombo28• 8 years ago

Curious. In order to be part of one of the tables in the [[something]] array, a table would need to be named [something.X]. What parser are you using? it's possible that it's behaving improperly in this case.

See the relevant part of the spec here: https://github.com/toml-lang/toml#user-content-array-of-tabl...

hyperpape2• 8 years ago

I'm a pretty big fan of TOML, though I've mostly only used it for Cargo.

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.

mojombo28• 8 years ago

The limitations are mainly around nested arrays of tables. As has been mentioned here already, the [[array-of-tables]] syntax that currently allows this can be super confusing, and is definitely the worst part of TOML right now. Even so, you can often work around this weakness by reworking your config file to pick up on a specific naming scheme (perhaps every "server-*" table is interpreted as a member of an array) or maybe there's an array of strings that contains the names of the tables, each of which becomes an array member in that order. But these are hacks, and it would be nice to have a first-class way of dealing with nested large tables that was easy to scan and not too repetitive.

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.

andrenth5• 8 years ago

I think HCL (Hashicorp Configuration Language) reads much better than TOML when there are nested sections in the config file.

ksec• 8 years ago

There are still some weaknesses in TOML that make it non-optimal for large, complex config

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?

mojombo28• 8 years ago

I'm always in favor of small config files, but sometimes for larger projects that's just not possible (or desirable). TOML has always been about being as simple as possible while still solving a wide range of problems. But I think of it as the 80% solution, where 20% of projects might need something more powerful to solve their more complex needs, and that's ok. We still need a super simple config file format for the 80%.

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.

dustingetz• 8 years ago

Tom, have you heard of EDN and Transit? Like JSON, but:

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

http://blog.cognitect.com/blog/2014/7/22/transit

mojombo28• 8 years ago

I have not, and while it looks cool, it seems to be optimized for data transfer between applications, not a human readable config format.

svacko• 8 years ago

There is also a similar project - Hjson, a user interface for JSON- https://hjson.org/

DonHopkins• 8 years ago

So like YAML, TOML ain't markup language either, despite the recursive acronym and the "ML" suffix. If your name was Mark instead of Tom, would you have named it MARKML, and would it still not be markup language?

adrianmalacoda• 8 years ago

This does not claim to be a markup language.

According to the repo history, it did... 5 years ago, until someone noticed and corrected it.

gregn610• 8 years ago

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!

alokitr2• 8 years ago

I found the double square bracket syntax useful and understandable

Really? I had kind of the inverse reaction to it. Indeed useful, but definitely not understandable

kolpa• 8 years ago

Json allows comments, but they have to be in string fields of an object so they survive reserialization.

mlthoughts201820• 8 years ago

I used to feel this way, and also used to be frustrated about multi-line strings in JSON. With years of experience now, though, I actually appreciate JSON omitting these features.

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.

mojombo28• 8 years ago

You're welcome, really glad you like it, and good to know the double square brackets make sense to you! It does seem to be a bit polarizing, so we'll keep working on something even better.

spondyl• 8 years ago

JSON used to support comments but they started being used for unintended things like parsing directives.[0]

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...

ErikAugust2• 8 years ago

{ “_comment”: “The comment goes here!”, “name”: “foo” }

liquidgecka• 8 years ago

damn it.. of course you would update the spec right before I release my config parser. =)

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. =)

mojombo28• 8 years ago

Hah, sorry! You can always release an 0.4 compatible first, and then add the stuff from 0.5. Sounds like a great project!

elcritch• 8 years ago

That TOML started out tongue-in-cheek makes it all that much better!

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

Or perhaps it’d have to be:

    [data: x,y,z]
    1,2,3
    4,5,6
    7,8,9

11235813213455• 8 years ago

TOML needs anchors (like yaml)

zifnab06• 8 years ago

Tom here (not the creator or TOML). Every time I have a "what are we using for configuration" discussion at work for a new project, I get to say "let's use TOML, it's obviously superior, just look at it's name!".

It's a horrible joke and I've yet to actually use it, but it makes me happy :)

wiradikusuma• 8 years ago

For more complex config, I highly recommend HOCON (https://github.com/lightbend/config/blob/master/HOCON.md), and its parser in Java (https://github.com/lightbend/config).

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.

afraca2• 8 years ago

Does anyone know why such a "joke proposal" (as stated by the author itself) was chosen for pretty significant projects like pip and cargo? (edit: I tried to say it began as something small and personal)

(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!)

mojombo28• 8 years ago

Well, it was only a joke to begin with. I couldn't stand the complexity or ambiguity of YAML and one night I had a few drinks and banged out my thoughts on something better. When people started writing implementations, I realized that TOML might actually have legs and started tightening it up and removing the snarky bits. I guess these projects felt the same pain I did about config files and presto!

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.

afraca2• 8 years ago

Thanks for response. I edited my response to be less snarky. Good job and thanks for the moral of the story.

niftich2• 8 years ago

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 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

pcwalton• 8 years ago

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 remaining formats, TOML seemed to be the most popular and had the most traction, so I went with that.

jonny_eh• 8 years ago

The name for this is the "Genetic Fallacy"

https://en.wikipedia.org/wiki/Genetic_fallacy

skrebbel2• 8 years ago

If only package.json had been package.toml

jxub• 8 years ago

Would that be hard to implement for npm/yarn? I'm sure that transforming TOML to JSON on the fly could be added as a step somewhere, resulting in changes to the package manager or just a wrapper command.

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.

skrebbel2• 8 years ago

It would not be trivial because npm/yarn don't just read package.json but also modify it. See numerous GitHub issues in either repo about supporting comments inside package.json.

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.

niftich2• 8 years ago

The news here is (presumably) the announcement of version 0.5.0 a few days prior [1], which includes several clarifications, rollup changes, and enhancements that accumulated over the last 3 years.

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

mojombo28• 8 years ago

Glad you like them, we spent quite a bit of time getting them right! Datetimes are a horrible mess of complexity, but hopefully over time languages and tools around them can standardize on a set of common primitives to make all our lives a bit less horribly messy. =)

dvfjsdhgfv• 8 years ago

Used to be called "INI file" in the past...

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.

runjake• 8 years ago

As mentioned in the source link, the INI format is not standardized. This is an attempt at a standardized format similar to INI.

mojombo28• 8 years ago

Yeah, TOML is definitely INI inspired, but there is no canonical INI spec. I wouldn't say that TOML is INI, though. INI files still exist in their variously poorly specified ways.

epage4• 8 years ago

Originally, I was fully on board with the homogeneous array requirement but its recently started causing me pains.

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" }

but allows a short-cut syntax where a string value is assumed to be the version value in the above dict.

  [dependencies]
  foo = "1.0"

Generally this is done in Rust using Enums

  enum Dependency {
     Version(String),
     Specification(HashMap<String, String>),
  }

mojombo28• 8 years ago

Homogenous arrays are partly to make implementations easier, and because if you really need that flexibility, you can always use an array of inline tables, which has the benefit of giving each sub-element a name, hopefully increasing the obviousness.

I'm not sure I understand your complaint, though, can you give me another example of how it's biting you in real life?

epage4• 8 years ago

you can always use an array of inline tables, which has the benefit of giving each sub-element a name, hopefully increasing the obviousness

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)

otterpro• 8 years ago

I 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_probably_not_so_great_after_a...

mojombo28• 8 years ago

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!

k__• 8 years ago

I have to admit, the string and array syntax are the only parts that keep me from using it instead of YAML.

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.

Pxtl2• 8 years ago

There is no fuzzy interpretation of things like YES and NO

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.

EamonnMR• 8 years ago

It's surprisingly easy to add it as an optional drop-in, ex: https://github.com/EamonnMR/OpenLockstep/blob/master/data.py...

tpaschalis• 8 years ago

Just dropping a useless comment to say thanks! Between Tom's work on Github, Jekyll, and TOML, I think he has influenced a vast amount of developers!

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!

mojombo28• 8 years ago

It's never useless to say thanks! I really appreciate your kind words, it's the fuel that powers a lot of open source. Keep it up!

erikpukinskis• 8 years ago

Not to mention inventing MySpace!

thanatropism• 8 years ago

Funny enough, I learned how to/started to use TOML today. I was running some [redacted] experiments using a .pyc compiled script and wanted to experiment with parameters -- but then I had to compile the script again and again.

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!

mojombo28• 8 years ago

Awesome, sounds like the perfect use case for TOML!

timvisee• 8 years ago

Cool. TOML is used quite extensively in Rust projects. I think it's awesome for very simple configurations. And newcomers don't have to learn anything in order to change a TOML configuration, which is very powerfull.

mojombo28• 8 years ago

Yeah, Cargo and Rust have been really important in TOML gaining adoption. Love the Rust community!

kvark• 8 years ago

TOML is a great format, but it can not universally replace JSON, because it's designed for small nested depth.

I've been trying to push RON as an alternative, and it works very well for WebRender, Amethyst, and other projects in Rust.

miguelrochefort• 8 years ago

Looks a lot like Rebol/Red.

losvedir• 8 years ago

I just started a rust project and so had to learn TOML since that's what the package manager (and a lot of the ecosystem) uses.

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

But I don't think the following works:

     [[foo]]
     [[bar]]
     baz = 5

That is, I think the double bracket syntax always starts at the top level? While the `=` are relative to the double brackets above it? Something about all that is non-obvious to me, and I don't love that there's multiple ways to do the same thing.

Pxtl2• 8 years ago

Yeah, most of TOML looks good, but the .INI style [table] and even wierder the [[table-array]] thing seems like they were trying to hammer a square peg into a round hole for the sake of having config files that look like INIs.

scrollaway• 8 years ago

Backwards-compatibility with ini is in my opinion one of the more powerful aspects of TOML which help adoption. Kinda like how UTF8 is ASCII-backcompatible.

woodrowbarlow• 8 years ago

Are there obvious downsides to JSON for config that I'm missing?

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.

TooBrokeToBeg• 8 years ago

Whitespace means tab (0x09) or space (0x20).
Newline means LF (0x0A) or CRLF (0x0D0A).

Complicating things from the start. Not a good sign.

boramalper• 8 years ago

Well some (many, actually) people use Windows too, and some prefer tabs and some prefer spaces; I can’t see why this is a problem?

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...

sametmax• 8 years ago

Indentation is not significant.

And you can't expect windows users to always check their editor is lf compliant. Toml is not just for programmers

Nadya2• 8 years ago

Since Tom is browsing, I have a question - and this is my one and only major issue with TOML.

     # THIS IS INVALID
     a.b = 1
     a.b.c = 2

Why? I'm sure there is very good reasoning - but it makes me have to reason about my data in a manner I consider backwards/confusing.

     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"

Some people might suggest to instead do

     first.name = "Bob"
     last.name = "Smith"
     alternative.first.name = "Robert"

But now nothing is scoped to [name] and if I need to get the full name I can't just pull in [name] but need to pull in [first], [last], and [alternative]. That's really messy in my opinion. All of these are names and should be scoped to [name] and not their own structure.

latk• 8 years ago

Because the "a.b" is not a key, but a table "a" that contains an entry with key "b". If you write "a.b = 1" then that integer is not a table, and can't have an entry called "c".

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"

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?

Nadya2• 8 years ago

Because the "a.b" is not a key, but a table "a" that contains an entry with key "b". If you write "a.b = 1" then that integer is not a table, and can't have an entry called "c".

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. :)

xinau• 8 years ago

I don't know if this is the intend of Tom, but I was also stumbling on this issue and the only reasonable explanation I can come up with is that:

One key can't have multiple values with different types. For example in json:

  { "name" : 
    { "first" : "Bob",
      "last" : "Smith"
    }
  }

How would you add a "alternative" key to the "first" value type. The only way i can think of is something like this.

  { "name" : 
    { "first" : "Bob",
      "first.alternative": "Robert",
      "last" : "Smith"
    }
  }

or as @latk suggested, let "first" be an array, with it's first entry being the non alternatives.

  { "name" : 
    { "first" : ["Bob", "Robert"],
      "last" : "Smith"
    }
  }

I think this is by design. To quote @mojombo "simple configuration file that maps unambiguously to a hash table".

But this is only a guess.

anonu• 8 years ago

How does toml compare to Google protobufs as a configuration system?

mojombo28• 8 years ago

Protocol Buffers is a data serialization format and unsuitable for configuration, as the binary serialized data is not human readable.

exabrial• 8 years ago

Does TOML have a schema?

mojombo28• 8 years ago

Not currently, but it's something I'd like to add as a separate spec sometime later.

firepoet• 8 years ago

In case you're curious, one of the Clojure libraries I found while researching TOML seems to have an ABNF grammar. It sits at the top of this file:

https://github.com/lantiga/clj-toml/blob/0.4.0-instaparse/sr...

What a lovely language! I may have to use it..

kaushalmodi• 8 years ago

Here's the TOML parser in Nim language: https://github.com/NimParsers/parsetoml.

It works great based on my small amount of testing, and TOML is awesome! I wish more people start using it.

andris9• 8 years ago

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...

noisy_boy• 8 years ago

Some 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

TheDong• 8 years ago

interpolation?

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.

amai• 8 years ago

The syntax for tables is awkward compared to CSV (This is actually also true for XML, JSON, YAML).

amelius• 8 years ago

I'm not a fan of configuration files. Instead, I prefer the style of "calling" the program from within a script, and passing the configuration as parameters. This also allows to pass e.g. callback functions. Imho, this is much more flexible, and the advantages grow over time, whereas configuration files tend to accumulate awkward/convoluted constructs as the software matures.

mchahn• 8 years ago

Should it be called a "language" when it has grammar but no semantics? (just curious)

Toml: Tom's Obvious, Minimal Language

Related Stories