Hi all,

I am trying to add functionality to Kate but although I see documentation I am missing some info to start.

As an example, I'd like to create a script to surround the selected text in the editor with underscores, so it's in italics in a Markdown document, and then assign a shortcut Ctrl-Shift-I to that script.

First of all, I am on Ubuntu 20 with XFCE, using Kate 19.12.3 with KatePart 5.68.0. The $XDG_DATA_HOME variable is not set and I cannot find anything on indentation. I have one instance of katepart5 and that is the folder /usr/share/katepart5 which has a sub folder scripts that is empty.

Under Tools > Scripts there are Emmet, Navigation, Quick Coding, and Editing. And there is Tools > External Tools, which I see are configured in the Setting > Configure Kate > External Tools.

My questions are:
Using the kjs/KateScript/javascript sounded easiest, but where do the files go?
I assume these will show up under Scripts. Is that correct? Is there a way to group any more scripts like Emmet, Navigation, etc.?
Shouldn't the scripts already in the menu be somewhere on disc?

I also read this: "Developing an indenter requires reloading the scripts to see whether the changes behave appropriately. Instead of restarting the application, simply switch to the command line and invoke the command reload-scripts."
That "the command line" - is that Tools > Focus Terminal? It will show a docked window but no terminal there. Reloading scripts without having to close and reopen Kate would be very nice, of course.

I hope someone can help give me a few tips on how to get started.

Hello! I also like to add commands to Kate.

Scripts (*.js files) must be placed in the directory ~/.local/share/katepart5/script/commands
For convenience, I created a link to it inside Documents folder.

You can of course create groups for your scripts. This is set in the script itself:

category [optional]: If a category is specified, the script appears in a submenu.

https://docs.kde.org/stable5/en/applica ... pting.html

jerry1970 wrote:I also read this: "Developing an indenter requires reloading the scripts to see whether the changes behave appropriately. Instead of restarting the application, simply switch to the command line and invoke the command reload-scripts."

This refers to the Command line from the View menu (F7). Try to press F7 and enter help or help list.

jerry1970 wrote:I'd like to create a script to surround the selected text in the editor with underscores, so it's in italics in a Markdown document

I made a draft, saved it as a file ~/.local/share/katepart5/script/commands/markdown.js and run command reload-scripts - it works!

Code: Select all

var katescript = {
    "author": "Average user",
    "license": "LGPLv2+",
    "revision": 1,
    "kate-version": "19",
    "functions": ["mdItalic"],
    "actions": [{
        "function": "mdItalic",
        "name": "Italic style",
        "category": "Markdown",
        "interactive": "false"
    }]
}; // kate-script-header, must be at the start of the file without comments

require('range.js');

function mdItalic() {
    var selection = view.selection();
    if (!selection.isValid()) {
        return;
    }

    // some kind of text conversion
    var text = document.text(selection);
    text = '_' + text + '_';

    view.clearSelection();
    document.editBegin();
    document.removeText(selection);
    document.insertText(selection.start, text);
    document.editEnd();
}


This is great!
Actually I was searching for something similar and I am interested on this.
Do you have a github/gitlab page with this script?

pvzh wrote:Hello! I also like to add commands to Kate.

Scripts (*.js files) must be placed in the directory ~/.local/share/katepart5/script/commands
For convenience, I created a link to it inside Documents folder.

You can of course create groups for your scripts. This is set in the script itself:

category [optional]: If a category is specified, the script appears in a submenu.

https://docs.kde.org/stable5/en/applica ... pting.html

The link points to a 404 page. Can you please update it?

I think he meant this page: https://docs.kde.org/stable5/en/kate/ka ... index.html

I came across this while trying to figure out how to use scripts in Kate and found it very helpful - many thanks to the posters above. Here are a few notes to consolidate and extend some of the answers given above. The following is based on Debian 11, kate 20.12.2, plasma 5.20.5 and KDE frameworks 5.78.0.

The text editor component of Kate is/was called katepart5. It is integrated into other KDE applications (e.g. Krusader). Thus, scripting appears and is documented in various places, not always consistently. It seems that the most current and authoritative (as noted above) is at:
https://docs.kde.org/stable5/en/kate/katepart/dev-scripting.html

Apparently with frameworks 5, kate has been split in two: main application and a library called ktexteditor (https://brli.github.io/2016/09/18/kate-syntax-ktexteditor.html).

Thus, scripting information may be associated with kate, katepart5 and/or ktexteditor - worth looking around.

Scripts are written in a subset of ECMAScript (i.e. JavaScript). I have zero experience programming in JavaScript, so please forgive me if some of the following is obvious.

Some versions of the documentation say that sample scripts are part of the installation. As with others, I couldn't find any. However, the source code for ktexteditor does contain *.js files corresponding to the scripts under Tools, Scripts:
https://github.com/KDE/ktexteditor/tree/master/src/script/data
(including the zero-length README.md file).

They are useful as sample code. The scripts are intended for general use and so are well built, as one would expect.

My little project, some minor text manipulation, didn't need to be so robust.

Mine was a command (not indent) script. I needed to create the subdirectories under ~/.local/share/ - i.e. adding katepart5/script/commands. The script file name can be anything so long as it has the .js extension.

Scripts must start with a structured header, described by others above and in the documentation.

The header defines the Kate menu entries, among other things. As noted, the first level sub-menu under Tools, Scripts is generated from the "category" entry of the "actions" section in each script header - in my case "TestCode". Each "name" entry in the "action" section of each header becomes a script-to-be-run within the sub-menu - in my case "process_statement". So, I ended up with TestCode under Tools, Script (along with Formatting, Markdown, Emmet, etc.) and process_statement under TestCode.

The header's "name" entry also becomes available as command in the Main Toolbar <KatePartView>. Adding it to that toolbar makes testing a bit more convenient.

Scripts can contain internal (i.e. private or local) functions not specified in the header (e.g. https://forum.kde.org/viewtopic.php?t=140599#). My script was simple so I didn't bother but doing so would make the code cleaner and easier to maintain - when I get time . . .

I couldn't figure out how to hook script development into an IDE, but my debugging needs were simple. If Kate is started from a terminal (Konsole) output from

Code: Select all

debug(text);

statements in the script will be directed there, along with error messages.

I fiddled around a bit to get a very basic idea of js and wrote a first cut. My script ran on bank statements that contained text lines in (more or less) fixed length fields. The script rearranged the text line by line to conform with an import specification. There were very few bank statements, so I opened each, ran the script, checked the output as it went along, fixed the code up, reloaded the script, and eventually saved the statement and moved on to the next statement.

Specifically:
1. start Konsole, run Kate;
2. open script file;
3. open document (bank statement);
4. run script from toolbar or menu;
5. review script impacts and check debug output in terminal;
6. good? bail; else switch to script, make changes;
7. save;
8. press F7, type "reload-scripts";
9. switch to document;
10. [go to 4]

It would more efficient if "reload-scripts" could be added to a toolbar but I couldn't figure out how to do that.

I would only also mention that not every ECMAScript function is available - alert(), for example, causes the process to pause but doesn't (AFAIK) produce output or respond to key presses, maybe because the window object is not fully implemented.

FWIW