View source for Konversation/Scripts/Scripting guide

<languages />
<translate>

== Introduction == <!--T:1-->

<!--T:2-->
'''Konversation''' has built-in support for running external scripts which, partnered with D-Bus and '''Konversation's''' own D-Bus methods, cover the most common scripting use cases, such as displaying information in the current chat window or controlling another application or even '''Konversation''' itself. This guide introduces the basics of writing a '''Konversation''' script. It covers only the essential concepts necessary to get started. Language- and system-specific nuances will be left to the user as a learning exercise.

== Requirements == <!--T:3-->

<!--T:4-->
All you need is a text editor and a programming/scripting language. '''Konversation''' supports any programming language that:

<!--T:5-->
# Can accept and process command-line arguments (argv's).
# Can connect to and call D-Bus, or at least make external system calls (such as executing the program "<code>qdbus</code>"). It is probably better and more secure to use the language's native D-Bus bindings if available, rather than executing a system call to run <code>qdbus</code>.

<!--T:6-->
At the moment, Python, BASH (or Shell), and Perl are known to work and have examples shipped with '''Konversation'''. But any language fulfilling the two requirements above would probably also work. This guide will give examples in Python.

== Case 1: Display Information into the Current Chat Window == <!--T:7-->

<!--T:8-->
Probably the most common scripting scenario is getting some text to display in the current '''Konversation''' tab (channel or private message), with the data usually coming from an external source. This source could be the script itself, another application (such as the <code>media</code> script included with '''Konversation'''), or the Internet (like getting weather information and displaying it in '''Konversation'''). Whatever the source, there are 3 steps to perform:

<!--T:9-->
# Getting the input - catching and parsing the command sent by the user from '''Konversation'''.
# Processing the data - gathering data from sources and manipulating it based on the input.
# Sending the output - throwing the information back to '''Konversation''' through D-Bus.

<!--T:10-->
The following is a nonsensical example of a '''Konversation''' script that roughly follows that pattern.


