Introduce yaml formatting

[nnmrts]

For easier and more efficient editing, I propose adding a .vscode/settings.json file that enables autoformatting YAML (in VSCode at least). I also included the autoformatted masterlist.yaml in this PR.

Sadly, there is seemingly no VSCode extension that allows configuration to format YAML to precisely follow the guide at https://loot.github.io/docs/contributing/Masterlist-Editing:

Arbitrary string values should be enclosed in single quotes. If the string contains any single quotes, they should be repeated.

The part I emphasized from the quote above is handled differently by the most common yaml formatters in VSCode. A single quote string containing '' to escape ' is not kept as is, unless that same string also includes ". Instead the whole string is converted to a double quoted string in that instance (an example of that behavior can be seen in the formatted masterlist.yaml included in this PR.

At several places I've read that single quote and double quote strings can actually mean different things in YAML, but I'm not sure if that is relevant in this context and if some double quoted strings would break any YAML parsing done by LOOT or other modding community tools. Replacing ' in strings everywhere with "proper" apostrophes (’) as a workaround wouldn't be a feasible option because file name strings need to be exact and could include ' meaning either apostrophe or single quote.

[nnmrts]

Also, in case this gets accepted, before merging it should probably be discussed at a central LOOT place like https://github.com/loot/loot or the LOOT Discord server, especially because https://loot.github.io/docs/contributing/Masterlist-Editing needs to be updated then.

[Ortham]

I'd be fine with changing the formatting to use double quotes instead of single quotes when any escaping is needed if it means auto-formatting would be easier.

At several places I've read that single quote and double quote strings can actually mean different things in YAML

AFAIK they mean the same thing but there are strings that you can express in double quotes that can't be expressed in single quotes. That does mean that parsing double-quoted strings is more difficult, but I don't think that really scratches the surface of what makes parsing YAML famously horrible.

[pStyl3]

I too would be fine with changing the formatting to use double quotes instead of single quotes.

However, I don't think that it would be necessary to change the indentation of # comments or to remove empty spaces, e.g. changing subs: [ 'someurl' ] to subs: ['someurl'] reduces readability in my opinion.

[nnmrts]

I don't think that it would be necessary to change the indentation of # comments

• @pStyl3

Unfortunately I couldn't find a way to avoid this with the current yaml formatter.

or to remove empty spaces

• @pStyl3

See 1ea16ba, which I hoped would fix this but it didn't.

I'd be fine with changing the formatting to use double quotes

• @Ortham

I too would be fine with changing the formatting to use double quotes

• @pStyl3

Nice, I also prefer double quotes. See 5ac47bc.

However, that's also not perfect. Condition strings, which of course often include double quotes themselves, and single quoted file strings with regex patterns are seemingly kept as is. One way or another, it seems to be the case that we have to be okay with mixed quoted strings.

What's worse in my opinion: the formatting isn't "deterministic" or rather "input-agnostic".

Take this string for example:

  - name: "legendaries\\.es[mp]"

Whatever "yaml.format.singleQuote" is set to, the formatter keeps this string as is. However, if the string looks like this:

  - name: 'legendaries\.es[mp]'

"yaml.format.singleQuote" also makes no difference and the string is kept as is.

This could obviously lead to both styles being present in the final file and yet again, manual review of the format is necessary.

Unless you're okay with that, I'll look into other yaml formatters, but after my recent research about them, I think the situation, at least regarding JS-based yaml formatters, is dire.

[nnmrts]

In my latest commit, I switched to the extension "Better YAML Formatter", which reintroduced unconfigurable single quotes but fixes this:

changing subs: [ 'someurl' ] to subs: ['someurl'] reduces readability in my opinion

• @pStyl3

I tried several different and increasingly obscure options but I think this is the best I can do without writing a not insane yaml formatter myself.

[Ortham]

Sorry for the delayed reply, but I've just taken a look at the latest formatting, and I'm happy with it. Thinking about how to explain it in the style guide, would it be accurate to say something like the following?

If it's an arbitrary string that doesn't contain any single quotes or any characters that need to be written as escape sequences, enclose it in single quotes. If it's an arbitrary string that contains single quotes or characters that need to be written as escape sequences, enclose it in double quotes and escape anything that needs to be escaped (including any double quotes).

[nnmrts]

Sorry for the delay as well, GitHub's notification system seriously got some explaining to do here...

@Ortham Yes, that makes sense and looks good to me, but obviously the autoformatter can't always follow these rules as I said. I don't know if that's a big deal and/or people should be aware of it. Might be useful as a side fact somewhere on that same page or even as a second sentence; could even link to this issue here.