doffm's posterous

A Language for describing D-Bus interfaces

A long time ago, while working on D-Bus accessibility, I became frustrated with the existing methods for specifying the interfaces. D-Bus interfaces are normally specified using an XML format. Although this format describes the D-Bus protocol perfectly well, it is lacking lots of information 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 littered with ‘annotations’, to extend the format and number of standard annotations sprang up around specific D-Bus bindings: EggDBus, Telepathy and QtDBus.

These annotation formats are difficult to read and edit. XML is moderately acceptable, but some restrictions of D-Bus XML make keeping the document consistent vey hard. The fact that they are limited to specific D-Bus libraries is also not ideal. I started work on a language for describing D-Bus interfaces that would address these issues. My idea was to have a readable syntax, enough features to clearly document a D-Bus interface, and tools 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 is complete, and generation of D-Bus XML is supported. The source can be found at http://github.com/doffm/dbuf. There is a decent tutorial located in the doc folder, but a taste of what the language is like follows. The code is part of a real example; the AT-SPI D-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 I think it is a useful tool for describing complex D-Bus interfaces.