Scripting the editor with JS

Introduction

Starting with version 2.5, the Kate editor component supports scripting with ECMA script, also known as JavaScript.

Scripts can be used through the built-in command line only. The requirements are that the scripts are placed in a folder where Kate can find them, along with an optional .desktop file that defines the related properties. The valid folders are named katepart/scripts in the TDE data folders. You can find the data folders by running the command tde-config --path data. You will usually have at least a system and a personal data folder. Of course scripts in the system data folder are available to all users on the system, while those in the personal folder are available to you only.

The Kate JavaScript API

Here is the complete set of functions and properties available in the document and view objects. In addition, you can use all the standard objects such as Math, String Regex and so forth.

When a script is run, the document object is the current document, and the view object is the current view.

Note

Types are not used in JavaScript. In this list, they are there solely to indicate what sort of arguments the functions expect.

Global Functions

debug(string s) function

parameters

s the string to output.

Outputs the string to STDERR using kdDebug(). A dedicated output area is used for the output, which will be prefixed by "Kate (KJS Scripts):"

The document API

document.attribute(uint line, uint column) function

Parameters

line the line of the position for which to find the attribute.
column the column of the position for which to find the attribute.

Returns the numeric ID of the attribute for the document position [line, column]. The attribute represents the visual appearance or style of the text, and is also used to calculate the syntax highlight for a specific part of the text in mixed formats like HTML or PHP.

document.canBreakAt(char c, attribute attrib) function

Parameters

c the character to test.
attrib the attribute at the position of c.

Returns whether it is allowed to break the line at the character c with attribute attribute.

document.canComment(attribute start_attrib, attribute end_attrib) function

Parameters

start_attrib the attribute at the start of the range to turn into a comment.
end_attrib the attribute at end of the range to turn into a comment.

Returns whether start_attribute and end_attribute belongs to the same syntax highlight system. If they do, it is possible to comment the block.

document.clear() function

Clears the document.

document.commentStart(attribute attrib) function

Parameters

attrib the attribute of the text for which to get the commentStart string.

Returns the string required to start a multiline comment for a text with attribute attrib, or an empty string if multiline comments are not supported for that text.

document.commentMarker(attribute attrib) function

Parameters

attrib the attribute of the text for which to get the commentMarker string.

Returns the string used to mark the rest of the line as a comment for a text with attribute attrib or an empty string if single line comments are not supported for that text.

document.commentEnd(attribute attrib) function

Parameters

attrib the attribute of the text for which to get the commentEnd string.

Returns the string required to end a multiline comment for a text with attribute attrib, or an empty string if multiline comments are not supported for that text.

document.editBegin() function

Starts an editing group. All actions done until the call to editEnd() will be grouped as a single undo action.

document.editEnd() function

Ends an editing group.

document.highlightMode property, read only

The name of the document's highlight mode, such as JavaScript or C++. If no syntax highlight mode is set for the document, the value is none. Notice that you need to use the English name in cases where it differs from the translated one.

document.indentMode property, read only

The name of the document indent mode, such as normal or cstyle. If no indent mode is set, the value is none.

document.indentWidth property, read only

The indentation width set for the document. This is used if space indenting is enabled.

document.insertLine(uint line, string text) function

Parameters

line the document line number.
text the text to insert.

Inserts a new line with the text text at the line line.

document.insertText(uint line, uint column, string text) function

Parameters

line the line number.
column the column number.
text the text to insert.

Inserts the text text in line line at column column.

document.length() function

Returns the document's size in bytes.

document.lines() function

Returns the number of lines in the document.

document.mixedIndent property, read only

A boolean telling whether the mixed-indent setting is enabled for the document. If so, indentation is optimized to contain a mix of tab characters and spaces like in the Emacs editor.

document.removeLine(uint line) function

Parameters

line the line number.

Removes the document line line.

document.removeText(uint startLine, uint startColumn, uint endLine, uint endColumn) function

Parameters

startLine specifies the beginning line.
startColumn specifies the beginning column.
endLine specifies the ending line.
endColumn specifies the ending column.

Removes the text range from line startLine and column startColumn to line endLine and column endColumn.

