Toml: Indentation does not mix well with directly entering arbitrarily nested tables

[scooter-dangle]

The current TOML spec (v0.4.0) says that "indentation (tabs and/or spaces) is allowed but not required".

The spec gives an example of indenting where a table's non-table contents are indented at the same level as the table, but nested tables (and the nested tables' contents) are indented one level. E.g.,

[a]
data = 8
  [a.b]
  data = 17

In indented TOML in the wild, I've often seen the tables' non-tabular contents also indented an additional level, e.g.:

[a]
  data = 8
  [a.b]
    data = 17

In describing the issue, I'll use the former indentation style, but the issue applies to both styles.

The issue is that, when directly entering a deeply nested table without first declaring the parent tables, indented TOML can be both unintuitive and deceptive, which hinders it in its objective of being easy to read.

Examples

Example 1

Incorrectly(?) indented, it visually appears that a.b and z are at the same level of nesting from the root of the table, which is incorrect:

data = 8

[a.b]
data = 17

[z]
data = 3
  [z.b]
  data = 9

However, indenting a.b to the correct level is unintuitive. Without its enclosing parent, a, it hangs on its own out to the right:

data = 8

  [a.b]
  data = 17

[z]
data = 3
  [z.b]
  data = 9

This is sorely exacerbated when the level of nesting increases, and it becomes an article of faith on the part of the reader that the text is in the correct vertical column:

data = 8

      [a.b.a.a]
      data = 17

[z]
data = 3
      [z.b.a.a]
      data = 9

Example 2

With the first kind of indentation (i.e., indenting only to show nestedness—not to show the full depth of nesting), grandchildren tables of table a appear to be immediate children:

[a]
data = 9
  [a.b.a]
  data = 17
  [a.d.b]
  data = 17

Even with indentation that fully reflects the depth of nesting, the reader still has to ignore the first impression that the two nested tables are direct siblings and notice that they actually have different parents within a.

[a]
data = 9
    [a.b.a]
    data = 17
    [a.d.b]
    data = 17

The solution to the above issues is to either encourage or require explicitly introducing all intervening tables when indenting TOML (or, perhaps, in general). Doing so more immediately illustrates to the reader the relationship between the two descendant tables as well as their relationship to a without the reader having to parse and compare every table declaration.

[a]
data = 9
  [a.b]
    [a.b.a]
    data = 17
  [a.d]
    [a.d.b]
    data = 17

If explicitly introducing all intervening tables from the root to the most nested table is not required, then indentation should be disallowed so that the reader is forced to always determine nesting directly by the bracketed table lines. Some may find this more difficult to read, but it allows for a more succinct (linewise, at least) TOML style while not communicating potentially inaccurate information about the structure of the table.

[a]
data = 9
[a.b.a]
data = 17
[a.d.b]
data = 17

Example 3

Note: An even more deceptive case occurs when re-visiting a previously visited node:

[a]
data = 9
  [a.a]
  data = 17
  [a.b]
  data = 17
[z]
data = 4
  [z.a]
  data = 8
  [z.b]
  data = 8
  [a.c]
  data = 8

The eye is likely to assume there are 3 data = 8 values under z node children, when the last one is actually under a.

However, this particular case would be prevented by https://github.com/toml-lang/toml/issues/446

[ChristianSi]

Indentation is irrelevant for the TOM spec, since it's insignificant. Use whatever indentation style you like (if any).

[scooter-dangle]

Indentation is irrelevant for the TOM spec, since it's insignificant. Use whatever indentation style you like (if any).

My point is that being able to directly enter nested tables makes any indentation style (other than no indentation at all) in TOML deceptive. I think that TOML's aim of being obvious applies to reading TOML, not just writing TOML. The spec's current combination of entering nested tables and agnosticism to indentation makes it non-obvious for the reader to understand what structure is being described.

[TheElectronWill]

Even with indentation that fully reflects the depth of nesting, the reader still has to ignore the first impression that the two nested tables are direct siblings and notice that they actually have different parents within a

[a]
data = 9
  [a.b.a]
  data = 17
  [a.d.b]
  data = 17

I don't get the problem here. My first impression when I read this is that a has some subtables "b.a" and "d.b", which are obviously sub-sub tables. If it disturbs you, just write the intermediate level.

Since formatting is a matter of taste, to me there is no point in changing the specification.

[edward2a]

Hi, was just reviewing TOML as YAML is giving me some headaches and came over this issue.
This looks to me like the argument of python vs ruby.

I like python, it helps write readable code, period.
Ruby allows for easier writing of spaghetti code and that makes it a bad design.
So does perl, and bash, and C.

If you give it a thought, that phrase makes not much sense at all.
You can write crap in whatever language, including python.
Having a strict or lose formatting restriction will not change the fact of the writer being sloppy.

Also consider that, from my understanding, with TOML you are basically getting a free-form extended ini-style ML. There is always going to be a trade off somewhere.

There is nothing stopping you from turning this:
a.toml

[a]
data = 9
  [a.a]
  data = 17
  [a.b]
  data = 17
[z]
data = 4
  [z.a]
  data = 8
  [z.b]
  data = 8
  [a.c] <<<<---- THIS IS BEING SLOPPY
  data = 8

Into this:
b.toml

[a]
  data = 9
  a = { data = 17 }
  b = { data = 17 }
  c = { data = 8 }
[z]
  data = 4
  a = { data = 8 }
  b = { data = 8 }

It may still not be the best approach as the inline table does not fit everywhere, length can be problematic, but I hope I am making a point here.

import toml
>>> with open('a.toml') as f:
...     a = toml.load(f)
...
>>> a
{'a': {'b': {'data': 17}, 'data': 9, 'a': {'data': 17}, 'c': {'data': 8}}, 'z': {'b': {'data': 8}, 'data': 4, 'a': {'data': 8}}}
>>> with open('b.toml') as f:
...     b = toml.load(f)
... 
>>> b
{'a': {'b': {'data': 17}, 'data': 9, 'a': {'data': 17}, 'c': {'data': 8}}, 'z': {'b': {'data': 8}, 'data': 4, 'a': {'data': 8}}}
>>>

@mojombo is there any idea on multi-line tables that could play along with the nesting model?

[mojombo]

Thanks for the thoughts on this @scooter-dangle, I think you make some valid points about how TOML's stance on indentation and auto-subtables could lead to confusion. On the other hand, I think @edward2a nails the reality with this sentiment:

You can write crap in whatever language

Life (and TOML) is a series of tradeoffs. I prefer a bit more rope at the expense of maybe having enough to hang myself with, because it also means I have enough to create some truly beautiful knots. Perhaps at some point a few very nice formatting standards will be added to popular linters and provide a baseline for what makes readable TOML. Maybe not. Either way, for those that take pride in their work, readable TOML files will be plentiful.