Introspection & compound type signatures

[Daniel P. Berrange]

I've been working on adding full support for introspection to the Perl
bindings to enable removal of the quick hacks[1] for typing I did
previously. All in all it has been pretty simple to build support
for the org.freedesktop.DBus.Introspectable interface into the 
bindings. 

The only complication I've come across is how to represent compound 
types in the XML format. The online specification [2] just defines
a single attribute for specifying an argument type, which while fine
for basic types, is obviously insufficient for compound types. 

   <arg name="foo" type="int32" direction="in"/>

with the note

  'The current type="uint32" stuff is totally broken, instead we have 
   to do full signatures. However, then this format will suck for human
   readability. So, some thinking to do here.'

I notice the specification & impl in CVS has been updated post the 0.31
release to specify that raw type signatures should be used instead. I'm
not sure if anyone thinks there's any mileage looking at this again, but
if there is, here's a few of my thoughts on the subject...

I can think of a handful of ways to reasonably represent the full compound
type structure, with varying levels of human-friendlinesss...

1. Include the full signature in the type attribute,

   <arg name="foo" type="int32" direction="in"/>
   
   <arg name="bar" type="(isab)" direction="in"/>

   This is not very good for human readability, particuarly if you are 
   writing the XML yourself, but would be OK if the language bindings
   generated the XML for you & its obviously got the benefit of being
   the same as the on-the-wire signature format.

2. Include the full signature in an expanded format

   <arg name="foo" type="int32" direction="in"/>
   
   <arg name="bar" type="struct(int32,string,array(byte))" direction="in"/>

   While a bit better for readability, its tedious to have to write
   yet another parser to decode this format into the real signature,
   so this isn't really a viable suggestion.

3. Remove type attribute, and use nested <type> elements

   <arg name="foo" direction="in">
     <type name="int32"/>
   </arg>

   <arg name="bar" direction="in">
     <type name="struct">
       <type name="int32"/>
       <type name="string"/>
       <type name="array">
         <type name="byte"/>
       </type>
     </type>
   </arg>
   
   This is quite verbose, but fairly easy to parse & build up an
   internal representation of the signature. It also clearly shows 
   the nested nature of compound types. 
   
4. Keep type attribute for primary type name, only use nested <type>
   elements for specifying compound type details

   <arg name="foo" type="int32" direction="in"/>

   <arg name="bar" type="struct" direction="in">
     <type name="int32"/>
     <type name="string"/>
     <type name="array">
       <type name="byte"/>
     </type>
   </arg>

   This keeps simple types more concise, and is just as clear as the
   previous example for compound types. Also still fairly easy to
   parse & handle.

Out of those my personal preference would be for example 4 since IMHO it
provides a pretty good human readability, and its still pretty simple to
deal with programmatically. Indeed this is what I've currently got implemented
since the code I working on currently is intended to run against the 0.31
release of DBus & this is the minimal extension for compound types that'll
still be compatible with that release. It would be nice to not have to fork
the code to add a different scheme for later releases, but I'll obviously 
follow whatever scheme is adopted for future releases as they are cut.

Regards,
Dan.

[1] http://lists.freedesktop.org/archives/dbus/2004-December/001825.html
[2] http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format
-- 
|=-            GPG key: http://www.berrange.com/~dan/gpgkey.txt       -=|
|=-       Perl modules: http://search.cpan.org/~danberr/              -=|
|=-           Projects: http://freshmeat.net/~danielpb/               -=|
|=-   berrange at redhat.com  -  Daniel Berrange  -  dan at berrange.com    -=|
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 232 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/dbus/attachments/20050319/a2a81730/attachment.pgp