<!--T:11-->
<!--}}-->{{Input|<syntaxhighlight lang="python">
#!/usr/bin/env python
# mood - a Konversation script to display a witty remark based on the user's mood.
# Usage: /exec mood [mood_string]

<!--T:12-->
import sys
import subprocess

<!--T:13-->
command = ['qdbus', 'org.kde.konversation', '/irc']

<!--T:14-->
argc = len(sys.argv)

<!--T:15-->
if argc < 2:
    command.append("error")
    text = "Server required"
elif argc < 3:
    command.append("error")
    text = "Target required"
elif argc < 4:
    command.append("error")
    text = "No mood given"
else:
    server = sys.argv[1]
    target = sys.argv[2]
    mood   = sys.argv[3]

    <!--T:16-->
if mood == "hungry":
        text = "Hungry! Anyone got a horse?"
    elif mood == "sleepy":
        text = "I yawn, therefore I am."
    elif mood == "gloomy":
        text = "Roses are red. Violets are blue, and so am I ..."
    elif mood == "happy":
        text = "Thinking happy thoughts (with a dash of pixie dust)."
    elif mood == "hyper":
        text = "Just a spoonful of sugar? I think I took a whole jar! *cartwheels*"
    elif mood == "excited":
        text = "Are we there yet? Are we there yet? Are we there yet?"
    else:
        text = "What were we talking about again?"

        <!--T:17-->
command.append("say")
        command.append(server)
        command.append(target)

<!--T:18-->
command.append(text)

<!--T:19-->
subprocess.Popen(command).communicate()
</syntaxhighlight>}}<!--{{-->

=== Getting the Input === <!--T:20-->

<!--T:21-->
When '''Konversation''' calls an external script, it runs it with some predefined arguments, like this:

<!--T:22-->
<code>script_name server target [additional arguments ...]</code>

<!--T:23-->
Arguments are usually stored in a collection (a list or an array, depending on the language) called "argv" indexed from 0 to N, with N being the number of arguments.

<!--T:24-->
* ''argv[0]'' is always the script name itself. In most cases, it's safe to ignore this.

<!--T:60-->
* ''argv[1''] is the address of the server the user is currently connected to. In case of multiple connected servers, this will always be the server to which the channel or query window is connected to.

<!--T:61-->
* ''argv[2]'' is the target, the name of the chat window where the command to run the script came from which, more often than not, would be the same window where output would be displayed. Of course, you can always change this.

<!--T:62-->
* ''argv[3]'' to ''argv[N]'' will be any additional arguments that would be sent by the user calling the script through '''Konversation'''. This can be anything from flags to enable/disable options in the script or data or text that can be displayed in the output of the script. Not all scripts have additional arguments, like the <code>uptime</code> and <code>sysinfo</code> scripts.

<!--T:25-->
{{Remember|1= Even if your script doesn't require additional arguments or even if the user didn't supply them, '''Konversation''' will always send the system and target arguments. Meaning, ''argv[1]'' and ''argv[2]'' will always be set. The minimum argument count will always be 3 (remember, indexing starts at 0).}}

=== Processing the Data === <!--T:26-->

<!--T:27-->
In the example script, the ''mood'' variable, supplied by the user in ''argv[3]'' of the script, is compared to predefined values and the appropriate remark is assigned to the ''text'' variable. This is a simple example of data processing. You can also fetch data from a predefined data source, like the <code>fortune</code> script. Or assemble information coming from the operating system, such as done in the <code>sysinfo</code> script. Whatever information or text you need to be displayed in '''Konversation''', you create that here.

<!--T:28-->
{{Warning|1=A word of caution: Be careful when creating multi-line text output, as your server or the channel you're sending to may have anti-flooding policies. When dealing with a potentially large, it might be best to have it displayed in another way (like in a text editor).}}

<!--T:29-->
Now that the needed information is processed and assembled, it's time to prepare it for sending back into '''Konversation''', which is discussed in the next section.

=== Sending the Output === <!--T:30-->

<!--T:31-->
Controlling '''Konversation''' externally, like through a script or the command-line, involves using its D-Bus methods. '''Konversation''' has several of them, including a group whose purpose is to display messages. Sending D-Bus messages can be tedious. Fortunately, Qt provides a much easier way of doing that, using the helper program "<code>qdbus</code>". Without going into much detail, all the D-Bus commands we will be sending to make '''Konversation''' display messages starts with this string:
<code> qdbus org.kde.konversation /irc</code>

<!--T:32-->
Depending on what kind of message the script will be sending, additional options will be added to that command. Here are but a few examples:
{{Input|<syntaxhighlight lang="perl">
 qdbus org.kde.konversation /irc say server target message
</syntaxhighlight>}}
This is probably the command that will be most commonly used. It sends message to the chat window target connected to server. If you want the message to be sent to the same chat window where the script was called from, use ''argv[1]'' and ''argv[2]'' for server and target, respectively. Of course you can always change the target to any channel or nick you want in that server.

<!--T:33-->
{{Input|<syntaxhighlight lang="bash">
 qdbus org.kde.konversation /irc error message
</syntaxhighlight>}}
This displays the message in the same chat window where the script was invoked. The difference is that the message isn't actually sent to the IRC server and is only visible to the user. The message is also formatted as something like ''"[D-Bus] Error: message"''. Useful for informing the user about errors in using the script or if something fails in the script. It doesn't need a server or a target.

<!--T:34-->
{{Input|<syntaxhighlight lang="bash">
 qdbus org.kde.konversation /irc sayToAll message
</syntaxhighlight>}}
Sends the message to all channels and query windows in all servers. Please use sparingly and observe proper netiquette. It doesn't require a server and a target.

<!--T:35-->
{{Input|<syntaxhighlight lang="bash">
 qdbus org.kde.konversation /irc actionToAll message
</syntaxhighlight>}}
sayToAll's action sibling. Sends the message to all channels and query windows in all servers BUT prepends "/me" to the actual message, resulting in displaying something like ''"*YourNick message*"''. Again, netiquette applies.

<!--T:36-->
{{Note|To send an action ("/me") message only to the current chat window (where the script was called from), compose the actual message as "/me message" and use the say variant of the command (first one in this list if you got lost {{smiley}}).}}

<!--T:37-->
There are other /irc related qdbus commands, some of which change the user's status instead of displaying the command. Feel free to explore other possibilities. Another Qt helper program, "<code>qdbusviewer</code>", provides a graphical interface for browsing through the available commands for '''Konversation''' and other "D-Bus aware" programs. You will probably need it a lot especially for the second scripting scenario discussed later.

=== Getting the Script to Run === <!--T:38-->

<!--T:39-->
Now it's time to actually make the script run in '''Konversation'''. Here are the steps:

<!--T:40-->
* Make your script executable.
<code> chmod +x script_name</code> does it all. It would be better to not include extensions (.sh, .py, .pl, etc.) in your filename, to make it easier to call the script.
* Place the script in either one of two folders:
** If you want your script to be available all users in your system, put the script together with the other scripts installed with '''Konversation'''. This may vary from distro to distro (or your own personal tinkering), but common a location is ''/usr/share/apps/konversation/scripts/''. In case it's not there, get the output of the command <code>kde4-config --install data</code> and append <code>/konversation/scripts/</code> to it. Consult your distribution's support channel if it's still not there.
** If you want the script just for yourself, simply place the script in ''~/.kde/share/apps/konversation/scripts/''. Some distros might still be using ~/.kde4/ instead so adjust accordingly.
** Post version 1.3.1 note: another way to find out where the installed scripts are is to run this command in '''Konversation's''' input line (using the <code>media</code> script as an example, since it comes with any '''Konversation''' installation): <code>/exec --showpath media</code>. Note that if there are two scripts with the same name in the user's home and in the system locations, the one in the user's home will take precedence and be the one shown here.
* To actually run the script, you need to invoke it by running this command in '''Konversation's''' input line:
<code> /exec script_name [additional arguments]</code>

<!--T:41-->
This will call your script and pass the arguments to it. Remember that your script_name is always ''argv[0]'', and that the current server and chat window are passed as ''argv[1]'' and ''argv[2]'', even if you didn't include them in your command. Therefore, any additional arguments would be ''argv[3]'' and so on.
* For convenience, you can create a command alias in '''Konversation''' so that you can invoke your script simply using /script_name instead of the actual syntax given above. To manually do this, go to <menuchoice>Settings -> Configure Konversation -> Command Aliases</menuchoice> page. Click on the <menuchoice>New</menuchoice> button and enter "script_name" as the ''Alias'' and "/exec script_name" as the ''Replacement''. So next time you need to run your script, you can simply do use <code>/script_name [arguments]</code>
* Alternately, whenever '''Konversation''' is started, it automatically creates a command alias of "/script_name" for "/exec script_name" for every script it finds in the scripts/ directories mentioned earlier.

<!--T:42-->
For the previous example, the script is named "mood" and can be invoked either using <code>/mood [mood]</code> or <code>/exec mood [mood]</code>, like:

 <!--T:43-->
/mood gloomy

<!--T:44-->
That's basically all you need to know to make a '''Konversation''' script. To make it a bit more interesting, let's have an example of another common scripting scenario.

== Case 2: Controlling an External Program from Konversation == <!--T:45-->

<!--T:46-->
Thanks to D-Bus, and the fact that a lot of KDE applications have D-Bus methods, you can control any KDE application right from within '''Konversation'''. Even without D-Bus, you can let your script start, stop, or possibly even control other applications simply with a command in '''Konversation'''. This lets you do a lot of things, like sending a command to a terminal emulator, opening a bug report in a browser providing only the report number (like the <code>bug</code> script), or simply running a system command (and probably displaying the results of that command, as the <code>cmd</code> script does).

<!--T:47-->
The following script performs the first example. It first makes [[Special:mylanguage/Yakuake|Yakuake]] visible and then runs the command supplied by the user. The script is rather simple and doesn't involve displaying anything back to the user, except in the case of an error when calling the script itself.

<!--T:48-->
{{Input|1=<syntaxhighlight lang="python">
#!/usr/bin/env python
# yakrun - Konversation script that runs the command supplied by the user in Yakuake and toggles Yakuake's state
# Usage: /exec yakrun [command]

<!--T:49-->
import sys
import subprocess

<!--T:50-->
errorCommand  = ['qdbus', 'org.kde.konversation', '/irc', 'error']
toggleCommand = ['qdbus', 'org.kde.yakuake', '/yakuake/window', 'toggleWindowState']
runCommand    = ['qdbus', 'org.kde.yakuake', '/yakuake/sessions', 'runCommand']

<!--T:51-->
argc = len(sys.argv)

<!--T:52-->
if argc < 4:
    text = "No command to run."

    <!--T:53-->
errorCommand.append(text)

    <!--T:54-->
subprocess.Popen(errorCommand).communicate()
else:
    command = " ".join(sys.argv[3:])

    <!--T:55-->
runCommand.append(command)

    <!--T:56-->
subprocess.Popen(toggleCommand).communicate()
    subprocess.Popen(runCommand).communicate()
</syntaxhighlight>}}

= Language-specific Notes = <!--T:57-->

<!--T:58-->
* Be careful when processing arguments and assembling them into a single string with spaces, which might be more error-prone in some languages, such as BASH.

<!--T:59-->
[[Category:Internet]]
[[Category:Advanced Users]]
</translate>