Konversation/Scripts/Guide til scripting

    From KDE UserBase Wiki
    Revision as of 14:40, 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. Tilfælde: 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.

    Getting the Script to Run

    Now it's time to actually make the script run in Konversation. Here are the steps:

    • Make your script executable.

    chmod +x script_name does it all. It would be better to not include extensions (.sh, .py, .pl, etc.) in your filename, to make it easier to call the script.

    • Place the script in either one of two folders:
      • If you want your script to be available all users in your system, put the script together with the other scripts installed with Konversation. This may vary from distro to distro (or your own personal tinkering), but common a location is /usr/share/apps/konversation/scripts/. In case it's not there, get the output of the command kde4-config --install data and append /konversation/scripts/ to it. Consult your distribution's support channel if it's still not there.
      • If you want the script just for yourself, simply place the script in ~/.kde/share/apps/konversation/scripts/. Some distros might still be using ~/.kde4/ instead so adjust accordingly.
      • Post version 1.3.1 note: another way to find out where the installed scripts are is to run this command in Konversation's input line (using the media script as an example, since it comes with any Konversation installation): /exec --showpath media. Note that if there are two scripts with the same name in the user's home and in the system locations, the one in the user's home will take precedence and be the one shown here.
    • To actually run the script, you need to invoke it by running this command in Konversation's input line:

    /exec script_name [additional arguments]

    This will call your script and pass the arguments to it. Remember that your script_name is always argv[0], and that the current server and chat window are passed as argv[1] and argv[2], even if you didn't include them in your command. Therefore, any additional arguments would be argv[3] and so on.

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

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

    /mood gloomy
    

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

    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.