IDL language

[David Zeuthen]

On Sat, 2009-05-09 at 09:39 -0400, Havoc Pennington wrote:
> Hi,
> 
> On Sat, May 9, 2009 at 9:02 AM, David Zeuthen <david at fubar.dk> wrote:
> > I'll change dynamic_struct to just be a{sv} - Simon already made a
> > convincing point about that elsewhere in the thread. Sure, throwing away
> > the name (e.g. going from (sa{sv}) to a{sv}) means it's going to be a
> > little harder handling
> >
> >  GetStuff (variant value);
> >
> > where @value is a a{sv} that can either be AtaSmart or ScsiData which
> > are both declared as dynamic_struct / using @ArgTypeHints (this was the
> > intent for including the name). I guess that C programmers will have to
> > live with that. On the upside it won't screw over gjs programmers and it
> > is backwards compatible.
> 
> Awesome. Yeah, I think supporting full type info in variants is a
> slippery slope that's best avoided. It is certainly going to be a
> little annoying in certain cases, but I think can be worked around.
> 
> >  - we will introduce something like a @org.freedesktop.DBus.DocString
> >   annotation
> 
> The doc string (1 sentence) is probably really easy; the longer docs
> kept creating discussions about what sort of markup was in them. It
> seems we need some sort of simple answer to that if we have longer
> docs.

My proposal would be to go with

 1. #<type> - where <type> is an interface, struct, enum, error_domain,
              etc. Would need to be fully-qualified name.

 2. Docbook - since Docbook is well-known and tools exist on all
              platforms to munge it into/from something else

but I realize this is probably a contentious issue (another proposal for
2. would be HTML for example). I just think we need to make a decision
here and stick with it.

> >  - do we want a dbus-typelib-install(1) command that validates these
> >   assumptions? Might be useful to also make it yell about warnings
> >   such as missing docs etc.
> 
> like desktop-file-install? I think maybe people mostly use
> desktop-file-validate instead? I'm not sure. Anyway a validator sounds
> nice.

The thinking with having dbus-type-install(1) is that we could rebuild a
HTML version of the type-library (e.g. docs) including cross-referencing
and all that good stuff. Personally I would find that really useful.

But all this stuff is something we can add later (and, sure, we want at
least the validator); not something we should initially focus on.

OK, switching gears.

I was thinking more about how to represent structs and dynamic_structs
so am going to ramble about that. The main thing I think needs solving
is that we want the complete type specified. Consider

 <method name="GetStuff">
  <arg direction="out" type="a(ii)" name="pairs"/>
  <arg direction="out" type="a(ii)" name="points"/>
  <arg direction="out" type="a{sa{sv}}" name="ata_smart_blobs"/>
 </method>

which don't really have enough information for what we're trying to
express. In the IDL language, I'd write

 struct Pair {
   int first;
   int second;
 };

 struct Point {
   int x;
   int y;
 };

 dynamic_struct AtaSmartData {
   uint64 time_collected;
   boolean passed;
   ... other stuff omitted ...
 };

 GetStuff (OUT array<Pair>,
           OUT array<Point>,
           OUT dict<s,AtaSmartData>);

In fact, this can get arbitrarily complicated depending on how complex
types you are using. In IDL (or with GObject introspection or Java or
other ways to express an interface), this is no problem but we're
throwing away information when converting to the typelib format.

One way to fix this would be to extend the D-Bus signature format.
Here's one idea:

 <method name="GetStuff">
   <arg direction="out" type="a(ii)" name="pairs">
     <annotation name="org.freedesktop.DBus.CompleteType"
                 value="a!org.example.Pair!"/>
   </arg>
   <arg direction="out" type="a(ii)" name="points">
     <annotation name="org.freedesktop.DBus.CompleteType"
                 value="a!org.example.Point!"/>
   </arg>
   <arg direction="out" type="a{sa{sv}}" name="ata_smart_blobs">
     <annotation name="org.freedesktop.DBus.CompleteType"
                 value="a{s!org.fd.DK.Disks.AtaSmartData!}"/>
   </arg>
 </method>

The idea is that the notation !TypeName! is use to make a reference to
the type in question. Then code generators (including doc generators)
can look up stuff in the typelib and do the right thing. 

(FWIW, this format is simple enough to be used at run-time too where the
code generator translates the type name into e.g. a GType name or
whatever cf. my ramblings on gtk-devel-list the other day.)

It ain't pretty, then again, this is optional. Better ideas on a
post-card.

    David