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

From KDE UserBase Wiki
(Importing a new version from external source)
 
No edit summary
 
(61 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<languages />
<languages />


== Introduction ==
== Introduktion ==


'''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''' har indbygget understøttelse af at køre eksterne scripts, som sammen med D-Bus og '''Konversations''' egne D-Bus-metoder dækker de fleste almindelige scriptingbehov, så som visning af information i det aktuelle chatvindue eller kontrol af et andet program eller endda af '''Konversation''' selv. Denne guide er en introduktion til at skrive et script til '''Konversation'''. Den dækker kun de vigtigste begreber, som er nødvendige for at komme i gang. Sprog- og systemspecifikke nuancer er overladt som en øvelse til brugeren.


== Requirements ==
== Forudsætninger ==


All you need is a text editor and a programming/scripting language. '''Konversation''' supports any programming language that:
Alt hvad du  skal bruge for at komme i gang er en teksteditor og et programmerings- eller scriptingsporg. '''Konversation''' understøtter ethvert programmeringssprog, som


# Can accept and process command-line arguments (argv's).
# kan modtage og behandle kommandolinjeargumenter (argv'er)
# 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>.
# kan forbinde til og kalde D-Bus eller i det mindste foretage eksterne systemkald (så som at køre programmet <code>qdbus</code>). Det er nok bedst og sikrest at bruge sprogets egne bindinger til D-Bus, hvis sådanne findes i stedet for at udføre et systemkald for at køre <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.
I øjeblikket vides Python, BASH (eller Shell) og Perl at virke og have eksempler, som følger med '''Konversation''', men ethvert sprog, som opfylder de to betingelser vil kunne bruges. Denne guide vil give eksempler i Python.


== Case 1: Display Information into the Current Chat Window ==
== 1. eksempel: Vis information i det aktuelle chatvindue ==


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:
Et af de mest almindelige scriptingscenarier er nok at få noget tekst vist i '''Konversations''' aktuelle faneblad (kanal eller privat meddelelse), hvor data sædvanligvis kommer fra en ekstern kilde. Denne kilde kunne være scriptet selv, et andet program (som i scriptet <code>media</code>, der følger med '''Konversation''') eller internettet (som fx at indsamle vejrinformation og vise den i '''Konversation'''). Hvad kilden end er, så er der tre skridt, der skal udføres:


# Getting the input - catching and parsing the command sent by the user from '''Konversation'''.
# Få fat i inputtet - opfang og fortolk kommandoen, som brugeren sendte fra '''Konversation'''.
# Processing the data - gathering data from sources and manipulating it based on the input.
# Behandl data - saml information fra kilder og omform den baseret på input.
# Sending the output - throwing the information back to '''Konversation''' through D-Bus.
# Send outputtet - smid informationen tilbage til '''Konversation''' via D-Bus.


The following is a nonsensical example of a '''Konversation''' script that roughly follows that pattern.
Det følgende er et nonsenseksempel på en script til '''Konversation''', som i grove træk følger dette mønster.




Line 75: Line 75:
</syntaxhighlight>}}<!--{{-->
</syntaxhighlight>}}<!--{{-->


=== Getting the Input ===
=== Få fat i inputtet ===


When '''Konversation''' calls an external script, it runs it with some predefined arguments, like this:
Når '''Konversation''' kalder et eksternt script, så kørers det med nogle forud definerede argumenter som her:


<code>script_name server target [additional arguments ...]</code>
<code>script_navn server mål [yderligere argumenter ...]</code>


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.
Argumenterne er sædvanligvis gemt i en samling (en liste eller en tabel, afhængigt af sproget) kaldet "argv" og indekseret fra 0 til N, hvor N er antallet af argumenter.


* ''argv[0]'' is always the script name itself. In most cases, it's safe to ignore this.
* ''argv[0]'' er altid scriptets navn. I de fleste tilfælde kan det trygt ignoreres.


* ''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[1]'' er adressen på den server, som brugeren aktuelt er forbundet til. I tilfælde af, at der er forbindelse til flere servere, så vil det altid være den server, som kanal- eller forespørgselsvinduet er forbundet til.


* ''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[2]'' er målet, dvs. navnet på det chatvindue, hvor kommandoen til at køre scriptet kom fra, hvilket som regel vil være det vindue, hvor outputtet skal vises. Selvfølgelig kan du altid ændre dette.


* ''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.
* ''argv[3]'' til ''argv[N]'' vil være de ekstra argumenter, som brugeren sender ved kaldet af scriptet i '''Konversation'''. Det kan være hvad som helst fra "flag", der aktiverer eller deaktiverer valgmuligheder i scriptet over data til tekst, der kan vises i scriptets output. Nogle scripts har ingen ekstra argumenter, fx <code>uptime</code> og <code>sysinfo</code>.


{{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/da|1=Selv når dit script ikke behøver ekstra argumenter og selv når brugeren ikke angiver nogle, så vil '''Konversation''' altid sende argumenterne server og mål, hvilket betyder, at ''argv[1]'' og ''argv[2]'' altid vil være sat. Der er derfor altid mindst 3 argumenter (husk, at indekseringen starter i 0).}}


=== Processing the Data ===
=== Behandl 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.
I eksempelscriptet blev variablen ''mood'', som kommer fra brugeren i ''argv[3]'' sammenlignet med foruddefinerede værdier, og en relevant bemærkning blev tildelt variablen ''text''. Dette er et simpelt eksempel på databehandling. Du kan også hente data fra en forud defineret datakilde, som i scriptet <code>fortune</code>, eller du kan samle information fra operativsystemet, som det sker i scriptet <code>sysinfo</code>. Hvad der end måtte være af information eller tekst, som du vil have vist i '''Konversation''' laves her.


{{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/da|1=Vær omhyggelig, når du laver output med flere linjer. Den server eller kanal, som du sender til kan have en "anti-flooding"-politik. Når det handler om potentielt store tekstmængder, så er det nok bedst at få det vist på en anden måde (som i en tekseeditor).}}


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.
Nu da den nødvendige information er samlet ind og behandlet er det tid til at forberede den til at blive sendt tilbage til '''Konversation'''. Det behandler vi i næste afsnit.


=== Sending the Output ===
=== Afsendelse af 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:
At kontrollere '''Konversation''' eksternt, fx fra et script eller kommandolinjen, involverer brug af dens D-Bus-metoder. '''Konversation''' har flere af disse, herunder en gruppe, hvis formål er at vise meddelelser. At sende D-Bus-meddelelser kan være trættende. Heldigvis har Qt gjort det meget nemmere ved brug af hjælpeprogrammet <code>qdbus</code>. Uden at gå i detaljer, så vil alle de D-Bus-kommandoer, som vi sender for at få '''Konversation''' til at vise beskeder begynde med denne streng: <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:
Afhængigt af, hvilken slags besked scriptet skal sende vil yderligere tilvalg blive føjet til den kommando. Her er nogle få eksempler:
{{Input|<syntaxhighlight lang="perl">
{{Input|<syntaxhighlight lang="perl">
  qdbus org.kde.konversation /irc say server target message
  qdbus org.kde.konversation /irc say server mål besked
</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.
Det er nok den kommando, som oftest vil blive brugt. Den sender beskeder til chatvinduet "mål" forbundet til "server". Hvis du vil have meddelelsen sendt til det samme chatvindue, som scriptet blev kaldt fra, så brug ''argv[1]'' og ''argv[2]'' som henholdvis server og mål. Du kan selvfølgelig altid ændre målet til enhver anden kanal eller nick på den server.


{{Input|<syntaxhighlight lang="bash">
{{Input|<syntaxhighlight lang="bash">
  qdbus org.kde.konversation /irc error message
  qdbus org.kde.konversation /irc error besked
</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.
Dette viser beskeden i det samme chatvindue, som scriptet blev kaldt fra. Forskellen er, at beskeden ikke sendes til IRC-serveren; den vises kun til brugeren. Beskeden er formatteret således: ''"[D-Bus] Error: besked"''. Det bruges til at informere brugeren om fejl ved brugen af scriptet eller når et eller andet går galt i scriptet. Der behøves ingen server og mål.


{{Input|<syntaxhighlight lang="bash">
{{Input|<syntaxhighlight lang="bash">
  qdbus org.kde.konversation /irc sayToAll message
  qdbus org.kde.konversation /irc sayToAll besked
</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.
Sender beskeden til alle kanaler og forespørgselsvinduer i alle servere. Brug den sparsomt og vær opmærksom på ordentlig netikette. Der behøves ingen server og mål.


{{Input|<syntaxhighlight lang="bash">
{{Input|<syntaxhighlight lang="bash">
  qdbus org.kde.konversation /irc actionToAll message
  qdbus org.kde.konversation /irc actionToAll besked
</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.
En nær slægtning til sayToAlll. Sender beskeden til alle kanaler og forespørgselsvinduer i alle servere, MEN sætter "/me" foran den egentlige besked, hvilket resulterer i noget i retning af ''"*DitNick besked*"''. Igen bør du være opmærksom på netikette.


{{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/da|1=For at sende en handlingsbesked ("/me"), som kun vises i det aktuelle vindue (hvor scriptet kaldtes fra) kan du skrive den egentlige besked som "/me besked" og bruge say-varianten af kommandoen (den første i listen, hvis du for vild {{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.
Der er andre /irc-relaterede qdbus-kommandoer, hvoraf nogle ændrer brugerens status i stedet for at vise kommandoer. Leg blot med mulighederne. Der er endnu er hjælpeprogram fra Qt, <code>qdbusviewer</code>, som giver dig en grafisk brugerflade til at gennemse de tilgængelige kommandoer i '''Konversation''' og andre programmer, som kan tale med D-Bus. Du vil nok få god brug for det, især til det næste scripting-scenarie.


=== Getting the Script to Run ===
=== Få scriptet til at køre ===


Now it's time to actually make the script run in '''Konversation'''. Here are the steps:
Nu er det tid til faktisk at bruge scriptet i '''Konversation'''. Sådan gør du:


* Make your script executable.
* Gør dit script kørbart ved at skrive <code> chmod +x script_name</code> i en konsol. Det er nok bedst ikke at medtage filendelsen (.sh,, .py, .pl osv.) i dit filnavn; det gør det lettere at kalde scriptet.
<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>


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.
* Gem scriptet i en af de følgende to mapper:
* 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>
** Hvis du ønsker, at dit script skal være tilgængeligt for alle brugere på dit system, så læg scriptet sammen med de andre scripts, som blev installeret med '''Konversation'''. Stedet kan variere fra distribution til distribution (eller med dine egne  tilpasninger), men ofte er det i <tt>/usr/share/apps/konversation/scripts/</tt>. Hvis de ikke er dér, så tag outputtet fra kommandoen <code>kde4-config --install data</code> og tilføj <code>/konversation/scripts/</code> til det. Spørg på din distributions hjælpekanal, hvis du stadig ikke kan finde dem.
* 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.
** Hvis du kun skal bruge scriptet selv, kan du lægge det i <tt>~/.kde/share/apps/konversation/scripts/</tt>. Nogle distributioner bruger måske stadig ~/.kde4/ i stedet, så tilpas efter behov.
** Note til versioner efter 1.3.1: En anden måde at finde ud af, hvor de installerede scripts findes er at køre denne kommando i '''Konversations''' inputlinje: <code>/exec --showpath media</code>, hvor vi har brugt scriptet <code>media</code> som eksempel, da det leveres med '''Konversation'''. Bemærk, at hvis der findes to scripts med det samme navn i brugerens hjemmemappe og i systemmappen, så har brugerens hjemmemappe forrang og vil være den, der vises her.


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:
* For faktisk at køre scriptet skal du kalde det ved at køre denne kommando i '''Konversations''' inputlinje: <code>/exec scriptnavn [yderligere argumenter]</code>
 
Dette vil kalde dit script og overføre argumenterne til det. Husk, at navnet på dit script altid findes i ''argv[0]'' og at den aktuelle server og chatvinduet er givet i ''argv[1]'' og ''argv[2]'', selv om du ikke inkluderer dem i din kommando. Yderligere argumenter findes derfor i ''argv[3]'' og fremefter.
 
* Det kan være praktisk at lave et kommandoalias i '''Konversation''', sådan at du kan kalde scriptet ved simpelthen at skrive /script_navn i stedet for at bruge den ovenfor viste syntaks. For at gøre dette manuelt går du til <menuchoice>Indstillinger -> Indstil Konversation -> Kommandoaliaser</menuchoice>. Klik på knappen <menuchoice>Ny...</menuchoice> og skriv "script_navn" i feltet <menuchoice>Alias</menuchoice> og "/exec script_name" i feltet <menuchoice>Erstatning</menuchoice>. Næste gang du skal køre scriptet, skal du blot skrive <code>/script_navn [argumenter]</code>
 
* Alternativt laver '''Konversation''' automatisk et kommandoalias, "/script_navn", for "/exec script_navn" for hvert script, den finder i de førnævnte scriptmapper.
 
Det ovenstående script har navnet "mood" og kan kaldes med enten  <code>/mood [stemning]</code> eller <code>/exec mood [stemning]</code>, som her:


  /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.
Det er i grunden alt, hvad du skal vide for at kunne lave et script til '''Konversation'''. Lad os nu se et eksempel på et andet almindeligt scriptingscenarie for at gøre det lidt mere interessant.


== Case 2: Controlling an External Program from Konversation ==
== 2. eksempel: Kontrollér et andet program fra 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 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).
Takket være D-Bus og den kendsgerning, at mange KDE-programmer har D-Bus-metoder kan du kontrollere ethvert KDE-program fra '''Konversation'''. Selv uden D-Bus kan du lade dine scripts starte, stoppe og måske endda kontrollere andre programmer blot med en kommando i '''Konversation'''. Dette lader dig gøre mange ting, så som at sende en kommando til en terminalemulator, åben en fejlrapport i en browser ved blot at angive rapportnummeret (som scriptet <code>bug</code>) eller simpelt hen køre en kommando (og eventuelt vise resultatet af kommandoen, som scriptet <code>cmd</code> gør det).


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.
Det følgende script bringer først [[Special:mylanguage/Yakuake|Yakuake]] frem og kører så den kommando, som brugeren har givet. Scriptet er ret enkelt og involverer ikke visning af noget resultat undtagen i tilfælde af fejl ved kald af scriptet selv.


{{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 script that runs the command supplied by the user in Yakuake and toggles Yakuake's state
Line 187: Line 188:
     subprocess.Popen(toggleCommand).communicate()
     subprocess.Popen(toggleCommand).communicate()
     subprocess.Popen(runCommand).communicate()
     subprocess.Popen(runCommand).communicate()
</syntaxhighlight>}}
</syntaxhighlight>}}<!--{{-->


= Language-specific Notes =
== Sprogspecifikke noter ==


* 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.
* Vær omhyggelig med at behandle argumenter og samle dem til en enkelt streng med mellemrum. Dette kan let give anledning til fejl i nogle sprog, som fx BASH.


[[Category:Internet]]
[[Category:Internet/da]]
[[Category:Advanced Users]]
[[Category:Avancerede brugere/da]]

Latest revision as of 16:15, 5 August 2011

Other languages:

Introduktion

Konversation har indbygget understøttelse af at køre eksterne scripts, som sammen med D-Bus og Konversations egne D-Bus-metoder dækker de fleste almindelige scriptingbehov, så som visning af information i det aktuelle chatvindue eller kontrol af et andet program eller endda af Konversation selv. Denne guide er en introduktion til at skrive et script til Konversation. Den dækker kun de vigtigste begreber, som er nødvendige for at komme i gang. Sprog- og systemspecifikke nuancer er overladt som en øvelse til brugeren.

Forudsætninger

Alt hvad du skal bruge for at komme i gang er en teksteditor og et programmerings- eller scriptingsporg. Konversation understøtter ethvert programmeringssprog, som

  1. kan modtage og behandle kommandolinjeargumenter (argv'er)
  2. kan forbinde til og kalde D-Bus eller i det mindste foretage eksterne systemkald (så som at køre programmet qdbus). Det er nok bedst og sikrest at bruge sprogets egne bindinger til D-Bus, hvis sådanne findes i stedet for at udføre et systemkald for at køre qdbus.

I øjeblikket vides Python, BASH (eller Shell) og Perl at virke og have eksempler, som følger med Konversation, men ethvert sprog, som opfylder de to betingelser vil kunne bruges. Denne guide vil give eksempler i Python.

1. eksempel: Vis information i det aktuelle chatvindue

Et af de mest almindelige scriptingscenarier er nok at få noget tekst vist i Konversations aktuelle faneblad (kanal eller privat meddelelse), hvor data sædvanligvis kommer fra en ekstern kilde. Denne kilde kunne være scriptet selv, et andet program (som i scriptet media, der følger med Konversation) eller internettet (som fx at indsamle vejrinformation og vise den i Konversation). Hvad kilden end er, så er der tre skridt, der skal udføres:

  1. Få fat i inputtet - opfang og fortolk kommandoen, som brugeren sendte fra Konversation.
  2. Behandl data - saml information fra kilder og omform den baseret på input.
  3. Send outputtet - smid informationen tilbage til Konversation via D-Bus.

Det følgende er et nonsenseksempel på en script til Konversation, som i grove træk følger dette mønster.


#!/usr/bin/env python
# mood - a Konversation script to display a witty remark based on the user's mood.
# Usage: /exec mood [mood_string]

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 = "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?"

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

command.append(text)

subprocess.Popen(command).communicate()

Få fat i inputtet

Når Konversation kalder et eksternt script, så kørers det med nogle forud definerede argumenter som her:

script_navn server mål [yderligere argumenter ...]

Argumenterne er sædvanligvis gemt i en samling (en liste eller en tabel, afhængigt af sproget) kaldet "argv" og indekseret fra 0 til N, hvor N er antallet af argumenter.

  • argv[0] er altid scriptets navn. I de fleste tilfælde kan det trygt ignoreres.
  • argv[1] er adressen på den server, som brugeren aktuelt er forbundet til. I tilfælde af, at der er forbindelse til flere servere, så vil det altid være den server, som kanal- eller forespørgselsvinduet er forbundet til.
  • argv[2] er målet, dvs. navnet på det chatvindue, hvor kommandoen til at køre scriptet kom fra, hvilket som regel vil være det vindue, hvor outputtet skal vises. Selvfølgelig kan du altid ændre dette.
  • argv[3] til argv[N] vil være de ekstra argumenter, som brugeren sender ved kaldet af scriptet i Konversation. Det kan være hvad som helst fra "flag", der aktiverer eller deaktiverer valgmuligheder i scriptet over data til tekst, der kan vises i scriptets output. Nogle scripts har ingen ekstra argumenter, fx uptime og sysinfo.

Husk!

Selv når dit script ikke behøver ekstra argumenter og selv når brugeren ikke angiver nogle, så vil Konversation altid sende argumenterne server og mål, hvilket betyder, at argv[1] og argv[2] altid vil være sat. Der er derfor altid mindst 3 argumenter (husk, at indekseringen starter i 0).


Behandl data

I eksempelscriptet blev variablen mood, som kommer fra brugeren i argv[3] sammenlignet med foruddefinerede værdier, og en relevant bemærkning blev tildelt variablen text. Dette er et simpelt eksempel på databehandling. Du kan også hente data fra en forud defineret datakilde, som i scriptet fortune, eller du kan samle information fra operativsystemet, som det sker i scriptet sysinfo. Hvad der end måtte være af information eller tekst, som du vil have vist i Konversation laves her.

Advarsel

Vær omhyggelig, når du laver output med flere linjer. Den server eller kanal, som du sender til kan have en "anti-flooding"-politik. Når det handler om potentielt store tekstmængder, så er det nok bedst at få det vist på en anden måde (som i en tekseeditor).


Nu da den nødvendige information er samlet ind og behandlet er det tid til at forberede den til at blive sendt tilbage til Konversation. Det behandler vi i næste afsnit.

Afsendelse af output

At kontrollere Konversation eksternt, fx fra et script eller kommandolinjen, involverer brug af dens D-Bus-metoder. Konversation har flere af disse, herunder en gruppe, hvis formål er at vise meddelelser. At sende D-Bus-meddelelser kan være trættende. Heldigvis har Qt gjort det meget nemmere ved brug af hjælpeprogrammet qdbus. Uden at gå i detaljer, så vil alle de D-Bus-kommandoer, som vi sender for at få Konversation til at vise beskeder begynde med denne streng: qdbus org.kde.konversation /irc

Afhængigt af, hvilken slags besked scriptet skal sende vil yderligere tilvalg blive føjet til den kommando. Her er nogle få eksempler:

 qdbus org.kde.konversation /irc say server mål besked

Det er nok den kommando, som oftest vil blive brugt. Den sender beskeder til chatvinduet "mål" forbundet til "server". Hvis du vil have meddelelsen sendt til det samme chatvindue, som scriptet blev kaldt fra, så brug argv[1] og argv[2] som henholdvis server og mål. Du kan selvfølgelig altid ændre målet til enhver anden kanal eller nick på den server.

 qdbus org.kde.konversation /irc error besked

Dette viser beskeden i det samme chatvindue, som scriptet blev kaldt fra. Forskellen er, at beskeden ikke sendes til IRC-serveren; den vises kun til brugeren. Beskeden er formatteret således: "[D-Bus] Error: besked". Det bruges til at informere brugeren om fejl ved brugen af scriptet eller når et eller andet går galt i scriptet. Der behøves ingen server og mål.

 qdbus org.kde.konversation /irc sayToAll besked

Sender beskeden til alle kanaler og forespørgselsvinduer i alle servere. Brug den sparsomt og vær opmærksom på ordentlig netikette. Der behøves ingen server og mål.

 qdbus org.kde.konversation /irc actionToAll besked

En nær slægtning til sayToAlll. Sender beskeden til alle kanaler og forespørgselsvinduer i alle servere, MEN sætter "/me" foran den egentlige besked, hvilket resulterer i noget i retning af "*DitNick besked*". Igen bør du være opmærksom på netikette.

Note

For at sende en handlingsbesked ("/me"), som kun vises i det aktuelle vindue (hvor scriptet kaldtes fra) kan du skrive den egentlige besked som "/me besked" og bruge say-varianten af kommandoen (den første i listen, hvis du for vild ).


Der er andre /irc-relaterede qdbus-kommandoer, hvoraf nogle ændrer brugerens status i stedet for at vise kommandoer. Leg blot med mulighederne. Der er endnu er hjælpeprogram fra Qt, qdbusviewer, som giver dig en grafisk brugerflade til at gennemse de tilgængelige kommandoer i Konversation og andre programmer, som kan tale med D-Bus. Du vil nok få god brug for det, især til det næste scripting-scenarie.

Få scriptet til at køre

Nu er det tid til faktisk at bruge scriptet i Konversation. Sådan gør du:

  • Gør dit script kørbart ved at skrive chmod +x script_name i en konsol. Det er nok bedst ikke at medtage filendelsen (.sh,, .py, .pl osv.) i dit filnavn; det gør det lettere at kalde scriptet.
  • Gem scriptet i en af de følgende to mapper:
    • Hvis du ønsker, at dit script skal være tilgængeligt for alle brugere på dit system, så læg scriptet sammen med de andre scripts, som blev installeret med Konversation. Stedet kan variere fra distribution til distribution (eller med dine egne tilpasninger), men ofte er det i /usr/share/apps/konversation/scripts/. Hvis de ikke er dér, så tag outputtet fra kommandoen kde4-config --install data og tilføj /konversation/scripts/ til det. Spørg på din distributions hjælpekanal, hvis du stadig ikke kan finde dem.
    • Hvis du kun skal bruge scriptet selv, kan du lægge det i ~/.kde/share/apps/konversation/scripts/. Nogle distributioner bruger måske stadig ~/.kde4/ i stedet, så tilpas efter behov.
    • Note til versioner efter 1.3.1: En anden måde at finde ud af, hvor de installerede scripts findes er at køre denne kommando i Konversations inputlinje: /exec --showpath media, hvor vi har brugt scriptet media som eksempel, da det leveres med Konversation. Bemærk, at hvis der findes to scripts med det samme navn i brugerens hjemmemappe og i systemmappen, så har brugerens hjemmemappe forrang og vil være den, der vises her.
  • For faktisk at køre scriptet skal du kalde det ved at køre denne kommando i Konversations inputlinje: /exec scriptnavn [yderligere argumenter]

Dette vil kalde dit script og overføre argumenterne til det. Husk, at navnet på dit script altid findes i argv[0] og at den aktuelle server og chatvinduet er givet i argv[1] og argv[2], selv om du ikke inkluderer dem i din kommando. Yderligere argumenter findes derfor i argv[3] og fremefter.

  • Det kan være praktisk at lave et kommandoalias i Konversation, sådan at du kan kalde scriptet ved simpelthen at skrive /script_navn i stedet for at bruge den ovenfor viste syntaks. For at gøre dette manuelt går du til Indstillinger -> Indstil Konversation -> Kommandoaliaser. Klik på knappen Ny... og skriv "script_navn" i feltet Alias og "/exec script_name" i feltet Erstatning. Næste gang du skal køre scriptet, skal du blot skrive /script_navn [argumenter]
  • Alternativt laver Konversation automatisk et kommandoalias, "/script_navn", for "/exec script_navn" for hvert script, den finder i de førnævnte scriptmapper.

Det ovenstående script har navnet "mood" og kan kaldes med enten /mood [stemning] eller /exec mood [stemning], som her:

/mood gloomy

Det er i grunden alt, hvad du skal vide for at kunne lave et script til Konversation. Lad os nu se et eksempel på et andet almindeligt scriptingscenarie for at gøre det lidt mere interessant.

2. eksempel: Kontrollér et andet program fra Konversation

Takket være D-Bus og den kendsgerning, at mange KDE-programmer har D-Bus-metoder kan du kontrollere ethvert KDE-program fra Konversation. Selv uden D-Bus kan du lade dine scripts starte, stoppe og måske endda kontrollere andre programmer blot med en kommando i Konversation. Dette lader dig gøre mange ting, så som at sende en kommando til en terminalemulator, åben en fejlrapport i en browser ved blot at angive rapportnummeret (som scriptet bug) eller simpelt hen køre en kommando (og eventuelt vise resultatet af kommandoen, som scriptet cmd gør det).

Det følgende script bringer først Yakuake frem og kører så den kommando, som brugeren har givet. Scriptet er ret enkelt og involverer ikke visning af noget resultat undtagen i tilfælde af fejl ved kald af scriptet selv.

#!/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]

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 = "No command to run."

    errorCommand.append(text)

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

    runCommand.append(command)

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

Sprogspecifikke noter

  • Vær omhyggelig med at behandle argumenter og samle dem til en enkelt streng med mellemrum. Dette kan let give anledning til fejl i nogle sprog, som fx BASH.