Partial harmonization of plugin API between plugin/feature types

Development Plugins
1

Is it OK if I request that both charges and formats plugin/feature types use JSON for communication with Avogadro?

Currently, the format used for the data passed between Avogadro and a plugin varies according to the type of the plugin/feature:

Type In Out
charges text or JSON text
energy nothing initially, then a stream of text stream of text
formats text text
generators JSON JSON
commands JSON JSON

For the energy type, I very much understand why the input and output are simple (values delimited by newline characters), because the exchange needs to be quick, and JSON parsing would add unnecessary overhead. Unless others feel differently, I’d say energy can just stay as it is.

For the other types though, I feel there would be significant benefits to consistently using a JSON object. For a start, the long list of subtle differences between the plugin types leads to extra complexity and confusion for plugin authors, as well as a larger documentation burden, and reducing the differences to what’s actually necessary would help that.

I’d note that the input format for the charges type is even inconsistent within the same type, depending on the calculation requested – --charges is run a simple string of a geometry in some format, while --potentials is already run with a JSON containing the geometry and an array of points. The author then has to deal with reading the geometry in separate ways. These could easily be unified.

Perhaps more importantly, it would be very hard to change the text-based I/O without breaking existing plugins, whereas the use of a JSON object makes it extensible, as the addition of new keys won’t cause problems.

If you’re not quite convinced of the point of this, one thing I think would be extremely useful to add in the future is to extend the ability of commands to send a pop-up message to the user to all types that use JSON using the message key, and to have generators send an error via error in the JSON rather than as plain text, and to extend that ability to the other types as well. Whether you’d actually like to implement that specific proposal is another question, but having I/O in most cases in JSON format would enable it.

2

At some point energy might also support something like MessagePack or protobuf .. or some other fast binary mechanism (although I found some fast text-to-float and float-to-text libraries).

I’m fine moving towards JSON “harmonization” - although formats is perhaps something where the input should just be the normal file?

3

Sure, for now, it is. But for consistency it can be in the same {"cjson": {...}} format. With CJSON it’s actually nice because the parsing only takes place once.

It also occurs to me that JSON is necessary for the plugin to receive its user config from Avogadro, so actually I do think it’s a good idea for all plugin types to get a JSON to begin with, even if it’s fairly empty. The plugin is entitled to just ignore it, after all.

So actually, I’m going to request that energy plugins also receive an initial JSON payload too then, with the subsequent communication being on stdin as a stream of whatever compact fast things.

Also means, for example, that if in future you implement some binary format, the initial JSON can indicate what’s going to follow.