Magic Characters

[swift2plunder]

Sometimes serialization formats share the wire. When this happens, it's useful to be able to tell from reading the first couple characters that the content should be routed to parser X. For example, "<" is a sign that we're in the XML family, "(" that we're looking at s-exp, "{" would be JSON, "%" YAML, etc. I would like to suggest that starting KDL documents with a node comment, "/-" (perhaps with some convention regarding metadata, such as version) would be a good best practice and perhaps a reasonable protocol recommendation

[zkat]

I mean... your examples don't even work for the languages specified?

• { could be Dhall (comments) or JSON5, among others, for example.
• YAML doesn't need to start with %.
• JSON doesn't need to start with {. There's no requirement that the toplevel be an object. It could be an array! Or any other type.
• < could be html5

As such, I'm not sure there's much we can do here on the KDL side to facilitate this use case. Perhaps the approach needs to be addressed instead?

[larsgw]

From my perspective at least some of those formats have a pattern that generally identifies it. In a certain project I use /^\s*(\{[\S\s]*\}|\[[\S\s]*\])\s*$/ for JSON (i.e. a file starts and ends with either {} or []), the near equivalent of /^((\s{2})*(-\s)?[\w-]*: .+\n)+$/ for YAML (i.e. each line starts with spaces, optionally a dash, and a field) and could reasonably use something like ^\s*<.+> for XML and HTML. It's far from perfect and because of that it's only useful in certain settings, but KDL doesn't have any such pattern I don't think. The only relatively uncommon syntax is the block comment /-, which usually doesn't appear. But that doesn't mean it has to have a pattern, and I wonder whether it even helps to standardize an opt-in pattern if it is not being recommended.

That said, maybe the absence of special syntax is enough? Something like this: /^(\s|\/\/.+|\/\*[\s\S]+?\*\/)*[^{[(<]\S*(?!\S|\s*[:=])/. Any combination of whitespace, single- and multi-line comments, followed by a node name that doesn't start with any opening brace and isn't followed by a colon or an equals sign. It doesn't "support" block comments or nested multi-line comments, and it accepts any non-KDL file that starts with valid KDL (like SDLang or almost any English text). But I think it rejects most JSON, XML, Dhall(?), YAML, TOML and s-exp files.

That said, if I'm making long regexes anyway I might as well see if I can convert the grammar into one...

[swift2plunder]

My application is allowing permissive syntax choices for players developing game clients for turn-based strategy games. I'd planned a sieve-like strategy to route messages, but using OAuth2 scopes will be a more robust strategy. I didn't intend the examples to be thorough (They are sufficient for the subset of protocols supported in my environment. Well, there's a second entry for YAML and I'm processing JSON with a YAML reader, but that is what it is.); I didn't see the specifics of the implementation as relevant to the suggestion

I'd still recommend something of the nature /- kdl version="1.0.0" generator="vim" author="Chris" (syntax?) as a best practice for debugging purposes. This is less important if the spec has low churn, but It's something that I want for my environment. It's fine if it's not something that you want for general use, but I want to float that idea before the conversation is closed

Also, I'm aware that "This is a place to store metadata..." isn't supported by the emphasis of my original post. I didn't really think that through to the point of changing the title, and perhaps I should have

If you'd prefer to have metadata like version be actionable without human intervention, then a kdl node with a version property that isn't commented would be better semantics. Beginning the document with this node could be useful, though I do see that making the order of nodes relevant is against the design philosophy.

To be clear, I'm not trying to change that philosophy. "That's off scope for this project," is as reasonable as "This is is how we'd accomplish that goal idiomatically." Either way, I can write a style guide for my projects with a reasonable expectation that it is likely to be forward compatible with future versions