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.
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.
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
.
Returns the document's size in bytes.
document.lines() function
Returns the number of lines in the document.
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.
uint line
) functionParameters
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 , 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.
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.
Would you like to comment or contribute an update to this page?
Send feedback to the TDE Development Team