Markus Armbruster <arm...@redhat.com> writes: > Andrea Bolognani <abolo...@redhat.com> writes: > >> The various schemas included in QEMU use a JSON-based format which >> is, however, strictly speaking not valid JSON. >> >> As a consequence, when vim tries to apply syntax highlight rules >> for JSON (as guessed from the file name), the result is an unreadable >> mess which mostly consist of red markers pointing out supposed errors >> in, well, pretty much everything. >> >> Using Python syntax highlighting produces much better results, and >> in fact these files already start with specially-formatted comments >> that instruct Emacs to process them as if they were Python files. >> >> This commit adds the equivalent special comments for vim. >> >> Signed-off-by: Andrea Bolognani <abolo...@redhat.com> > > Naming QAPI schema files .json even though their contents isn't was a > mistake. Correcting it would be a pain. If we correct it, then the > sooner the better. > > Renaming them to .py gives decent editor support out of the box. Their > contents isn't quite Python, though: true vs. True, false vs. False. Do > we care? Only a few dozen occurences; they could be adjusted. > > Renaming them to .qapi would perhaps be less confusing, for the price of > "out of the box". > > Thoughts?
Let me try to summarize the discussion from my point of view. Basing a DSL on some existing syntax has its advantages: the learning curve is slightly more gentle, and we get some tooling for free, notably editor support. Basing on JSON was a mistake: JSON is designed for data interchange, not for programming. To make it fit for programming, we extended it, losing much of what we gained by basing on existing syntax. Use of .json file names for the resulting bastard is confusing. Among the confused are editors. We unconfuse them one by one by telling them to treat the files as Python. Works, because the syntax happens to be a strict subset of Python's. We discussed swapping out the base syntax layer for one that is actually fit for purpose (and doesn't need extending), e.g. YAML. Radical change, benefits need to justify the cost. Possible benefits: * Better ergonomics for developers Depends on what we pick for a base, and how we use it. We discussed YAML at some length. It's complex, and the way it assigns types is at odds with the QAPI schema's needs. I doubt YAML could improve ergonomics all that much. * Not having to maintain our own code for the lower layer Replacing the (trivial) JSON parser by glue for an off-the-shelf parser is quite unlikely to pay off. Replacing the (non-trivial) doc comment parser could be a win, but no credible replacements have been suggested so far. * Make the schema more easily consumable by other programs Parsing is the easy part of this problem. Making the easy part easier won't make the total problem appreciably easier. Right now, I doubt the benefits are worth the cost. To make me reconsider, write a concise memo stating the goals, their benefits, the possible ways to get there, and their cost. More modest ways to stop our confusing misuse of .json: * Rename QAPI schema files to .qapi, keep unconfusing tools one by one by telling them to treat the files as Python. * Rename QAPI schema files to .py. Optionally rename false, true to False, True in the schema language, so the schema expressions are semantically valid Python. Humans might still find .py confusing. * Rename QAPI schema files to .js, change comments from # to //. * Keep .json, change comments from # to // and strings from ' to ". This is still not JSON, but should be close enough to make common tooling work. The last two are too much churn for too little benefit, in my opinion. I'm willing to do either of the first two. If you have a preference, let me know.
