RFC: Exporting JavaScript API

Since quite some time, Kate Part has build-in scripting support through JavaScript. Our plan is to make this API public, so other applications like Kile, Kate App and KDevelop can use it. However, we are currently unsure how to best implement it, so this is a rfc to get feedback.

The bindings for a Kate Document are for instance located in part/script/katescriptdocument.h (header, implementation). As you can see, there are functions like

Q_INVOKABLE bool insertLine(int line, const QString &s),

which can be invoked in our scripting by a call of ‘document.insertLine(5, “hello world”)’. The API only contains basic functions. But for instance Kile maybe also wants to provide a function called ‘document.insertSection()’ or similar LaTeX related functions. The question now is as follows: How can Kile extend our QObject based prototype with their own QObject based classes?

We do not want to make the class KateScriptDocument public. Instead, we just want to return a QScriptValue containing a QObject based KateScriptDocument. You can think of the problem also as follows:

// in Kile:
QScriptEngine *engine = ...;
KTextEditor::Document *kteDocument = ...;

QObject* kateScriptDocument = kteDocument->scriptDocument();
engine->globalObject().setProperty("document", engine->newQObject(kateScriptDocument));
// at this point, the JavaScript object 'document' contains all KateScriptDocument functions

// next, we want to add the Kile related document functions
KileTextDocument* kileDocument = ...;
QObject* kileScriptDocument = kileDocument->...(); // some function that returns the binginds object

// now: how can we populate the 'document' property with the functions in kileScriptDocument?
engine->globalObject().setProperty("document", ? );

If you have any idea or other solutions how to do it right, please let us know!