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, їх можна визначити у скрипті.

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

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

Тепер, коли потрібні дані оброблено та зібрано, час підготувати їх до надсилання до вікна Konversation. Питання надсилання ми обговоримо у наступному розділі.

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

Керування Konversation ззовні, зі скрипту чи з командного рядка, пов’язане з використанням методів D-Bus програми. У Konversation передбачено декілька методів, зокрема методи, призначені для показу повідомлень. Надсилання повідомлень D-Bus — справа доволі непроста. На щастя, у Qt передбачено набагато простіший спосіб виконання цього завдання, за допомогою програми "qdbus". Якщо не надто заглиблюватися, всі команди D-Bus, які ми надсилатимемо Konversation з метою показу повідомлень, починатимуться з такого рядка: qdbus org.kde.konversation /irc

Залежно від типу повідомлення, яке надсилатиме скрипт, до команди буде додано додаткові параметри. Ось приклад:

 qdbus org.kde.konversation /irc say сервер призначення повідомлення

Це, ймовірно, команда, яку використовують найчастіше. Команда надсилає «повідомлення» до вікна спілкування «призначення», з’єднаного з сервером «сервер». Якщо повідомлення слід надіслати до того самого вікна, з якого викликано скрипт, скористайтеся змінними argv[1] та argv[2] на місці сервера і призначення, відповідно. Звичайно ж, ви завжди можете змінити призначення на будь-який канал або псевдонім, потрібний вам на певному сервері.

 qdbus org.kde.konversation /irc error повідомлення

За допомогою цієї команди можна показати «повідомлення» у тому самому вікні спілкування, з якого було викликано скрипт. Відмінність полягає у тому, що повідомлення не буде надіслано безпосередньо на сервер IRC, бачитиме його лише користувач скрипту. Повідомлення також буде форматовано: "[D-Bus] Помилка: повідомлення". Цей спосіб корисний для інформування користувача про помилки у використанні скрипту або помилки, які виникли під час виконання самого скрипту. Вказувати призначення у команді не потрібно.

 qdbus org.kde.konversation /irc sayToAll повідомлення

Надіслати повідомлення до всіх каналів та вікон діалогів на всіх серверах. Слід використовувати обережно з врахуванням правил етикету. Сервер і вікно призначення вказувати не потрібно.

 qdbus org.kde.konversation /irc actionToAll повідомлення

Близнюк дії sayToAll. Надсилає повідомлення на всі канали і до всіх вікон діалогів на всіх серверах, але додає перед повідомленням «/me». В результаті користувачі побачать "*ваш_псевдонім повідомлення*". Знову ж таки, врахуйте правила етикету.

Зауваження

Щоб надіслати повідомлення про дію (з «/me») лише у вікно поточного спілкування (звідки було викликано скрипт), створіть текстову частину у форматі «/me повідомлення», а потім скористайтеся командою say (перша у списку, якщо ви не помітили ).

Передбачено і інші пов’язані з /irc команди qdbus, деякі з них змінюють стан користувача у мережі замість показу повідомлень. Дослідіть самі всі можливості. За допомогою ще однієї з програм Qt, "qdbusviewer", ви зможете переглянути у графічному інтерфейсі повний список всіх команд керування Konversation та інших програм, які використовують D-Bus. Такі команди знадобляться вам для наступного скриптового сценарію, описаного нижче.

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

Тепер можна зробити так, щоб скриптом можна було скористатися у Konversation. Ось що треба зробити:

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