Konversation/Scripts/Scripting guide/uk: Difference between revisions

From KDE Wiki Sandbox
(Created page with "== Вимоги ==")
No edit summary
 
(61 intermediate revisions by 2 users not shown)
Line 3: Line 3:
== Вступ ==
== Вступ ==


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


== Вимоги ==
== Вимоги ==


All you need is a text editor and a programming/scripting language. '''Konversation''' supports any programming language that:
Все, що вам знадобиться, — це текстовий редактор і інтерпретатор мови програмування або скриптів. У '''Konversation''' передбачено підтримку будь-якої мови програмування, інтерпретатор якої задовольняє таким вимогам:


# Can accept and process command-line arguments (argv's)
# Може приймати і обробляти аргументи командного рядка (argv).
# 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>.
# Може встановлювати з’єднання і викликати D-Bus або принаймні виконувати зовнішні системні виклики (зокрема виконання програми <code>qdbus</code>). Ймовірно, краще і безпечніше використовувати вбудовані прив’язки D-Bus, якщо такі є, а не виконання системних викликів для запуску <code>qdbus</code>.


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


== Case 1: Display Information into the Current Chat Window ==
== Завдання 1. Показ даних у поточному вікні спілкування ==


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:
Ймовірно, найтиповішим сценарієм для скрипту є отримання певного тексту для показу його на поточній вкладці '''Konversation''' (каналі або особистому діалозі) з даними, які зазвичай надходять із зовнішнього джерела. Джерелом може бути сам скрипт, інша програма (як у скрипті <code>media</code>, включеному у '''Konversation''') або дані інтернету (зокрема отримання даних щодо погоди і показу їх у '''Konversation'''). Яким би не було джерело, слід виконати три дії:


# Getting the input - catching and parsing the command sent by the user from Konversation
# Отримати вхідні дані — отримати і обробити команду, надіслану користувачем з вікна '''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
# Надіслати дані — повернути дані назад до '''Konversation''' за допомогою D-Bus.


The following is a nonsensical example of a '''Konversation''' script that roughly follows that pattern.
У наведеному нижче прикладі скрипт '''Konversation''' виконує саме ці три дії.




