This article was imported form wiki.kate-editor.org. Note that kscript is no longer available in Kate since v. 2.4. If you absolutely have to, it is still possible to run dcop scripts using the External Tools feature.

Incorporation of a script into Kate

Kate works with all scripts which are defined by desktop files in $KDEDIR/share/apps/kate/scripts/ directory where $KDEDIR stands for the director where KDE looks for its files, for example /usr/kde, or for your own directory in ~/.kde/. In the first case the scripts are available for all users, in the latter only for yourself. This desktop file has the following structure:

[Desktop Entry]
Encoding=UTF-8
Name=English name of the script
Name[nl]=name in the Dutch
Type=ShellScript/bash
X-KDE-ScriptName=scriptname.sh

As an example we will write a script that counts the number of lines, words and characters in the current document. Our desktop file looks like this:

[Desktop Entry]
Encoding=UTF-8
Name=Word Count
Name[nl]=Woorden count
Type=ShellScript/bash
X-KDE-ScriptName=wordcount.sh

Save this file in ~/.kde/share/apps/kate/scripts/ under the
name wordcount.desktop. (It is possible that you have to create the directory if it does not exist.)

The script itself

Now we will write the script itself. It is named wordcount.sh, and it must be in the same directory as the corresponding desktop file. In this case it is just a normal shell-script, and so we have to start with shebang line:

#!/bin/bash

We use the DCOP technology (technical information) which allows our script to communicate with Kate. When the script is called from Kate it gets its DCOP name as first argument (this is usually just kate). The rest must dig out our script itself.

In the DCOP-browser dcop or kdcop we can find what Kate offers. We want find to out what is the number of the document currently shown in Kate's window. We can do this by running the following command, try it a terminal window (while Kate is running):

dcop kate KateDocumentManager activeDocumentNumber

This returns a value which stands up for the number of the currently active document in Kate. Instead of kate in the above example we may have to use something like kate-10665. Actual number of kate's process could be found with the command dcop ' kate * ' .

But for our script we have already got the correct DCOP name of the current kate: $1! Therefore the active document number can be find in our script by:

#!/bin/bash
doc=`dcop $1 KateDocumentManager activeDocumentNumber`

(Notice reversed quotations mark/backticks!) Then we can read (and also use!) this document through the EditInterface of that document:

edit="editinterface#$doc text=`dcop $1 #text`

The complete text of our active document appears now in the variable edit. But we wanted to count words, and for that we can use Unix-tool wc (word count). This tool examines document on its standard input so we can just pipe the output of the DCOP command right into wc, and output of wc can then be used in a KDE dialog for pretty display. The output wc consists from 3 numbers, the number of lines, words and characters.

Therefore, we can do this:

#!/bin/bash
doc=`dcop $1 KateDocumentManager activeDocumentNumber`
dcop $1 editinterface#$doc text | wc | {
    read lines words chars
    kdialog -- msgbox lines
}

Save this under the name wordcount.sh, in the same directory as desktop file referring this script. Now restart Kate, and you can find new command word count in the menu Tools > KDE-Scripts.

Improving the Script

Our script is possibly still too fragile. We can check whether kate runs:

#!/bin/bash
case "$1" in
kate*) ;;
*) echo "Please call me from Kate" > &2
exit 1;;
esac
#...

and we can embellish the output of KDialog with HTML. For that we place the complete message between <qt>- and </qt>-tags:

kdialog --title "words count" \
--msgbox "<qt><table >
<tr><td>Number of lines:</td><td align=right><b>$lines</b></td></tr>
<tr><td>Number of words:</td><td align=right><b>$words</b></td></tr>
<tr><td>Number of characters:</td><td align=right><b>$chars</b></td></tr>
</table></qt>"

so the resulting script now looks like this:

#!/bin/bash
case "$1" in kate*) ;;
*) echo "Please call me from Kate" > &2 exit 1;;
esac
doc=`dcop $1 KateDocumentManager activeDocumentNumber`
dcop $1 editinterface#$doc text | wc | { \
   read lines words chars kdialog -- title "words count" \
           --msgbox "<qt><table> <tr><td>Aantal regels:</td>
           <td align=right><b>$lines</b></td></tr>
           <tr><td>Aantal woorden:</td><td align=right><b>$words</b></td></tr>
           <tr><td>Aantal tekens:</td><td align=right><b>$chars</b></td></tr>
           </table></qt>"
   }

A screenshot of the dialog is available at:

<img src="kate1.png_small.jpg" alt="kate1.png" width="400" height="325"/>
(click for real size)

Words Count in Selected Text

This we leave to the reader as nice exercise! Tip: use the DCOP function SelectionInterface#<number> hasSelection to get whether there is a selection in the current document and the command SelectionInterface#<number> selection to get the content fo the selection. Take care as well to show in the dialog with results that the results are for the selection not for whole document.

For more information on shell scripting you may consult the following documents:

• Bash beginners Guide (english)
• Advanced Bash-Scripting Guide