Proposal: Array headers

[wasokeli]

I have some top-level arrays that I want to treat similarly to top-level tables:

glyphs = [
    {codepoint = 0x41, name = "A", file = "A.svg"},
    {codepoint = 0x42, name = "B", file = "B.svg"},
    {codepoint = 0x43, name = "C", file = "C.svg"},
]

ligatures = [
    {ligature = "ff", name = "f_f",          file = "f_f.svg"},
    {ligature = "=>", name = "rocket_right", file = "rocket_right.svg"},
    {ligature = "->", name = "arrow_right",  file = "arrow_right.svg"},
]

[special-characters]
"=" = "equals"
"-" = "hyphen"
">" = "greater"

[metadata]
family   = "Font Regular"
designer = "Me"
license  = "CC0-1.0"

My concerns with this setup:

• Same-level arrays have to be physically grouped together; they can't be ordered logically, interspersed with tables. I'd like to order the information as in the following two examples - metadata first, and special-characters before ligatures.
• Unlike table headers, array names can't show how nested they are globally. That would be especially helpful in the domain of font generation, where it can take a while to scroll past several arrays to find an absolute header.
• Array names read as assignments, not as headings. That means it's harder to express information hierarchy to the reader, and they're harder to skim for in large or unfamiliar files.

If I care strongly about these concerns, I can work around these disadvantages. For non-Latin scripts with very tall arrays, the following can be a usability improvement, despite the added code complexity:

[metadata]
family   = "Font Regular"
designer = "Me"
license  = "CC0-1.0"

[glyphs]
data = [
    {codepoint = 0x41, name = "A", file = "A.svg"},
    {codepoint = 0x42, name = "B", file = "B.svg"},
    {codepoint = 0x43, name = "C", file = "C.svg"},
]

[special-characters]
"=" = "equals"
"-" = "hyphen"
">" = "greater"

[ligatures]
data = [
    {ligature = "ff", name = "f_f",          file = "f_f.svg"},
    {ligature = "=>", name = "rocket_right", file = "rocket_right.svg"},
    {ligature = "->", name = "arrow_right",  file = "arrow_right.svg"},
]

But I'd prefer a syntax that doesn't introduce further nesting:

[metadata]
family   = "Font Regular"
designer = "Me"
license  = "CC0-1.0"

[glyphs][
    {codepoint = 0x41, name = "A", file = "A.svg"},
    {codepoint = 0x42, name = "B", file = "B.svg"},
    {codepoint = 0x43, name = "C", file = "C.svg"},
]

[special-characters]
"=" = "equals"
"-" = "hyphen"
">" = "greater"

[ligatures][
    {ligature = "ff", name = "f_f",          file = "f_f.svg"},
    {ligature = "=>", name = "rocket_right", file = "rocket_right.svg"},
    {ligature = "->", name = "arrow_right",  file = "arrow_right.svg"},
]

In short - TOML's headers are very useful, but they're awkward to apply to a domain that uses arrays heavily.

[wasokeli]

Related issues:

• Allow "[]" to return to global scope (for adding sibling array after a table) #456 similarly has trouble with the use case of metadata+list
• Lists in the style of TOML #613 similarly wants to give an array a heading
• Revisit array of table syntax #309 (comment) similarly wants a top-level array to be physically lower in the document, in Cargo

[arp242]

This seems fairly non-obvious syntax and a lot of work for implementations to solve what I would personally consider a minor niche issue. My sense of taste tells me it's not a good trade-off, especially because with TOML 1.1 inline tables you could write it as:

metadata = {
	family   = "Font Regular",
	designer = "Me",
	license  = "CC0-1.0",
}

glyphs = [
	{codepoint = 0x41, name = "A", file = "A.svg"},
	{codepoint = 0x42, name = "B", file = "B.svg"},
	{codepoint = 0x43, name = "C", file = "C.svg"},
]

special-characters = {
	"=" = "equals",
	"-" = "hyphen",
	">" = "greater",
}

ligatures = [
	{ligature = "ff", name = "f_f",          file = "f_f.svg"},
	{ligature = "=>", name = "rocket_right", file = "rocket_right.svg"},
	{ligature = "->", name = "arrow_right",  file = "arrow_right.svg"},
]

Which would also solve your ordering issue.

[wasokeli]

This doesn't invalidate your good points, just to clarify: This Issue is less requesting a specific syntax and more requesting any syntax. The other possibilities that occur to me:

[glyphs][]
{codepoint = 0x41, name = "A", file = "A.svg"},
{codepoint = 0x42, name = "B", file = "B.svg"},
{codepoint = 0x43, name = "C", file = "C.svg"},

[glyphs[]]
{codepoint = 0x41, name = "A", file = "A.svg"},
{codepoint = 0x42, name = "B", file = "B.svg"},
{codepoint = 0x43, name = "C", file = "C.svg"},

[ChristianSi]

@KelseyHigham: That syntax unfortunately looks quite close to [[glyphs]], which has a different meaning.

[arp242]

This Issue is less requesting a specific syntax and more requesting any syntax

Are the inline tables not good enough? That seems "any syntax" that would solve it?

[wasokeli]

What I meant more precisely is any syntax that allows me to keep using TOML headers with the readability benefits they bring (they look and work like headings, they're reorderable, they list their absolute path).

Like yes, I can dispense with TOML headers entirely. But then I'm converting my entire file to this other format, and asking my users to configure their fonts in what's effectively JSON with comments. At that point I'd rather just add the redundant nesting level to every array.

[svew]

I'd like to shamelessly plug my (closed) proposal #1052 as a remedy for the issues you're describing (In short, use + as a special "array appending" key, so we can use the typical table syntax with lists):

Array names read as assignments, not as headings

I propose(d) this as a new syntax for this situation:

[glyphs]
+= {codepoint = 0x41, name = "A", file = "A.svg"}
+= {codepoint = 0x42, name = "B", file = "B.svg"}
+= {codepoint = 0x43, name = "C", file = "C.svg"}

Where + in the table key position indicates you are referencing a new value being appended to the list described by the header, and = indicates assigning to that value (just like with tables). This lets you use the TOML headers we all love, while also being visually distinct enough (in my opinion) for readers to pick up that this is an array.

You could even break down your inline tables into header-defined tables by moving the appending key into the header path, indicating that your header is referencing a new tabular subelement of glyphs:

[glyphs.+]
codepoint = 0x41
name = "A"
file = "A.svg"

[glyphs.+]
codepoint = 0x42
name = "B"
file = "B.svg"

Same-level arrays have to be physically grouped together; they can't be ordered logically, interspersed with tables.

My proposed syntax makes it easy to split lists and append to them at various points in the config file, just like how you can with tables:

[glyphs]
+= {codepoint = 0x41, name = "A", file = "A.svg"}
+= {codepoint = 0x42, name = "B", file = "B.svg"}

[glyphs]
+= {codepoint = 0x43, name = "C", file = "C.svg"}

Unlike table headers, array names can't show how nested they are globally

If you want to put your list under, for example fonts.helvetica.glyphs, in TOML 1.1 you'd have to write a header [fonts.helvetica], and then have a value assignment for glyphs. With my proposal, the entire path can be put in the header, so it becomes visually distinct like you mentioned.