[Xcb] Using COMMENT, and a Better Way for enums

[Jamey Sharp]

--dp9QYJgVRVEW2bsm
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

(Sorry this reply took me so long: I got a bit swamped.)

On 11/06 10:56PM, James Mastros wrote:
> Hello, all.
>   I'm working on a perl version of XCB

Great! I've been waiting for test cases for the versatility of the macro
language.

> (can we get a name that isn't tied to C, BTW?),

Heh. I recall that some of us have discussed that problem. You're
welcome to name your bits anything you want; in my opinion, XCB refers
to the C binding only, and xcb-proto inherits that name only because XCB
is the first (and perhaps most significant) user of the protocol
descriptions.

> First, the minor rant: While COMMENT is defined, it's almost never used.=
=20
>  The m4 files contain comments in the form of /* ... */.  This makes it=
=20
> quite obnoxious to try to generate things other then c with it.
>=20
> That one is easy, since there's already a defined API for it.  enums, my=
=20
> next topic, require a new one, since the existing one is rather poor.

The COMMENT API is poor too, I think, because it doesn't express the
relationship between the comment and the thing being commented on. What
I actually want there is a way to include complete documentation - say,
all the content in the X protocol spec and extension specs - in the
protocol description files, in a manner suitable for generating
documentation from them.

However, for the purposes of your Perl binding, we might as well convert
those bits to use the COMMENT macro.

> (I'm using ENUM instead of XCBENUM here.  The only difference seems to
> be that XCBENUM prepends XCB to the name given.

XCBENUM will/should go away. I did the classic thing of trying to be too
general; fortunately, XCB is recovering nicely.

> I propose the following.
> ENUM(`CW', `
>   ENUMELEM(`BackPixmap', NTHBIT(0))
>   ENUMELEM(`BackPixel', NTHBIT(1))
> ')
>=20
> The definition of ENUM needn't change in this proposal
>=20
> The definitions of the other two macros could be, for client-c.xcb:
> DEFINE(`ENUMELEM', $1` =3D '$2)
> DEFINE(`NTHBIT', `1L<<'$1)
>=20
> That should allow me to define them the way I need for perl.

Arguably, even ENUM is too general. I'd like to be able to write things
something like this:

VOIDREQUEST(CreateWindow, `
   OPCODE(1)
   ...
   PARAM(CONSTSET(CARD16, InputOutput, InputOnly, CopyFromParent), `class')
   ...
   VALUEPARAM(CARD32, `value',
       BackPixmap,
       BackPixel,
       ...
       Colormap,
       Cursor
   )
')

And produce C code like this:

enum XCBCreateWindowClass {
    XCBCreateWindowInputOutput,
    XCBCreateWindowInputOnly,
    XCBCreateWindowCopyFromParent
};
enum XCBCreateWindowValue {
    XCBCreateWindowBackPixmap =3D 1L << 0,
    XCBCreateWindowBackPixel =3D 1L << 1,
    ...
};
XCBVoidCookie XCBCreateWindow(..., enum XCBCreateWindowClass class,
=2E.., CARD32 value_mask, CARD32 *value_list);

I'd then like to have a shorthand to make these names visible from other
requests, so that ChangeWindowAttributes wouldn't have to duplicate the
the elements of the CreateWindowValue bitmask, for example.

> Other languages may be a problem if they have different ideas of
> numeric literals then C, but this seems unlikely in practice.  (In
> particular, almost all enums will be 42, 0x2a, or NTHBIT(4).)

As long as the target language accepts literal numbers in some
reasonable format, M4's built-in eval macro should let us not worry
about numeric constants: it can do shifts and all the obvious things.

Of course, m4 is powerful enough to write an arbitrary text parser in...
;-)

> Oh, one other thing.  The extensions/ files seem to have another sort of=
=20
> literal C -- typedefs.  I'd much rather see TYPEDEF(`INT32', `FIXED'),=20
> and the related make_fixed be in some higher layer completely.

I agree. Though perhaps a STRUCT with two INT16s is the right approach
for Render? I'd have to look at it again.

> BTW, the perl implementation isn't nearly ready for public perusal yet.=
=20
>  While I think I'm done making huge changes to the existing pieces of=20
> infrastructure, there's a whole two layers that aren't there yet.  This=
=20
> is my first low-level X programming, so I'm taking it a bit on the slow=
=20
> side.

There's an argument to be made for generating a Perl binding to the C
library, rather than writing a native Perl implementation. But I'm
thrilled that you're trying this, regardless of what implementation
strategy you use.
--=20
Jamey Sharp <jamey@minilop.net> - http://minilop.net/

--dp9QYJgVRVEW2bsm
Content-Type: application/pgp-signature
Content-Disposition: inline

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)

iD8DBQE/uXbZNgAXSpyH6VcRApDqAJsErn7PaxXBSuBl0y35Io9tSj74/wCghr5b
4Ify6ObEB+0VfGJw02LqjM8=
=GjTF
-----END PGP SIGNATURE-----

--dp9QYJgVRVEW2bsm--