document.setText(string text) function

Parameters

text the new document text.

Sets the entire document content to text.

document.spaceIndent property, read only

A boolean telling whether space-indent is enabled for the document. If so, the document is indented with indentWidth spaces per level, otherwise indentation is one tab character per level.

document.textFull() function

Returns the full document text. If the text spans over multiple lines the linefeed character is \n.

document.textLine(uint line) function

Parameters

line the line number.

Returns the text at line line.

document.textRange(uint startLine, uint startColumn, uint endLine, uint endColumn) function

Parameters

startLine specifies the beginning line.
startColumn specifies the beginning column.
endLine specifies the ending line.
endColumn specifies the ending column.

Returns the specified text range. If the range spans over multiple lines the linefeed character is \n.

The view API

view.clearSelection() function

Deselects all text.

view.cursorColumn() function

Returns the current cursor column (TAB characters are expanded).

view.cursorColumnReal() function

Returns the current real cursor column (a TAB character counts as one).

view.cursorLine() function

Returns the current cursor line.

view.hasSelection() function

Returns true if some text in the view has been selected, otherwise false.

view.removeSelectedText() function

Removes the selected text, if the view has a selection.

view.selectAll() function

Selects all text.

view.selection() function

Returns the selected text. If the selection spans over multiple lines the linefeed character is \n.

view.selectionEndColumn property, read only

Returns the ending column of the selection.

view.selectionEndLine property, read only

Returns the ending line of the selection.

view.selectionStartColumn property, read only

Returns the starting column of the selection.

view.selectionStartLine property, read only

Returns the starting line of the selection.

view.setCursorPosition(uint line, uint column) function

Parameters

line specifies the new line for the cursor.
column specifies the new column for the cursor.

Sets the input cursor position in the view to (line, column). TAB characters are expanded and the cursor position is made visible. Both line and column are zero-based.

view.setCursorPositionReal(uint line, uint column) function

Parameters

line specifies the new line for the cursor.
column specifies the new column for the cursor.

Sets the input cursor position to (line, column). This sets the string position, that is a TAB character counts for 1, and the cursor position is made visible. Both line and column are zero-based.

view.setSelection(uint startLine, uint startColumn, uint endLine, uint endColumn) function

Parameters

startLine specifies the beginning line.
startColumn specifies the beginning column.
endLine specifies the ending line.
endColumn specifies the ending column.

Sets a selection from line startLine and column startColumn to line endLine and column endColumn.

Example 6.4. A sample script

As an example we will create a small script that transforms the selected text to upper case. We first need to check whether a selection exists: if so we get the text, change the case and then replace the original text with the new one. An implementation would look something like this:

if (view.hasSelection())
{
  // uppercase selection
  column = view.selectionStartColumn;
  line = view.selectionStartLine;

  selection = view.selection().toUpperCase();

  document.editBegin();
  view.removeSelectedText();
  document.insertText(line, column, selection);
  document.editEnd();
}

To group this actions together so that they will be reverted by a single activation of Undo, we encapsulate the lines

view.removeSelectedText()
document.insertText()

in a document.editBegin() - document.editEnd() block.

Example 6.5. A sample .desktop file

Here is a sample .desktop file that accompanies the above script.

# Example of a .desktop file
[Desktop Entry]
Encoding=UTF-8
Name=Kate Part JavaScript Uppercase Script
Comment=Script to transform the selected text to upper case
X-Kate-Command=uppercase-selection
X-Kate-Help=<p>Usage: <code>uppercase-selection</code></p>

As you can see you can define the Encoding, set a Name, a Comment, a help text using X-Kate-Help and the command line name via X-Kate-Command.

Putting it all together

Kate will search the script folders (see above) for .js files. For every such file found, Kate will check whether there is a corresponding .desktop file with the same basename (for example script.js and script.desktop).

If a corresponding .desktop file exists, the script will be registered using the name from the .desktop entry X-Kate-Command.

If a corresponding .desktop file can not be found, the script will be registered with the file basename (i.e. without the ending .js). If you only need the command name and none of the extra features that a .desktop file would provide, you do not need a .desktop file at all.