A long time ago, while working on D-Bus accessibility, I becamefrustrated with the existing methods for specifying the interfaces. D-Businterfaces are normally specified using an XML format. Although this formatdescribes the D-Bus protocol perfectly well, it is lacking lots ofinformation that would be useful for D-Bus bindings and for documentation.To deal with this the D-Bus wizards decided that the XML could be litteredwith ‘annotations’, to extend the format and number of standard annotationssprang up around specific D-Bus bindings: EggDBus,Telepathy and QtDBus.
These annotation formats are difficult to read and edit. XML is moderatelyacceptable, but some restrictions of D-Bus XML make keeping the documentconsistent vey hard. The fact that they are limited to specific D-Buslibraries is also not ideal. I started work on a language for describingD-Bus interfaces that would address these issues. My idea was to have areadable syntax, enough features to clearly document a D-Bus interface, andtools to generate XML or code for the different D-Bus libraries.
After a long hiatus dbuf is finally in a state where the language parser iscomplete, and generation of D-Bus XML is supported. The source can be foundat http://github.com/doffm/dbuf. There is adecent tutorial located in the doc
folder, but a taste of what thelanguage is like follows. The code is part of a real example; the AT-SPID-Bus interface translated into dbuf.
using Attributes = org.freestandards.atspi.Attributes;using Reference = org.freestandards.atspi.Reference;/* The base interface which is implemented by all accessible objects.*/interface org.freestandards.atspi.Accessible { enum Role { ROLE_INVALID = 0, ROLE_ACCELERATOR_LABEL, ROLE_ALERT, ROLE_ANIMATION, ROLE_ARROW, ROLE_CALENDAR, ROLE_CANVAS, ROLE_CHECK_BOX, ROLE_CHECK_MENU_ITEM, } /* Represents a bit-field of currently held states. TODO Could just be a uint64? */ typedef uint32[] State; /* A short string representing the object's name. */ read property string Name; /* The accessible object which is this objects containing parent. */ read property Reference Parent; /* Access this objects non-hierarchical relationships to other accessible objects. */ method GetRelationSet reply { RelationSet relations; } /* Get the Role indicating the type of UI role played by this object. */ method GetRole reply { Role role; } /* Access the states currently held by this object. */ method GetState reply { State state; } /* Get a properties applied to this object as a whole, as an set name-value pairs. As such these attributes may be considered weakly-typed properties or annotations, as distinct from the strongly-typed interface instance data. */ method GetAttributes reply { Attributes attributes; }}
There is lots more work to do with dbuf, but even in its current state Ithink it is a useful tool for describing complex D-Bus interfaces.
I think #vala does a much better job already: http://git.gnome.org/browse/rygel/tree/src/plugins/external/rygel-external-interfaces.vala