toml-lang / toml

Tom's Obvious, Minimal Language

Home Page:https://toml.io

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Clarify whether whitespace is permissible between the brackets in headers of table arrays

dmbaturin opened this issue · comments

The spec says that this is a valid array of tables:

[[lots_of_tables]]
  foo = 1
  bar = 2

It doesn't say whether this is an invalid array of tables:

[ [ lots_of_tables ] ]
  foo = 1
  bar = 2

The ABNF grammar file does suggest that it's an inseparable token, but it would be nice to have a verbal note in the spec as well, like:

The double bracket is an inseparable token, and attempts to insert whitespace between the brackets (`[ [` or `] ]`) will cause prase errors.

I don't think the specification text needs to contain every last possible thing. It's pretty obvious from the ABNF, as well as "common sense", and there are already tests for this (since 2015):

[~cp/toml-test](master)% ag  '(\[ \[|\] \])' tests/invalid/
tests/invalid/table/llbrace.toml
1:[ [table]]

tests/invalid/table/rrbrace.toml
1:[[table] ]

If we were to describe every single last "invalid test" in the toml.md text then we'd double the size of that.

Thanks for filing this issue @dmbaturin! ^.^

As you've noticed, TOML's syntax is formally described in the ABNF grammar. I don't think this is something that should get additional clarification, since there are many other instances where similar styles of clarifications are deferred to the ABNF (as @arp242 has mentioned already).

The specification is walking a line between being clear and approachable to regular readers while containing enough information to guide implementation authors; and the goal is for folks interested in the nuances to use the ABNF (or https://github.com/toml-lang/toml-test, for the implementation) to get those nuances right.

I've closed this out since I don't think we're going to add a clarifying sentence like this.