Konversation/Scripts/Scripting guide/uk

Вступ

У Konversation передбачено вбудовану підтримку запуску зовнішніх скриптів на основі якої, разом з використанням D-Bus та власних методів D-Bus Konversation, уможливлює керування у найпоширеніших випадках використання скриптів, зокрема показ даних у поточному вікні балачки або керування іншими програмами або навіть самою програмою Konversation. На цій сторінці ви знайдете основі відомості щодо написання скриптів Konversation. Тут наведено лише основні початкові відомості. Дані з використання особливостей мов програмування та операційних систем ви можете здобути самі з відповідної навчальної літератури.

Вимоги

Все, що вам знадобиться, — це текстовий редактор і інтерпретатор мови програмування або скриптів. У Konversation передбачено підтримку будь-якої мови програмування, інтерпретатор якої задовольняє таким вимогам:

1. Може приймати і обробляти аргументи командного рядка (argv).
2. Може встановлювати з’єднання і викликати D-Bus або принаймні виконувати зовнішні системні виклики (зокрема виконання програми qdbus). Ймовірно, краще і безпечніше використовувати вбудовані прив’язки D-Bus, якщо такі є, а не виконання системних викликів для запуску qdbus.

У поточній версії перевірено працездатність скриптів мовами Python, BASH (або командної оболонки) та Perl. Приклади скриптів цими мовами є частиною пакунків з Konversation. Але ви можете скористатися будь-якою іншою мовою, яка задовольняє викладені вище вимоги. На цій сторінці всі приклади наведено мовою Python.

Завдання 1. Показ даних у поточному вікні спілкування

Ймовірно, найтиповішим сценарієм для скрипту є отримання певного тексту для показу його на поточній вкладці Konversation (каналі або особистому діалозі) з даними, які зазвичай надходять із зовнішнього джерела. Джерелом може бути сам скрипт, інша програма (як у скрипті media, включеному у Konversation) або дані інтернету (зокрема отримання даних щодо погоди і показу їх у Konversation). Яким би не було джерело, слід виконати три дії:

1. Отримати вхідні дані — отримати і обробити команду, надіслану користувачем з вікна Konversation.
2. Обробити дані — зібрати дані з джерела і обробити їх відповідно до надісланої користувачем команди.
3. Надіслати дані — повернути дані назад до Konversation за допомогою D-Bus.

У наведеному нижче прикладі скрипт Konversation виконує саме ці три дії.

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# mood — скрипт Konversation для показу дотепного зауваження щодо настрою користувача.
# Використання: /exec mood [рядок_настрою]

import sys
import subprocess

command = ['qdbus', 'org.kde.konversation', '/irc']

argc = len(sys.argv)

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]

    if mood == "hungry":
        text = "Голодний! Зараз з’їм вашого коня!"
    elif mood == "sleepy":
        text = "Позіхаю, хочу спати."
    elif mood == "gloomy":
        text = "Троянди червоні. Нудьга чорна і моя нудьга теж..."
    elif mood == "happy":
        text = "Обдумую щасливі думки (навкруги кружляють феї щастя)."
    elif mood == "hyper":
        text = "Лише ложка цукру? Мені потрібен цілий пакунок!"
    elif mood == "excited":
        text = "Ми вже на місці? Ми вже на місці? Ми вже на місці?"
    else:
        text = "А про що ми, власне, вели розмову?"

        command.append("say")
        command.append(server)
        command.append(target)

command.append(text)

subprocess.Popen(command).communicate()

Отримання вхідних даних

Якщо програма Konversation викликає зовнішній скрипт, вона має передати йому декілька попередньо визначених аргументів, ось так:

назва_скрипту сервер призначення [додаткові аргументи...]

Аргументи зазвичай зберігаються у збірці (списку або масиві, залежно від мови), яка називається "argv", пронумеровані від 0 до N, де N — кількість аргументів.

