Shebang workarounds

[jaxter184]

I've found KDL to be well-designed to use as a base for a domain-specific scripting language, and shebangs can make scripts more ergonomic to run. Unfortunately, most shebangs are KDL syntax errors (usually because of path separators, but also potentially for other reasons depending on the contents).

I don't think it's a huge deal because the script interpreter can just choose to ignore the first line if it starts with a #! before it passes it into a KDL parser, but my goal in making a discussion about this is to see if anyone's got any better suggestions or examples of this kind of logic being used in the wild. Also, not sure how this kind of workaround would interact with LSPs and syntax highlighters.

There was a mention of shebangs here while discussing a similar syntax: #402, but as far as I can tell, there wasn't an explicit discussion or decision made on whether or not that would be a reasonable thing to do. I wish I had thought about this before the v2 release so they could have maybe been treated as comments (I think that's how the Rust compiler does it?). But such is life.

[zkat]

Thinking about this:

I think the fact that shebangs mean something VERY specific is precisely why it's a good thing that they're illegal syntax in KDL. There can be no doubt that, if your document happens to work, it's because you're using an implementation that gives it an explicit and hopefully expected meaning. You can't accidentally throw your document at a naïve parser and have it suddenly shove unexpected data into your document.

And I don't want to specify exactly what a shebang even means because it would mean supping our toes into the dangerous world of "what is even a file path". For example: KDL has different restrictions about acceptable Unicode characters in literal documents. Then there's case sensitivity, path separators, path escaping mechanisms, etc.

All things that we COULD specify, but they would add a lot more complexity to KDL implementations which might never care to be "executable", even if they want to just ignore the line, and it would significantly increase the size and complexity of the spec itself. Not to mention that / and \ are not the only separators that there ever have been, or that ever will be--and we're talking about a data language spec, not a standard library that can adapt with the times.

So in the end... my personal opinion is that I would rather not spec this. The fact that it's a syntax error protects us from accidental data confusion, and platforms like Node.js have done just fine adding shebang support to their scripts even though it's not legal syntax in the language itself.

[bgotink]

This is indeed strictly speaking not necessary. A script interpreter that wants to support being called via shebang could easily remove the shebang line before sending the script to the KDL parser.
But what about syntax highlighting, IDE support, other authoring tools like a formatter? If the spec doesn't prescribe that #! starts a single-line comment when used at the start of a document, many parsers will not support it and thus error when a shebang is encountered.

The shebang line itself wouldn't have to be specced. We could take an approach similar to what JavaScript did and make a hashbang a single-line comment but only when used at the start of a document.

document = bom? hashbang-comment? version? nodes

hashbang-comment := '#!' ^newline* (newline | eof)

[eilvelia]

platforms like Node.js have done just fine adding shebang support to their scripts even though it's not legal syntax in the language itself.

It's legal since proposal-hashbang has been accepted (node 12+)

[zkat]

Should we turn this into an issue, then? With the upcoming RFC work, I think that’ll give us room to slide in a few extra features on the language. Although I still feel like it’s a bit strange to have shebangs in a config language.