Konversation/Scripts/Guide til scripting

    From KDE UserBase Wiki
    Revision as of 15:31, 5 August 2011 by Claus chr (talk | contribs) (Importing a new version from external source)
    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 (de)aktiverer valgmuligheder i scriptet over data til tekst, der kan vises i scriptets output. Nogle scripts har ingen ekstra argumenter som 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 eksemplscriptet 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 eksempek 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 til 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 /ir-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ørk 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.

    • For convenience, you can create a command alias in Konversation so that you can invoke your script simply using /script_name instead of the actual syntax given above. To manually do this, go to Settings -> Configure Konversation -> Command Aliases page. Click on the New button and enter "script_name" as the Alias and "/exec script_name" as the Replacement. So next time you need to run your script, you can simply do use /script_name [arguments]
    • Alternately, whenever Konversation is started, it automatically creates a command alias of "/script_name" for "/exec script_name" for every script it finds in the scripts/ directories mentioned earlier.

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

    /mood gloomy
    

    That's basically all you need to know to make a Konversation script. To make it a bit more interesting, let's have an example of another common scripting scenario.

    Case 2: Controlling an External Program from 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 bug script), or simply running a system command (and probably displaying the results of that command, as the cmd script does).

    The following script performs the first example. It first makes Yakuake visible and then runs the command supplied by the user. The script is rather simple and doesn't involve displaying anything back to the user, except in the case of an error when calling the script itself.

    #!/usr/bin/env python
    # yakrun - Konversation 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()
    

    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.