• argv[0] завжди має значення назви самого скрипту. Здебільшого ігнорується.
• argv[1] — адреса сервера, з яким з’єднано користувача. Якщо з’єднання встановлено з багатьма серверами, сервер, з яким з’єднано канал або вікно діалогу.
• argv[2] — призначення, назва вікна спілкування, з якого надійшла команда щодо виконання скрипту, найчастіше те саме вікно, у якому буде показано виведені дані. Звичайно ж, ви можете змінити значення цього аргументу.
• від argv[3] до argv[N] будь-які додаткові аргументи, які буде надіслано користувачем, який віддав команду виконання скрипту за допомогою Konversation. Цими аргументами може бути будь-що від прапорців для вмикання або вимикання дій у скрипті до даних або тексту, який слід показати у даних, виведених скриптом. Додаткові аргументи передбачено не у всіх скриптах. Прикладами скриптів без додаткових аргументів є uptime та sysinfo.

Пам’ятайте!

Навіть якщо ваш скрипт не потребує додаткових аргументів або користувач не вказує цих аргументів, Konversation завжди надсилатиме аргументи системи та призначення. Тобто argv[1] і argv[2] завжди буде встановлено. Мінімальною кількістю аргументів завжди буде 3 (не забувайте, що нумерація починається з 0).

Обробка даних

У нашому прикладі скрипту змінна mood, яку вказує користувач як argv[3] скрипту, порівнюється з попередньо визначеними значеннями, після чого змінній text надається відповідне значення. Це простий приклад обробки даних. Ви також можете отримувати дна з попередньо визначеного джерела, подібно до того, як це робить скрипт fortune, або збирати дані з операційної системи, як це робить скрипт sysinfo. Які б дані або текст вам не потрібно було показати у Konversation, їх можна визначити у скрипті.

Попередження

Невеличке попередження: будьте обережні зі виведенням багаторядкових повідомлень, оскільки на сервері або каналі, якими ви користуєтеся, можуть бути жорсткі правила щодо розмірів повідомлень (захист від переповнення). Якщо розмір даних може бути доволі значним, краще подати їх у іншому форматі (подібно до текстового редактора).

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.

Надсилання вихідних даних

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 "qdbus". Without going into much detail, all the D-Bus commands we will be sending to make Konversation display messages starts with this string: qdbus org.kde.konversation /irc

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:

 qdbus org.kde.konversation /irc say server target message

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.

 qdbus org.kde.konversation /irc error message

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.

 qdbus org.kde.konversation /irc sayToAll message

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.

 qdbus org.kde.konversation /irc actionToAll message

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.

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

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, "qdbusviewer", 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.

Запуск скрипту

Now it's time to actually make the script run in Konversation. Here are the steps:

• Make your script executable.

chmod +x script_name 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 kde4-config --install data and append /konversation/scripts/ 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 media script as an example, since it comes with any Konversation installation): /exec --showpath media. 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:

/exec script_name [additional arguments]

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 Settings -> Configure Konversation -> Command Aliases page. Click on the New 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 /script_name [arguments]
• 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.

For the previous example, the script is named "mood" and can be invoked either using /mood [mood] or /exec mood [mood], like:

/mood gloomy

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.

Завдання 2. Керування зовнішньою програмою з вікна Konversation

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 provding only the report number (like the bug script), or simply running a system command (and probably displaying the results of that command, as the cmd script does).

The following script performs the first example. It first makes 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.

#!/usr/bin/env python
# yakrun — скрипт Konversation, який виконує вказану користувачем команду у Yakuake і перемикає стан Yakuake
# Використання: /exec yakrun [команда]

import sys
import subprocess

errorCommand  = ['qdbus', 'org.kde.konversation', '/irc', 'error']
toggleCommand = ['qdbus', 'org.kde.yakuake', '/yakuake/window', 'toggleWindowState']
runCommand    = ['qdbus', 'org.kde.yakuake', '/yakuake/sessions', 'runCommand']

argc = len(sys.argv)

if argc < 4:
    text = "Не вказано команди."

    errorCommand.append(text)

    subprocess.Popen(errorCommand).communicate()
else:
    command = " ".join(sys.argv[3:])

    runCommand.append(command)

    subprocess.Popen(toggleCommand).communicate()
    subprocess.Popen(runCommand).communicate()

Нотатки щодо використання певних мов

• 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.