Extend Scripting API to allow executing commands

Authored by dhaumann on Aug 14 2018, 9:54 PM.

Description

Extend Scripting API to allow executing commands

Summary:
This patch adds the following JavaScript API:

object view.executeCommand(String command,
                           String args = String(),
                           Range range = Rante::invalid())

The returned object indicates whether execution of the command
was successful:

  • object.ok [bool] is true on success, otherwise false.
  • object.status [String] contains the result of the command (e.g. "31 replacements made", or an error message)

Examples:

view.executeCommand("sort"); // all, or seletcion
view.executeCommand("sort", "", new Range(1, 0, 4, 0); // sort lines 1-4
view.executeCommand("set-indent-width", "4");

Unfortunately, we do not have any getters, e.g. "indent-width".
This is a shortcoming of the KTextEditor::Command API. We should
consider to change KTextEditor::Command as follows:

// old:
virtual bool exec(KTextEditor::View *view, const QString &cmd, QString &msg,
                  const KTextEditor::Range &range = KTextEditor::Range::invalid()) = 0;

// new:
virtual QVariant exec(const QVariant & args,
                  const KTextEditor::Range &range = KTextEditor::Range::invalid(),
                  KTextEditor::View * view = nullptr) = 0;

or similar. This way, Commands would be much more usabe in general
(and also better chainable, which could result in: command 1 | command 2 | ...).

What is missing in this patch:

  • infinite recursion is very easily possible
  • guard against some special commands: reload-scripts, anything else?
  • should the API be more smart? E.g. we could support both:
    • view.executeCommand("sort", "", new Range(1,0, 3, 0))
    • view.executeCommand("sort", new Range(1,0, 3, 0)) -> we'd have to lookup the type of the passed QJSValues (would work)...
  • Maybe only return a bool instead of object with "ok" and "status" ? -> The status could be helpful as a return value, but to be honest, this is a hack (see shortcoming of KTextEditor::Command above). We could also add KTextEditor::CommandExtension, provide an improved interface, and then do this properly here... Comments?

Test Plan: make test, manual testing

Reviewers: cullmann, mwolff, kfunk

Reviewed By: cullmann

Subscribers: kwrite-devel, kde-frameworks-devel

Tags: Kate, Frameworks

Differential Revision: https://phabricator.kde.org/D9247

Details

Committed
cullmannAug 14 2018, 9:54 PM
Reviewer
cullmann
Differential Revision
D9247: Extend Scripting API to allow executing commands
Parents
R39:467cf37fd04f: Indentation script for R
Branches
Unknown
Tags
Unknown