Wednesday, July 18, 2007

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 :)


Tim said...

Complex javascript on every character press? Won't that be terribly slow?

dhaumann said...

Yes and no. As long as we provide the right helper functions in a C++ implementation...
That's the hard part, and that's where help is very much appreciated.

Kevin Kofler said...

IMHO, using integers as the representation for indentation is fundamentally broken, because it matters whether tabs or spaces (or a mix of both) should be used.

Consider the example:
Now you want to indent under the 'b' of blabla. The only way to do that which still works when the reader uses a different tab width setting (which is the only reason to use tabs in the first place IMHO!) is to indent the next line with a tab and 4 spaces.

Antonio said...

I'm guessing the integer indentation depth represents the depth in `number of indents', so that 2 would mean 4 spaces in a 2-space indentation scheme, or 8 in a 4-space indentation scheme, etc.

dhaumann said...

@Kevin: You are absolutely right. It is not possible by design. But then, Kate never really supported the mixed mode you mention. And the system as it is right now is really simple.

@Antonio: The returned integer means: Indent X white spaces. Kate Part will transform the white spaces into tabs if it is the user's preference. If you have a tab width of 4 and indent() returns 6, then you will automatically get 1 tab and 2 spaces.

Pablo said...

Since the indentation mechanism is going to be redesigned/reimplemented for KDE4, I agree with Kevin that it makes sense to have a scripting engine flexible enough to support the mixed mode he's talking about. In fact, it's one of my main pet peeves with Kate right now.

dhaumann said...

@Pablo: We are discussing at the kwrite-devel mailing list about it, too.

Robin said...

I'm trying to write a ruby indenter. It actually works pretty well already, but I have run into a problem:

Is there a way to add BACKSPACE to the triggerChars?

I've tried \b \\b \x08 etc, but it doesn't work.

Andrew said...

and is it possible to use kjs for code completion? If yes, is there a comprehensive guide for that? I gladly appreciate if you drop me a link to