[Xcb] Proposal: Link fields to enums in the protocol XML files

[Peter Harris]

Ian Osgood wrote:
> Please search the XCB mailing list archives for previous discussions  
> on this topic. A few years ago we researched a quite detailed list of  
> requirements for such a type annotation system.

I see your message from Jun 11 2007, and a thread I was involved with in
January 2008.

I don't see a detailed list of requirements anywhere. Your message lists
the same things you list below, and the thread I was involved with
discussed a few alternate implementations without ever coming to a
concrete decision (probably due to lack of volunteers to implement any
of the alternatives).

Perhaps I missed something when searching the archives. Links appreciated.

> Among the challenges:  
> some parameters take a union of types (two different enums

Aside from KEYBUTMASK, I don't believe I've seen this anywhere[1]. I'm
not sure it's worth the effort to support this in a separate mechanism
for a single case. The obvious workaround is to simply define KeyButMask
as a separate enum.

If there are other places where multiple enums are used, please let me know.

> ; an enum  
> or an XID;

<field type="PIXMAP" enum="Enum" /> seems pretty clear to me.

<item> can use the same encoding. If you prefer,
<type>PIXMAP</type><enum>Enum</enum> can be used instead, for
consistency with <value> and <bit>, but that seems uglier to me.

>  etc.), sometimes the same enum is used in different  
> parameter widths (8-bit vs. 32-bit),

<field type="CARD32" enum="Enum" /> seems pretty clear to me. Aside from
decoupling the size from the enum itself, it also has the advantage of
not breaking current code.

The only ambiguity is exhaustive enums vs special-value enums for
languages that want to use native enums for type safety.

This could be solved by creating a typedef for use with any enum that is
not exhaustive. Then any field with an explicit CARD type will only have
an exhaustive enum associated with it.

Example: <field type="TIMESTAMP" enum="TimeConstants" />

Okay, that's maybe not the best example, since we already have
TIMESTAMP, but we have not defined an enum with CurrentTime anywhere.

<item> size is determined by the referencing <valueparam>. Therefore,
while type="PIXMAP" is a useful annotation, type="CARDn" will be
redundant and discouraged inside <item>.

> and extensions referencing types  
> and enums from the core protocol or another extension.

<import> has already solved this one, no? XCB extensions have been
referencing typedefs from xcbproto and other extensions forever. I don't
see how enums are any different.


Given that this is at least the third independent reimplementation of
the same thing, I'd like to get this nailed down so we can stop
re-inventing each other's wheels. I'm willing to do the heavy lifting if
there is a different encoding you'd like to see.

Thanks,
 Peter Harris

[1] The GLX Enum compound doesn't count. It's not defined by XCB. There
is an XML description in Mesa, and a ".spec" description available from
opengl.org, but either one will require a separate parser anyway.
-- 
               Open Text Connectivity Solutions Group
Peter Harris                    http://www.opentext.com/connectivity
Research and Development        Phone: +1 905 762 6001
pharris at opentext.com            Toll Free: 1 877 359 4866