Re: [RFC PATCH v1 0/8] qapi: add generator for Golang interface

[Markus Armbruster <armbru@redhat.com>]

Andrea Bolognani <abologna@redhat.com> writes:

> On Mon, May 02, 2022 at 09:21:36AM +0200, Markus Armbruster wrote:
>> Andrea Bolognani <abologna@redhat.com> writes:
>> > The wire protocol would still retain the unappealing name, but at
>> > least client libraries could hide the uglyness from users.
>>
>> At the price of mild inconsistency between the library interface and
>> QMP.
>
> That's fine, and in fact it already happens all the time when QAPI
> names (log-append) are translated to C identifiers (log_append).

There's a difference between trivial translations like "replace '-' by
'_'" and arbitrary replacement like the one for enumeration constants
involving 'prefix'.

>> We could clean up QMP if we care, keeping around the old names for
>> compatibility.  See also Kevin's work on QAPI aliases.  Which is much
>> more ambitious, though.
>
> I wasn't aware of that effort. Personally I'm always in favor of
> cleaning up inconsistencies, so I am automatically a fan :)
>
> That said, the idea of exposing a sub-par Go API until such massive
> undertaking can be completed is not terribly appealing.

Point.

>                                                         And it would
> not address every facet of the issue (see below).
>
>> > Capitalization of these acronyms is inconsistent across the schema,
>>
>> Common issue with camel-cased compounds containing acronyms, because
>> either way is ugly.
>
> Agreed :) But consistent ugliness is still preferable to inconsistent
> ugliness.

True.

>> > with one of the two forms disagreeing with Go naming expectations.
>>
>> Pardon my ignorance: What are Go's expectations?
>
> Acronyms are usually all upper case:
>
>   https://pkg.go.dev/net/http#ParseHTTPVersion
>   https://pkg.go.dev/net/http#ProxyURL
>   https://pkg.go.dev/crypto/tls#NewLRUClientSessionCache
>
> The same seems to be true of Python:
>
>   https://docs.python.org/3/library/http.html#http.HTTPStatus
>   https://docs.python.org/3/library/urllib.error.html#urllib.error.URLError
>   https://docs.python.org/3/library/xmlrpc.server.html#xmlrpc.server.SimpleXMLRPCServer
>
> Rust, on the other hand, seems to prefer only capitalizing the first
> letter of a word, no matter if it's an acronym:
>
>   https://doc.rust-lang.org/std/net/struct.TcpStream.html
>   https://doc.rust-lang.org/std/net/struct.Ipv4Addr.html
>   https://doc.rust-lang.org/std/ffi/struct.OsString.html

Another strange game where the only winning move is not to play.

> Whether different naming conventions are used for types, functions
> and struct members is also language-dependent.

Yes.

>> > In this case we might be able to just change the schema without
>> > introducing backwards compatibility issues, though? Type names are
>> > not actually transmitted on the wire IIUC.
>>
>> Correct!
>
> That's great, but even if we decided to change all type names so that
> the schema is internally consistent and follows a naming convention
> that's reasonable for C, Go and Python, we'd still leave the Rust
> interface looking weird... There's no one-size-fits-all name,
> unfortunately.

C will remain the primary customer for quite a while.  It doesn't come
with universally accepted naming conventions, so we made up our own.  I
think we have some wiggle room there.  We could, for instance, decide to
clean up the current inconsistent capitalization of acronyms in the QAPI
schema to either style, TCPStream or TcpStream.

Your point remains: some names will still look "weird" in some possible
target languages.

>> > Of course such annotations would only be necessary to deal with
>> > identifiers that are not already following the expected naming
>> > conventions and when MLAs are involved.
>>
>> Pardon my ignorance some more: what are MLAs?
>
> Multi Letter Acronyms. Which are actually just called "acronyms" I
> guess? O:-)

Well played!

> The point is that, if we want to provide a language interface that
> feels natural, we need a way to mark parts of a QAPI symbol's name in
> a way that makes it possible for the generator to know they're
> acronyms and treat them in an appropriate, language-specific manner.

It's not just acronyms.  Consider IAmALittleTeapot.  If you can assume
that only beginning of words are capitalized, even for acronyms, you can
split this into words without trouble.  You can't recover correct case,
though: "i am a little teapot" is wrong.

"Split before capital letter" falls apart when you have characters that
cannot be capitalized: Point3d.

Camel case is hopeless.

> The obvious way to implement this would be with an annotation along
> the lines of the one I proposed. Other ideas?

I'm afraid having the schema spell out names in multiple naming
conventions could be onerous.  How many names will need it?  Times how
many naming conventions?

Another issue: the fancier the translation from schema name to
language-specific name gets, the harder it becomes to find one from the
other.