Kate Scripting: Indentation

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:

  1. it must have a valid script header (the first line must include the string kate-script and indentation scripts must have the type: indentation)
  2. it must define some variables and functions

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

  1. check the indentation script’s trigger characters, i.e. whether the script wants to indent code for the typed character
  2. if yes, call the indentation function
  3. 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:

  1. 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
  2. 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-script
 * name: MyLanguage Indenter
 * license: LGPL
 * author: Foo Bar
 * version: 1
 * kate-version: 3.0
 * type: indentation
 *
 * optional bla bla here
 */

// specifies the characters which should trigger indent() beside the default '\n'
triggerCharacters = "{}";

// called for the triggerCharacters {} and
function indent(line, indentWidth, typedChar)
{
  // do calculations here
  // if typedChar is an empty string, the user hit enter/return

  // todo: Implement your indentation algorithms here.
  return -1; // keep indentation
}

More details on the header:

  • name [required]: the name will appear in Kate’s menus
  • license [optional]: not visible in gui, but should be specified in js-files. it is always better to have a defined license
  • author [optional]: name
  • version [optional]: recommended. an integer
  • kate-version [required]: the minimum required kate-version (e.g. for api changes)
  • type [required]: must be set to indentation

The only missing part is the API which Kate Part exports to access the document and the view. Right now, there is no API documentation, so you have to look at the code:

You will find, that the current document exports functions like

  • document.fileName()
  • document.isModified()
  • document.charAt(line, column)
  • etc…

The view exports functions like

  • view.cursorPosition()
  • view.hasSelection()
  • view.clearSelection()

That’s the boring part of this blog. The interesting one is unfortunately shorter: we are looking for contributors who want to write scripts or help in the C++ implementation :)

API documentation & refactored kdelibs/kdeui

During the last weeks/days the directory structure of especially kdelibs/kdeui got a major overhaul: in KDE 3 all files of a module were in the same directory which was more or less a mess as you did not know immediately which files belonged to the same category. kdelibs/kdeui in KDE4 has a rather clean structure now (similar to the one in Qt) by using subfolders like

  • actions
  • dialogs
  • widgets
  • xmlgui
  • several others…

Compare this to KDE3′s kdelibs/kdeui structure. For KDE4 this is a huge benefit, as we have clearly defined groups. We already had lots of discussions in the past about API documentation and this is exactly where the new structure is important: In Qt every class usually belongs to a group (example). Our API documentation tool doxygen of course supports grouping, and now it is even easy to know which class should be in which group. For instance, all classes in the widgets directory should be in the ‘Widgets‘ group, and then maybe even more fine-grained divided into sub-groups.
By the way, we have a policy that every widget in kdelibs has a screenshot to immediately see how it looks like – another nice way to get involved :)
All in all this is really awesome and I’d like to thank all involved developers. Next prey is kdelibs/kdecore? =)

Kate: More eye-candy

Two years ago we had the KDE conference in Ludwigsburg, Germany. At that time, Martijn Klingens committed a patch to show trailing spaces in Kate. I just change the visualization a bit, the change is in for KDE4 :) Tabs are marked with a ‘»’ character, and spaces with a dot. On the left you can see the old and on the right the new version; Here is a screenshot: