All posts by Dominik

Dominik is a PhD student at the Control Theory and Robotics Lab, TU Darmstadt, as part of the Research Training Group GKMM (GRK1362). My research focuses on state estimation in distributed systems. As hobby, I contribute to the KDE project and work on the Kate application and editor component.

Kate: More on Indentation Scripting

My last blog was about the theory of how indentation works by using javascripts. Now we will look at a concrete example: a LISP-style indenter. (LISP indentation is easy, that’s why it’s a good example).
The rules:

  • comments starting with ;;; always have indentation 0
  • comments starting with ;; should be aligned with the next line
  • comments starting with ; should only appear behind code, so they are simply ignored
  • every ‘(‘ indents and every ‘)’ unindents

lisp.js looks like this:

/** kate-script
* name: LISP
* license: LGPL
* author: foo bar
* version: 1
* kate-version: 3.0
* type: indentation
*/
// indent should be called when ; is pressed
triggerCharacters = ”;”;
function indent(line, indentWidth, ch)
{
// special rules: ;;; -> indent 0
//                ;;  -> align with next line, if possible
//                ;   -> usually on the same line as code -> ignore
textLine = document.line(line);
if (textLine.search(/^\s*;;;/) != -1) {
return 0;
} else if (textLine.search(/^\s*;;/) != -1) {
// try to align with the next line
nextLine = document.nextNonEmptyLine(line + 1);
if (nextLine != -1) {
return document.firstVirtualColumn(nextLine);
}
}

cursor = document.anchor(line, 0, ’(‘);
if (cursor) {
return document.toVirtualColumn(cursor.line, cursor.column) + indentWidth;
} else {
return 0;
}
}

The result:

;;; fib : number -> number
(define (fib n)
(if (< n 2)
1
(+ (fib (- n 1)) (fib (- n 2)))))

As this indenter is scripted, everybody can adapt the style to the own needs.

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? =)