{{Input|<syntaxhighlight lang="python">
<!--}}-->{{Input|<syntaxhighlight lang="python">
#!/usr/bin/env python
#!/usr/bin/env python
# mood - a Konversation script to display a witty remark based on the user's mood
# -*- coding: utf-8 -*-
# Usage: /exec mood [mood_string]
# mood — скрипт Konversation для показу дотепного зауваження щодо настрою користувача.
# Використання: /exec mood [рядок_настрою]


import sys
import sys
Line 52: Line 53:


     if mood == "hungry":
     if mood == "hungry":
         text = "Hungry! Anyone got a horse?"
         text = "Голодний! Зараз з’їм вашого коня!"
     elif mood == "sleepy":
     elif mood == "sleepy":
         text = "I yawn, therefore I am."
         text = "Позіхаю, хочу спати."
     elif mood == "gloomy":
     elif mood == "gloomy":
         text = "Roses are red. Violets are blue, and so am I ..."
         text = "Троянди червоні. Нудьга чорна і моя нудьга теж..."
     elif mood == "happy":
     elif mood == "happy":
         text = "Thinking happy thoughts (with a dash of pixie dust)."
         text = "Обдумую щасливі думки (навкруги кружляють феї щастя)."
     elif mood == "hyper":
     elif mood == "hyper":
         text = "Just a spoonful of sugar? I think I took a whole jar! *cartwheels*"
         text = "Лише ложка цукру? Мені потрібен цілий пакунок!"
     elif mood == "excited":
     elif mood == "excited":
         text = "Are we there yet? Are we there yet? Are we there yet?"
         text = "Ми вже на місці? Ми вже на місці? Ми вже на місці?"
     else:
     else:
         text = "What were we talking about again?"
         text = "А про що ми, власне, вели розмову?"


         command.append("say")
         command.append("say")
Line 73: Line 74:


subprocess.Popen(command).communicate()
subprocess.Popen(command).communicate()
</syntaxhighlight>}}
</syntaxhighlight>}}<!--{{-->
 
=== Отримання вхідних даних ===
 
Якщо програма '''Konversation''' викликає зовнішній скрипт, вона має передати йому декілька попередньо визначених аргументів, ось так:
 
<code>назва_скрипту сервер призначення [додаткові аргументи...]</code>


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


When '''Konversation''' calls an external script, it runs it with some predefined arguments, like this:
* ''argv[0]'' завжди має значення назви самого скрипту. Здебільшого ігнорується.


<code>script_name server target [additional arguments ...]</code>
* ''argv[1]'' — адреса сервера, з яким з’єднано користувача. Якщо з’єднання встановлено з багатьма серверами, сервер, з яким з’єднано канал або вікно діалогу.


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.
* ''argv[2]'' — призначення, назва вікна спілкування, з якого надійшла команда щодо виконання скрипту, найчастіше те саме вікно, у якому буде показано виведені дані. Звичайно ж, ви можете змінити значення цього аргументу.


* ''argv[0]'' is always the script name itself. In most cases, it's safe to ignore this.
* від ''argv[3]'' до ''argv[N]'' будь-які додаткові аргументи, які буде надіслано користувачем, який віддав команду виконання скрипту за допомогою '''Konversation'''. Цими аргументами може бути будь-що від прапорців для вмикання або вимикання дій у скрипті до даних або тексту, який слід показати у даних, виведених скриптом. Додаткові аргументи передбачено не у всіх скриптах. Прикладами скриптів без додаткових аргументів є <code>uptime</code> та <code>sysinfo</code>.
* ''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.
* ''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.
* ''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.


{{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).}}
{{Remember_(uk)|1=Навіть якщо ваш скрипт не потребує додаткових аргументів або користувач не вказує цих аргументів, '''Konversation''' завжди надсилатиме аргументи системи та призначення. Тобто ''argv[1]'' і ''argv[2]'' завжди буде встановлено. Мінімальною кількістю аргументів завжди буде 3 (не забувайте, що нумерація починається з 0).}}


=== Processing the Data ===
=== Обробка даних ===


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


{{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).}}
{{Warning_(uk)|1=Невеличке попередження: будьте обережні зі виведенням багаторядкових повідомлень, оскільки на сервері або каналі, якими ви користуєтеся, можуть бути жорсткі правила щодо розмірів повідомлень (захист від переповнення). Якщо розмір даних може бути доволі значним, краще подати їх у іншому форматі (подібно до текстового редактора).}}


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.
Тепер, коли потрібні дані оброблено та зібрано, час підготувати їх до надсилання до вікна '''Konversation'''. Питання надсилання ми обговоримо у наступному розділі.


=== Sending the Output ===
=== Надсилання вихідних даних ===


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


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">
{{Input|<syntaxhighlight lang="perl">
  qdbus org.kde.konversation /irc say server target message
  qdbus org.kde.konversation /irc say сервер призначення повідомлення
</syntaxhighlight>}}
</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.
Це, ймовірно, команда, яку використовують найчастіше. Команда надсилає «повідомлення» до вікна спілкування «призначення», з’єднаного з сервером «сервер». Якщо повідомлення слід надіслати до того самого вікна, з якого викликано скрипт, скористайтеся змінними ''argv[1]'' та ''argv[2]'' на місці сервера і призначення, відповідно. Звичайно ж, ви завжди можете змінити призначення на будь-який канал або псевдонім, потрібний вам на певному сервері.


