Category Archives: Users

Kate Part in KDE4 supports the ECMAScript (JavaScript) language by using kjs. In KDE3 we had several hard-coded indenters in C++, the idea is to let scripts do all the indentation in KDE4.How does it work? It is similar to vim: You simply create a script in the directory $KDEDIR/share/apps/katepart/jscript. An indentation script has to follow several rules:

it must have a valid script header (the first line must include the string kate-script and indentation scripts must have the type: indentation)

it must define some variables and functions

Whenever the user types a character, the flow in Kate Part works like this

check the indentation script’s trigger characters, i.e. whether the script wants to indent code for the typed character

if yes, call the indentation function

the return value of the indentation function is an integer value representing the new indentation depth in spaces.

In the 3rd step there are 2 special cases for the return value:

return value = -1: Kate keeps the indentation, that is it searches for the last non-empty line and uses its indentation for the current line

return value < -1 tells Kate to do nothing

So how does a script look like exactly?The name does not really matter, so let’s call it foobar.js:

Kate allows you to specify local document variables by setting the corresponding modelines. The hidden file .kateconfig provides exactly the same functionality, but for all files in the directory.

Enable the Feature

To use a .kateconfig file you first have to enable the feature by invoking Settings > Configure Kate. In the config page Open/Save you can find the option Search depth for config file, which defaults to Do not use a config file. Change the value to an appropriate number,

0 means look in the current folder

1 means look in the current folder, and if there is no .kateconfig file, look in the parent folder

etc…

In short – Kate will search the number of given folder levels upwards for a .kateconfig file and load the settings from it.

Extended Options in KDE 3.5.x, KDE 4 and Kate 5

Kate in KDE 4 as well as later versions of Kate always search for a .kateconfig file for local files (not remote files). In addition, it is now possible to set options based on wildcards (file extensions) as follows:

In this example, all files use a tab-width of 4 spaces, an indent-width of 4 spaces, and tabs are replaced expanded to spaces. However, for all *.xml files, the indent width is set to 2 spaces. And Makefiles use tabs, i.e. tabs are not replaced with spaces. Wildcards are semicolon separated, i.e. you can also specify multiple file extensions as follows:

kate-wildcard(*.json;*.xml): indent-width 2;

Further, you can also use the mimetype to match certain files, e.g. to indent all C++ source files with 4 spaces, you can write :

kate-mimetype(text/x-c++src): indent-width 4;

Note: Next to the support in .kateconfig files, wildcard and mimetype dependent document variables are also supported in the files itself as comments.

Kate Part’s modelines – also called Kate document variables – are Kate Part’s implementation of document variables, similar to Emacs and vim modelines.

Document variables can be used to set Kate settings local to a file. This is for example for using another indenter than the one defined in the GUI settings. Or assume you work on two projects, the first indents with spaces and the second with tabs, then you can simply add a modeline that contains the specific document variables that set the specific indentation properties.

Modeline Format

A modeline in the Kate Part has the following format:

kate: VARIABLENAME VALUE; [ VARIABLENAME VALUE; ... ]

The lines can be in a comment, in C++ for example in /*...*/ sections. Multiple modelines are supported, i.e. modelines can be split over several lines for better visibility. Variable names are single words (no whitespace), and anything up to the next semicolon is the value. The trailing semicolon (;) is required.

Here is an example of how a modeline could look like, forcing indentation settings for a C++, Java or JavaScript file:

This means Kate Part’s modelines have actually the highest precedence. Whenever a document is saved, the document variables are reread, and will overwrite changes made using menu items or the command line.
Any variable not listed below is stored in the document and can be queried by other objects such as plugins, which can use them for their own purpose.

Available Modelines

The variables listed here documents Kate version 2.4. More variables may be added in the future. There are defied 3 types of values for variables, with the following valid expressions:

BOOL – on|off|true|false|1|0

INTEGER – any integer number

STRING – anything else

Available modelines are, in detail:

auto-brackets [BOOL]
Set auto insertion of brackets on or off.

auto-center-lines [INT]
Set the number of autocenter lines.

auto-insert-doxygen [BOOL]
Turn insertion of the leading asterisk in doxygen comments on or off. This has no effect unless you use the cstyle auto-indenter.

background-color [STRING]
Sets the document background color. The value must be something that can be evaluated to a valid color, for example #ff0000.