Konversation/Scripts/Guide til scripting

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.