{{Input|<syntaxhighlight lang="bash">
{{Input|<syntaxhighlight lang="bash">
  qdbus org.kde.konversation /irc error message
  qdbus org.kde.konversation /irc error повідомлення
</syntaxhighlight>}}
</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.
За допомогою цієї команди можна показати «повідомлення» у тому самому вікні спілкування, з якого було викликано скрипт. Відмінність полягає у тому, що повідомлення не буде надіслано безпосередньо на сервер IRC, бачитиме його лише користувач скрипту. Повідомлення також буде форматовано: ''"[D-Bus] Помилка: повідомлення"''. Цей спосіб корисний для інформування користувача про помилки у використанні скрипту або помилки, які виникли під час виконання самого скрипту. Вказувати призначення у команді не потрібно.


{{Input|<syntaxhighlight lang="bash">
{{Input|<syntaxhighlight lang="bash">
  qdbus org.kde.konversation /irc sayToAll message
  qdbus org.kde.konversation /irc sayToAll повідомлення
</syntaxhighlight>}}
</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.
Надіслати повідомлення до всіх каналів та вікон діалогів на всіх серверах. Слід використовувати обережно з врахуванням правил етикету. Сервер і вікно призначення вказувати не потрібно.


{{Input|<syntaxhighlight lang="bash">
{{Input|<syntaxhighlight lang="bash">
  qdbus org.kde.konversation /irc actionToAll message
  qdbus org.kde.konversation /irc actionToAll повідомлення
</syntaxhighlight>}}
</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.
Близнюк дії sayToAll. Надсилає повідомлення на всі канали і до всіх вікон діалогів на всіх серверах, але додає перед повідомленням «/me». В результаті користувачі побачать ''"*ваш_псевдонім повідомлення*"''. Знову ж таки, врахуйте правила етикету.


{{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}}).}}
{{Note_(uk)|Щоб надіслати повідомлення про дію (з «/me») лише у вікно поточного спілкування (звідки було викликано скрипт), створіть текстову частину у форматі «/me повідомлення», а потім скористайтеся командою say (перша у списку, якщо ви не помітили {{smiley}}).}}


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


=== Getting the Script to Run ===
=== Запуск скрипту ===


Now it's time to actually make the script run in '''Konversation'''. Here are the steps:
Тепер можна зробити так, щоб скриптом можна було скористатися у '''Konversation'''. Ось що треба зробити:


* 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.
<code> chmod +x script_name</code>. Варто не додавати суфікса до назви вашого скрипту (.sh, .py, .pl тощо), щоб скрипт простіше було викликати.
* 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>


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>
** Якщо вашим скриптом будуть користуватися всі користувачі системи, скопіюйте його до теки, у якій зберігаються інші скрипти, встановлені разом з '''Konversation'''. Точна адреса теки залежить від вашого дистрибутива (або ваших особистих налаштувань), типовою є адреса ''/usr/share/apps/konversation/scripts/''. Якщо такої теки у вашій системі немає, спробуйте скористатися даними, виведеними командою <code>kde4-config --install data</code>, додавши до назви теки <code>/konversation/scripts/</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.
** Якщо скриптом користуватиметеся лише ви, просто скопіюйте його до ''~/.kde/share/apps/konversation/scripts/''. У деяких дистрибутивах все ще використовується тека, ~/.kde4/. Виправте адресу, якщо у вашому дистрибутиві використано саме цю теку.
** Зауваження щодо версій, новіших за 1.3.1: ще одним способом визначення теки, куди встановлено скрипти, є така команда, віддана у рядку введення повідомлення '''Konversation''' (у нашому прикладі використано скрипт <code>media</code>, оскільки цей скрипти встановлюється разом з '''Konversation'''): <code>/exec --showpath media</code>. Зауважте, що якщо існує два скрипти з однаковими назвами, один у домашній теці користувача і один у загальносистемній теці, пріоритет матиме скрипт з теки користувача, саме його адресу буде показано у відповідь на вказану вище команду.


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:
* Для виконання скрипту вам слід викликати його з командного рядка '''Konversation''':
<code> /exec назва_скрипту [додаткові аргументи]</code>
 
Ця команда викличе ваш скрипт і передасть йому аргументи. Зауважте, що значенням ''argv[0]'' завжди буде «назва_скрипту», а назву сервера та вікна спілкування буде передано як ''argv[1]'' і ''argv[2]'', навіть якщо ви не вкажете значення цих змінних у вашій команді. Тому додаткові аргументи буде передано як ''argv[3]'' тощо.
 
* Для полегшення користування ви можете створити у '''Konversation''' псевдоніми (скорочення) команд. Тоді ваш скрипт можна буде виликати за допомогою команди /назва_скрипту замість наведеного вище загального варіанта. Для додавання псевдоніма вручну, скористайтеся сторінкою <menuchoice>Параметри -> Налаштувати Konversation -> Скорочення команд</menuchoice>. Натисніть кнопку <menuchoice>Створити</menuchoice> і вкажіть «назву_скрипту» у полі <menuchoice>Замінник</menuchoice>' і "/exec script_name" у полі <menuchoice>Заміна</menuchoice>. Надалі ви зможете запускати ваш скрипт за допомогою команди <code>/назва_скрипту [аргументи]</code>
 
* Крім того, під час запуску '''Konversation''' програма автоматично створюватиме замінники команд у форматі "/назва_скрипту" для "/exec назва_скрипту" всіх скриптів, які буде знайдено у теках scripts/ тек, про які ми говорили раніше.
 
Для скрипту, описаного у нашому попередньому прикладі, назвою буде "mood", а викликати скрипт можна буде командою <code>/mood [настрій]</code> або <code>/exec mood [настрій]</code>, ось так:


  /mood gloomy
  /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.
Це в основному все, що вам потрібно знати для створення скрипту '''Konversation'''. Щоб додати ще трохи цікавинки, розгляньмо інший поширений випадок використання скриптів.


== Case 2: Controlling an External Program from Konversation ==
== Завдання 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 <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).
Завдяки D-Bus та тому, що у багатьох програмах KDE передбачено можливість використання методів D-Bus, ви можете керувати будь-якою програмою KDE безпосередньо з вікна '''Konversation'''. Навіть без D-Bus ви, за допомогою свого скрипту, можете запускати, зупиняти та навіть керувати іншими програмами простою командою '''Konversation'''. Таким чином можна виконувати безліч завдань, зокрема надсилати команду емулятору термінала, відкривати повідомлення щодо вад у вікні переглядача за номером звіту щодо вади (як це реалізовано у скрипті <code>bug</code>) або просто виконати системну команду (і можливо показати результати її виконання, як це робить скрипт <code>cmd</code>).


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.
Наведений вище скрипт реалізує першу можливість. Він розкриває вікно [[Special:mylanguage/Yakuake|Yakuake]] і виконує у ньому вказану користувачем команду. Скрипт доволі примітивний: він не показуватиме виведених даних користувачеві, хіба що станеться помилка у самому скрипті.


{{Input|1=<syntaxhighlight lang="python">
<!--}}-->{{Input|1=<syntaxhighlight lang="python">
#!/usr/bin/env python
#!/usr/bin/env python
# yakrun - Konversation script that runs the command supplied by the user in Yakuake and toggles Yakuake's state
# yakrun — скрипт Konversation, який виконує вказану користувачем команду у Yakuake і перемикає стан Yakuake
# Usage: /exec yakrun [command]
# Використання: /exec yakrun [команда]


import sys
import sys
Line 172: Line 180:


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


     errorCommand.append(text)
     errorCommand.append(text)
Line 184: Line 192:
     subprocess.Popen(toggleCommand).communicate()
     subprocess.Popen(toggleCommand).communicate()
     subprocess.Popen(runCommand).communicate()
     subprocess.Popen(runCommand).communicate()
</syntaxhighlight>}}
</syntaxhighlight>}}<!--{{-->


= Language-specific Notes =
== Нотатки щодо використання певних мов ==


* 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.
* Будьте обережними з обробкою аргументів і збиранням їх до одного рядка з пробілами. Подібні дії можуть призвести до повідомлень про помилки у деяких мовах програмування, зокрема BASH.


[[Category:Internet]]
[[Category:Інтернет/uk]]
[[Category:Advanced Users]]
[[Category:Досвідченим користувачам/uk]]

Latest revision as of 16:30, 5 August 2011

Other languages:

Вступ

У 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. Ось що треба зробити:

  • Надайте скрипту право виконуватися. Для цього достатньо команди

chmod +x script_name. Варто не додавати суфікса до назви вашого скрипту (.sh, .py, .pl тощо), щоб скрипт простіше було викликати.

  • Розташуйте скрипт одній з двох тек:
    • Якщо вашим скриптом будуть користуватися всі користувачі системи, скопіюйте його до теки, у якій зберігаються інші скрипти, встановлені разом з Konversation. Точна адреса теки залежить від вашого дистрибутива (або ваших особистих налаштувань), типовою є адреса /usr/share/apps/konversation/scripts/. Якщо такої теки у вашій системі немає, спробуйте скористатися даними, виведеними командою kde4-config --install data, додавши до назви теки /konversation/scripts/. Порадьтеся з каналом підтримки дистрибутива, якщо і так не вдасться визначити потрібну адресу.
    • Якщо скриптом користуватиметеся лише ви, просто скопіюйте його до ~/.kde/share/apps/konversation/scripts/. У деяких дистрибутивах все ще використовується тека, ~/.kde4/. Виправте адресу, якщо у вашому дистрибутиві використано саме цю теку.
    • Зауваження щодо версій, новіших за 1.3.1: ще одним способом визначення теки, куди встановлено скрипти, є така команда, віддана у рядку введення повідомлення Konversation (у нашому прикладі використано скрипт media, оскільки цей скрипти встановлюється разом з Konversation): /exec --showpath media. Зауважте, що якщо існує два скрипти з однаковими назвами, один у домашній теці користувача і один у загальносистемній теці, пріоритет матиме скрипт з теки користувача, саме його адресу буде показано у відповідь на вказану вище команду.
  • Для виконання скрипту вам слід викликати його з командного рядка Konversation:

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

Ця команда викличе ваш скрипт і передасть йому аргументи. Зауважте, що значенням argv[0] завжди буде «назва_скрипту», а назву сервера та вікна спілкування буде передано як argv[1] і argv[2], навіть якщо ви не вкажете значення цих змінних у вашій команді. Тому додаткові аргументи буде передано як argv[3] тощо.

  • Для полегшення користування ви можете створити у Konversation псевдоніми (скорочення) команд. Тоді ваш скрипт можна буде виликати за допомогою команди /назва_скрипту замість наведеного вище загального варіанта. Для додавання псевдоніма вручну, скористайтеся сторінкою Параметри -> Налаштувати Konversation -> Скорочення команд. Натисніть кнопку Створити і вкажіть «назву_скрипту» у полі Замінник' і "/exec script_name" у полі Заміна. Надалі ви зможете запускати ваш скрипт за допомогою команди /назва_скрипту [аргументи]
  • Крім того, під час запуску Konversation програма автоматично створюватиме замінники команд у форматі "/назва_скрипту" для "/exec назва_скрипту" всіх скриптів, які буде знайдено у теках scripts/ тек, про які ми говорили раніше.

Для скрипту, описаного у нашому попередньому прикладі, назвою буде "mood", а викликати скрипт можна буде командою /mood [настрій] або /exec mood [настрій], ось так: 

/mood gloomy

Це в основному все, що вам потрібно знати для створення скрипту Konversation. Щоб додати ще трохи цікавинки, розгляньмо інший поширений випадок використання скриптів.

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

Завдяки D-Bus та тому, що у багатьох програмах KDE передбачено можливість використання методів D-Bus, ви можете керувати будь-якою програмою KDE безпосередньо з вікна Konversation. Навіть без D-Bus ви, за допомогою свого скрипту, можете запускати, зупиняти та навіть керувати іншими програмами простою командою Konversation. Таким чином можна виконувати безліч завдань, зокрема надсилати команду емулятору термінала, відкривати повідомлення щодо вад у вікні переглядача за номером звіту щодо вади (як це реалізовано у скрипті bug) або просто виконати системну команду (і можливо показати результати її виконання, як це робить скрипт cmd).

Наведений вище скрипт реалізує першу можливість. Він розкриває вікно Yakuake і виконує у ньому вказану користувачем команду. Скрипт доволі примітивний: він не показуватиме виведених даних користувачеві, хіба що станеться помилка у самому скрипті. 

#!/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()

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

  • Будьте обережними з обробкою аргументів і збиранням їх до одного рядка з пробілами. Подібні дії можуть призвести до повідомлень про помилки у деяких мовах програмування, зокрема BASH.
Retrieved from "https://wikisandbox.kde.org/index.php?title=Konversation/Scripts/Scripting_guide/uk&oldid=201510"