Re: [PATCH] schemas: Add vim modeline

[Eric Blake <eblake@redhat.com>]

On 7/30/20 6:51 AM, Markus Armbruster wrote:

>> Given that we already have emacs mode-lines, I see no reason to
>> not also have vim mode-lines, so regardless of the deeper discussion
>> I think this is patch is fine to merge in the short term
>>
>>    Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>

Agreed on that front.

>>
>>
>>> 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".

I've tried that patch in the past, but it went nowhere at the time.
https://lists.gnu.org/archive/html/qemu-devel/2018-04/msg03173.html

Rebasing it to the present would be a complete rewrite, but I'm still 
willing to do it if we think it will go somewhere this time.


>>
>> IMHO, the critical rule is that if you a pick a particular file extension
>> associated with an existing language, you absolutely MUST BE compliant
>> with that language.
> 
> Can't argue with that :)

Also in violent agreement.

> 
>> We fail at compliance with both JSON and Python because we're actually
>> using our own DSL (domain specific language).
>>
>> IOW if we're going to stick with our current file format, then we should
>> be naming them .qapi. We can still use an editor mode line if we want to
>> claim we're approximately equiv to another language, but we can't be
>> surprised if editors get upset.
>>
>>
>> The bigger question is whether having our own DSL is justified ?
>>
>> I'm *really* sceptical that it is.
> 
> To be precise: our own DSL *syntax*.  Semantics is a separate question
> to be skeptical about.
> 
>> We can't use JSON because it lacks comments. So we invented our own
>> psuedo-JSON parser that supported comments, and used ' instead of "
>> for some reason. We also needed to be able to parse a sequence of
>> multiple JSON documents in one file. We should have just picked a
>> different language because JSON clearly didn't do what we eneeded.
> 
> JSON is a exceptionally poor choice for a DSL, or even a configuration
> language.
> 
> Correcting our mistake involves a flag day and a re-learn.  We need to
> weigh costs against benefits.

How much of that can be automated with tooling?  Yes, a re-learn is 
needed, but if a tool can convert between the two syntaces with minimal 
pain, the re-learn (in both directions: rebasing patches written 
pre-change for merge after the change lands upstream, and backporting 
patches post-change to trees that are pre-change) is not as painful.

> 
> The QAPI schema language has two layers:
> 
> * JSON, with a lexical and a syntactical sub-layer (both in parser.py)
> 
> * QAPI, with a context-free and a context-dependend sub-layer (in
>    expr.py and schema.py, respectively)
> 
> Replacing the JSON layer is possible as long as the replacement is
> sufficiently expressive (not a tall order).

I'm open to the idea, if we want to attempt it, and agree with the 
assessment that it is not a tall order.  In fact, if we were to go with 
the JSON5 language instead of JSON, we are already that much closer to 
having sufficiently expressive (although JSON5 does not seem to be as 
popular in terms of pre-written libraries).

> 
>> You suggest naming them .py. If we do that, we must declare that they
>> are literally Python code
> 
> Agree.

I'm not necessarily a fan of .py for QAPI files; it makes me think of 
executable python code, even if we chose it merely for something that 
python could parse natively instead of rolling our own parser.

> 
>>                                modify them so that we can load the
>> files straight into the python intepretor as code, and not parse
>> them as data. I feel unhappy about treating data as code though.
> 
> Stress on *can* load.  Doesn't mean we should.
> 
> Ancient prior art: Lisp programs routinely use s-expressions as
> configuration file syntax.  They don't load them as code, they read them
> as data.
> 
> With Python, it's ast.parse(), I think.
> 
>> While JSON doesn't do what we need, its second-cousin YAML is a more
>> flexible format. Taking one example
>>

> StrictYAML insists on quotes.
> 
> I hate having to quote identifiers.  There's a reason we don't write
> 
>      'int'
>      'main'('int', 'argc', 'char' *'argv'[])
>      {
>          'printf'("hello world\n");
>          return 0;
>      }
> 

JSON5 would also let us get rid of some quotes, if that is considered a 
desirable goal of the representation (although I'm not sure that quote 
avoidance should be driving our decision, so much as automated conversion).

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org