# Avancerade redigeringsverktyg

## Kommentera/avkommentera

Kommandona kommentera och avkommentera, som är tillgängliga i menyn Verktyg, låter dig lägga till eller ta bort kommentarmarkeringar i den markerade texten, eller den nuvarande raden, om ingen text är markerad, om kommentarer stöds av textformatet som du redigerar.

Reglerna för hur kommentarer ser ut definieras av syntaxdefinitionerna, så om syntaxfärgläggning inte används, så är det inte möjligt att kommentera eller avkommentera.

Vissa format definierar kommentarmarkeringar för enstaka rader, vissa för flera rader och vissa både ock. Om kommentarmarkeringar för flera rader inte är tillgängliga, så är det inte möjligt att kommentera en markering där den sista raden inte ingår helt och hållet.

Om det finns en kommentarmarkering för enstaka rader, så föredras kommentarer för enstaka rader när det är möjligt, eftersom detta hjälper till att undvika problem med nästlade kommentarer.

När kommentarmarkeringar tas bort, så ska inte någon okommenterad text markeras. När kommentarmarkeringar för flera rader tas bort från en markering, så ignoreras eventuella blanktecken utanför kommentarmarkeringen.

För att lägga till kommentarmarkeringar, använd menyalternativet Verktyg Kommentera eller motsvarande snabbtangent, som normalt är &Ctrl;D.

För att ta bort kommentarmarkeringar, använd menyalternativet Verktyg Avkommentera eller motsvarande snabbtangent, som normalt är &Ctrl; Skift D.

## Editorkomponentens kommandorad

&kate;s editorkomponent har en intern kommandorad, som låter dig utföra vissa åtgärder från ett minimalt grafiskt gränssnitt. Kommandoraden är ett textinmatningsfält längst ner i redigeringsområdet. För att visa den, välj Visa Byt till kommandorad eller använd snabbtangenten (normalt F7). Editorn tillhandahåller en uppsättning kommandon som är dokumenterade nedan, och ytterligare kommandon kan tillhandahållas av insticksprogram.

Skriv in kommandot och tryck på returtangenten för att utföra det. Kommandoraden anger om kommandot lyckades och visar kanske ett meddelande. Om du kom till kommandoraden genom att trycka på F7 döljs den automatiskt efter några sekunder. För att rensa meddelandet och skriva in ett nytt kommando, tryck på F7 igen.

Kommandoraden har ett inbyggt hjälpsystem, skriv in kommandot `help` för att komma igång. För att se en lista med alla tillgängliga kommandon, skriv in `help list`. För att visa hjälp om ett visst kommando, skriv `help `kommando``.

Kommandoraden har en inbyggd historik, så att du kan återanvända kommandon som redan skrivits in. För att navigera i historiken, använd tangenterna Uppåtpil och Neråtpil. När historikkommandon visas är kommandots argument markerade, vilket låter dig enkelt skriva över argumenten.

### Vanliga kommandon på kommandoraden

#### Kommandon för att anpassa editorn

Dessa kommandon tillhandahålls av editorkomponenten och låter dig bara anpassa det aktiva dokumentet och vyn. Det är praktiskt om du vill använda en inställning som skiljer sig från den förvalda inställningen, till exempel för indentering.

#### Argumenttyper

BOOLESK

- Denna används med kommandon som sätter på eller stänger av någonting. Möjliga värden är `on` (på), `off` (av), `true` (sant), `false` (falskt), `1` eller `0`.

HELTAL

- Ett heltal

STRÄNG

- En sträng

    set-tab-widthHELTAL bredd

- Ställer in tabulatorbredden till talet `bredd`

    set-indent-widthHELTAL bredd

- Ställer in indenteringsbredden till talet `bredd`. Används bara om du indenterar med mellanslag.

    set-word-wrap-columnHELTAL bredd

- Ställer in radbredden för hård radbrytning till `bredd`. Detta används om du använder automatisk radbrytning för din text.

    set-icon-borderBOOLESK aktivera

- Ställer in synligheten hos ikonkanten.

    set-folding-markersBOOLESK aktivera

- Ställer in synligheten hos vikmarkörrutan.

    set-line-numbersBOOLESK aktivera

- Ställer in synligheten hos radnummerrutan.

    set-replace-tabsBOOLESK aktivera

- Om aktiverad, ersätts tabulatortecken med mellanslag medan du skriver.

    set-remove-trailing-spaceBOOLESK aktivera

- Om aktiverad, tas avslutande blanktecken bort så fort markören lämnar en rad.

    set-show-tabsBOOLESK aktivera

- Om aktiverad, synliggörs tabulatortecken och avslutande blanktecken med en liten punkt.

    set-indent-spacesBOOLESK aktivera

- Om aktiverad, indenterar editorn med `indenteringsbredd` mellanslag för varje indenteringsnivå, istället för ett tabulatortecken.

    set-mixed-indentBOOLESK aktivera

- Om aktiverad, använder &kate; en blandning av tabulatortecken och mellanslag för indentering. Varje indenteringsnivå har bredden `indenteringsbredd`, och fler indenteringsnivåer optimeras så att så många tabulatortecken som möjligt används.

  När det utförs aktiverar kommandot dessutom indentering med mellanslag, och om indenteringsbredden inte anges ställs den in till halva `tabulatorbredden` för dokumentet.

    set-word-wrapBOOLESK aktivera

- Aktiverar dynamisk radbrytning enligt `aktivera`

    set-replace-tabs-saveBOOLESK aktivera

- Om aktiverad, ersätts tabulatortecken med blanktecken så fort dokumentet sparas.

    set-remove-trailing-space-saveBOOLESK aktivera

- Om aktiverad, tas avslutande mellanslag bort från alla rader så fort dokumentet sparas.

    set-indent-modenamn

- Ställer in automatiskt indenteringsläge till `namn`. Om `namn` inte känns igen, ställs läget in till 'none'. Giltiga lägen är 'none', 'normal', 'cstyle', 'haskell', 'lilypond', 'lisp', 'python', 'ruby' och 'xml'.

    set-highlightfärgläggning

- Ställer in dokumentets syntaxfärgläggningssystem. Argumentet måste vara ett giltigt färgläggningsnamn, som visas i menyn Verktyg Färgläggning. Kommandot tillhandahåller en lista för automatisk komplettering av dess argument.

#### Kommandon för redigering

Dessa kommandon ändrar aktuellt dokument.

    indent

- Indenterar de markerade raderna eller den nuvarande raden.

    unindent

- Avindenterar markerade rader eller nuvarande rad.

    cleanindent

- Rensar indenteringen för markerade rader eller nuvarande rad enligt dokumentets indenteringsinställningar.

    comment

- Infogar kommentarmarkeringar för att göra markeringen, markerade rader eller nuvarande rad en kommentar enligt textformatet som definieras av dokumentets syntaxfärgläggningsdefinition.

    uncomment

- Tar bort kommentarmarkeringar från markeringen, markerade rader eller nuvarande rad enligt textformatet som definieras av dokumentets syntaxfärgläggningsdefinition.

    kill-line

- Tar bort den nuvarande raden.

    replacemönsterersättning

- Ersätter text som matchar `mönster` med `ersättning`. Om du vill att `mönster` ska innehålla blanktecken, måste både `mönster` och `ersättning` placeras inom enkla eller dubbla citationstecken. Om argumenten inte är citerade, används det första ordet som `mönster` och resten som `ersättning`. Om `ersättning` är tom, tas varje förekomst av `mönster` bort.

  Du kan anpassa kommandot genom att lägga till ett kolon följt av en eller flera bokstäver som var och en representerar en inställning, genom att ange `replace:alternativ mönster ersättning`. Tillgängliga alternativ är:

  `b`

- Sök bakåt.

`c`

- Sök från markörens position.

`e`

- Sök bara i markeringen.

`r`

- Utför en sökning med ett reguljärt uttryck. Om det anges, kan du använda `\N`, där N är ett tal, för att representera hittad text i ersättningssträngen.

`s`

- Utför skiftlägeskänslig sökning.

`p`

- Fråga efter tillåtelse att ersätta nästa förekomst.

`w`

- Matcha bara hela ord.

    dateformat

- Infogar en datum- och tidssträng som definieras av angivet `format`, eller formatet yyyy-MM-dd hh:mm:ss om inget anges. Följande översättningar görs när `format` tolkas:

  `d` | Dagen som ett tal utan inledande nolla (1-31).
  `dd` | Dagen som ett tal med inledande nolla (01-31).
  `ddd` | Dagens förkortade lokala namn (t.ex. 'mån', 'sön').
  `dddd` | Dagens långa lokala namn (t.ex. 'måndag', 'söndag').
  `M` | Månaden som ett tal utan inledande nolla (1-12).
  `MM` | Månaden som ett tal med inledande nolla (01-12).
  `MMM` | Månadens förkortade lokala namn (t.ex. 'jan', 'dec').
  `yy` | Året som ett tal med två siffror (00-99).
  `yyyy` | Året som ett tal med fyra siffror (1752-8000)
  `h` | Timman utan inledande nolla (0-23 eller 1-12 om FM/EM visas).
  `hh` | Timman med inledande nolla (00-23 eller 01-12 om FM/EM visas).
  `m` | Minuten utan inledande nolla (0-59).
  `mm` | Minuten med inledande nolla (00-59).
  `s` | Sekunden utan inledande nolla (0-59).
  `ss` | Sekunden med inledande nolla (00-59).
  `z` | Millisekunden utan inledande nolla (0-999).
  `zzz` | Millisekunden med inledande nolla (000-999).
  `AP` | Använd FM/EM visning. AP ersätts antingen av "FM" eller "EM".
  `ap` | Använd fm/em visning. ap ersätts antingen av "fm" eller "em".

    charidentifierare

- Det här kommandot låter dig infoga enskilda tecken med deras numeriska kod, på decimal, oktal eller hexadecimal form. För att använda det, starta dialogrutan för redigeringskommandot och skriv `char: [nummer]` i inmatningsrutan, och tryck sedan på Ok.

  ##### Exempel på användning av `char`

  Inmatning: `char:234`

  Utmatning: `ê`

  Inmatning: `char:0x1234`

  Utmatning: `ሴ`

`s///[ig]` `%s///[ig]`

- Det här kommandot söker och ersätter på ett sätt som liknar sed, för den nuvarande raden, eller för hela filen (`%s///`).

  I kortet, så söks texten igenom efter en text som matchar sökmönstret, det reguljära uttrycket mellan det första och andra snedstrecket, och vid en träff så ersätts texten med uttrycket mellan mitten och sista delen av strängen. Parenteser i sökmönstret skapar bakåtreferenser, det vill säga kommandot kommer ihåg vilken del av texten som matchade inom parenteserna. De här strängarna kan återanvändas i ersättningsmönstret, med referenserna `\1`, för första paret parenteser, `\2` för det andra, och så vidare.

  För att söka efter tecknen `(` eller `)`, måste du undanta dem med ett bakstreckstecken `\(\)`.

  Om du lägger till `i` sist i uttrycket, blir matchningen skiftlägesokänslig. Om du lägger till `g` sist, ersätts alla förekomster av mönstret, annars ersätts bara den första förekomsten.

  ##### Ersätta text på den nuvarande raden

  Din vänliga kompilator stannade just, och talade om för dig att klassen `minKlass` som nämns på rad 3902 i din källkodsfil inte är definierad.

  "Tusan också!" tänker du. Det ska förstås vara `MinKlass`. Du går till rad 3902, och istället för att försöka hitta ordet i texten, så startar du dialogrutan för redigeringskommandot, och skriver in `s/minklass/MinKlass/i`, trycker på knappen Ok, sparar filen och kompilerar – utan problem med felet borta.

  ##### Ersätta text i hela filen

  Antag att du har en fil där du nämner namnet Anna Johansson flera gånger, och någon kommer in och talar om för dig att hon precis har gift sig och bytt namn till Anna Svensson. Du vill, förstås, byta ut alla förekomster av Anna Johansson mot Anna Svensson.

  Starta kommandoraden, och skriv in kommandot: `%s/Anna Johansson/Anna Svensson/`, tryck på returtangenten och du är klar.

  ##### Ett mer avancerat exempel

  Det här exemplet använder bakåtreferenser samt en ordklass (om du inte vet vad det är, se tillhörande dokumentation som nämns nedan).

  Antag att du har följande rad:

      void MinKlass::StrOperation( String      &x, String &y String *p, int  &a, int &b )

  Nu inser du att det inte är bra kod, och bestämmer dig för att du vill använda nyckelordet `const` för alla adress- parametrar, de som markeras med operatorn & framför argumentets namn. Du skulle också vilja förenkla blanktecknen, så att det bara finns ett blanktecken mellan varje ord.

  Starta dialogrutan för redigeringskommandot, skriv in: `s/\s+(\w+)\s+(&)/ const \1 \2/g` och tryck sedan på knappen Ok. Tecknet `g` i slutet på raden gör att det reguljära uttrycket görs om för varje träff, så att bakåtreferenserna sparas.

  Utmatning: `void MinKlass::StrOperation( const String &x, const String &y String *p, const int &a, const int &b )`

  Åtgärden utförd! Vad hände nu egentligen? Ja, vi letade efter blanktecken (`\s+`), följt av en eller flera bokstäver (`\w+`), följt av ytterligare blanktecken (`\s+`), följt av ett och-tecken, och sparade bokstäverna samt och-tecknet för att återanvända i ersättningsoperationen. Därefter ersatta vi den matchande delen av vår rad, med ett blanktecken följt av const, följt av ett blanktecken, följt av våra sparade bokstäver (`\1`), följt av vårt sparade och-tecken (`\2`)

  I vissa fall var bokstäverna String, i andra int, så att använda teckenklassen `\w` och tecknet `+` visade sig vara en värdefull tillgång.

#### Kommandon för navigering

    gotoHELTAL rad

- Det här kommandot går till den angivna raden.

    findmönster

- Kommandot går till första förekomsten av `mönster` enligt inställningen. Följande förekomster kan hittas genom att använda Redigera Sök igen (normal snabbtangent är F3).

  Kommandot kan anpassas genom att lägga till ett kolon följt av ett eller flera alternativ. Formatet är `find:alternativ mönster`. Följande alternativ stöds:

  `b`

- Sök bakåt.

`c`

- Sök från markörens position.

`e`

- Sök bara i markeringen.

`r`

- Utför en sökning med ett reguljärt uttryck. Om det anges, kan du använda `\N`, där N är ett tal, för att representera hittad text i ersättningssträngen.

`s`

- Utför skiftlägeskänslig sökning.

`w`

- Matcha bara hela ord.

    ifindmönster

- Kommandot tillhandahåller sökning medan du skriver. Du kan ställa in beteendet eller sökningen genom att lägga till ett kolon följt av ett eller flera alternativ, på detta sätt: `ifind:alternativ mönster`. Tillåtna alternativ är:

  `b`

- Sök bakåt.

`r`

- Gör en sökning med ett reguljärt uttryck.

`s`

- Utför skiftlägeskänslig sökning.

`c`

- Sök från markörens position.

## Använda kodvikning

Kodvikning låter dig dölja delar av ett dokument i editorn, vilket gör det lättare att få en överblick av stora dokument. I &kate; görs beräkningen av områden som kan fällas ihop genom att använda reglerna som anges i definitionerna av syntaxfärgläggning, och därför är det bara tillgängligt i vissa format, typiskt i programkällkod, XML-markering och liknande. De flesta definitioner av syntaxfärgläggning som stöder kodvikning låter dig också manuellt definiera områden som kan fällas ihop, typiskt genom att använda nyckelorden `BEGIN` och `END`.

För att använda kodvikningsfunktionen, aktivera vikmarkörer genom att använda menyalternativet Visa Visa vikmarkörer om de inte redan är synliga. Vikmarkörrutan till vänster på skärmen visar en grafisk vy av områden som kan fällas ihop, med triangelsymboler för att ange möjliga åtgärder för ett givet område: en triangel med spetsen neråt betyder att området är expanderat, och att klicka på den fäller ihop området så att en triangel som pekar åt höger visas istället.

Fyra kommandon tillhandahålls för att hantera tillståndet hos områden som kan fällas ihop, se menydokumentationen.

Om du inte vill använda kodvikningsfunktionen kan du inaktivera alternativet Visa vikmarkörer (om tillgängliga) på sidan Utseende i editorns inställningar.

## Utöka &kate; med skript

Sedan &kate; 3.4 i &kde; 4.4 kan &kate;s editorkomponent enkelt utökas genom att skriva skript. Skriptspråket är ECMAscript (känt överallt som Javascript). &kate; stöder två sorters skript: intenterings- och kommandoradskript.

### Indenteringsskript

Indenteringsskript, som också kallas indenterare, indenterar automatiskt källkoden medan texten skrivs in. Som ett exempel, efter att ha tryckt på returtangenten ökar ofta indenteringsnivån.

Följande avsnitt beskriver steg för steg hur skelettet för en enkel indenterare skapas. Som första steg, skapa en ny `*.js`-fil, som t.ex. heter `javascript.js` i den lokala hemkatalogen `$KDEHOME/share/apps/katepart/script`.

#### Indenteringsskriptets huvud

Huvudet i filen `javascript.js` är inbäddat i en kommentar, och har följande form

    /* kate-script
     * name: JavaScript
     * author: Exempel Namn <exempel.namn@någon.adress.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * type: indentation
     * required-syntax-style: javascript
     * indent-languages: javascript
     * priority: 0
     *
     * En rad utan kolon ':' stoppar tolkning av huvudet. Alltså kan du lägga till valfri
     * text här som en detaljerad licens.
     */

Varje post förklaras nu i detalj:

- `kate-script` [krävs]: Textsträngen måste finnas på första raden i `*.js`-filen, annars hoppar &kate; över skriptet.

- `name` [krävs]: Detta är indenterarens namn som visas i menyn Verktyg Indentering och i inställningsdialogrutan.

- `author` [valfri]: Upphovsmannens namn och kontaktinformation.

- `license` [valfri]: Kort form av licensen, såsom BSD eller LGPLv3.

- `revision` [krävs]: Skriptets utgåva. Numret ska ökas så fort skriptet ändras.

- `kate-version` [krävs]: Minimal version av &kate; som krävs.

- `type` [krävs]: Typen måste vara `indentation`, annars hoppar &kate; över skriptet.

- `required-syntax-style` [valfri]: Lista åtskild med komman av syntaxfärgläggningsstilar som krävs. Det är viktigt för indenterare som förlitar sig på specifik syntaxfärgläggningsinformation i dokumentet. Om en krävd syntaxstil specificeras, är bara indenteraren tillgänglig när lämplig syntaxfärgläggning är aktiv. Det förhindrar odefinierat beteende orsakat av att använda indenteraren utan den förväntade färgläggningsmetoden. Exempelvis använder sig Ruby-indenteraren sig av det i filen `ruby.js` och `ruby.xml`.

- `indent-languages` [valfri]: Lista åtskild med kommatecken av syntaxstilar som indenteraren kan indentera korrekt, t.ex. c++, java.

- `priority` [valfri]: Om flera indenterare är lämpliga för en viss färglagd fil, bestämmer prioriteten vilken indenterare som väljes som standardindenterare.

- `i18n-catalog` [valfri]: Ytterligare meddelandekatalog (`po`-fil) inläst för översättning av indenterare från tredjepart.

&kate; läsera alla par av formen `nyckel`: `värde` till ett kolon inte längre hittas. Det betyder att huvudet kan innehålla valfri text som en licens, vilket visas i exemplet.

#### Indenteringens källkod

Efter att ha specificerat huvudet, förklarar det här avsnittet hur själva indenteringsskriptet fungerar. Det grundläggande skelettet för implementeringen ser ut så här:

    triggerCharacters = "{}/:;";
    function indent(line, indentWidth, ch)
    {
        // anropas för varje nyrad (ch == '\n') och alla tecken angivna i
        // den globala variabeln triggerCharacters. Vid anrop av VerktygJustera
        // är variabeln ch tom, dvs. ch == ''.
        //
        // se också: Programmeringsgränssnittet för skripthantering
        return -2;
    }

Funktionen `indent()` har tre parametrar:

- `line`: raden som ska indenteras

- `indentWidth`: indenteringsbredden i antal mellanslag

- `ch`: antingen ett nyradstecken (`ch == '\n'`), avtryckartecknet angivet i `triggerCharacters` eller tom om användaren utförde åtgärden Verktyg Justera.

Returnvärdet från funktionen `indent()` anger hur raden kommer att indenteras. Om returvärdet är ett enkelt heltal, tolkas det på följande sätt:

- returvärde `-2`: gör ingenting

- returvärde `-1`: behåll indentering (söker efter föregående icke tomma rad)

- returvärde `0`: tal >= 0 anger indenteringsdjupet i mellanslag

Som alternativ kan ett fält med två element returneras.

- `return [ indent, align ];`

I detta fall är det först elementet indenteringsdjupet ovan med samma betydelse för specialvärden. Det andra elementet är dock ett absolutvärde som representerar en kolumn för justering. Om värdet är större än indenteringsvärdet, representerar skillnaden ett antal mellanslag att lägga till efter indentering av den första parametern. Annars ignoreras det andra numret. Att använda tabulator och mellanslag för indentering kallas ofta blandat läge.

Betrakta följande exempel: Antag att tabulator används för indentering, och tabulatorbredden är inställd till 4. Här representerar <tab> en tabulator, och '.' ett mellanslag.

    1: <tab><tab>anropa("Hej",
    2: <tab><tab>......."allesamman");

Vid indentering av rad 2, returnerar funktionen `indent()` [8, 15]. Som resultat infogas två tabulatorer för att indentera till kolumn 8, och 7 mellanslag läggs till för att justera den andra parametern under den första, så att den förblir justerad om filen visas med en annan tabulatorbredd.

En standardinstallation av KDE levererar &kate; med flera indenterare. Den motsvarande Javascript-koden finns i `$KDEDIR/share/apps/katepart/script`.

Att utveckla en indenterare kräver att skript läses in igen för att se om ändringar beter sig lämpligt. Istället för att starta om programmet, byt helt enkelt till kommandoraden och utför kommandot `reload-scripts`.

Om du utvecklar användbara skript, fundera på att bidra med det till &kate;-projektet genom att kontakta e-postlistan.

### Kommandoradskript

Eftersom det är svårt att uppfylla allas behov, stöder &kate; små hjälpverktyg för snabb textbehandling via den inbyggda kommandoraden. Exempelvis är kommandot `sort` implementerat som ett skript. Det här avsnittet förklarar hur man skapar `*.js`-filer för att utöka &kate; med godtyckliga hjälpskript.

Kommandoradskript är placerade i samma katalog som indenteringsskript. Som första steg, skapa alltså en ny `*.js`-fil som heter `mina_verktyg.js` i den lokala hemkatalogen `$KDEHOME/share/apps/katepart/script`.

#### Kommandoradskriptets huvud

Huvudet för varje kommandoradsskript är inbäddat i en kommentar och har följande form

    /* kate-script
     * author: Exempel Namn <exempel.namn@någon.adress.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * type: commands
     * functions: sort, format-paragraph
     *
     * En rad utan kolon ':' stoppar tolkning av huvudet. Alltså kan du lägga till valfri
     * text här som en detaljerad licens.
     */

Varje post förklaras nu i detalj:

- `kate-script` [krävs]: Textsträngen måste finnas på första raden i `*.js`-filen, annars hoppar &kate; över skriptet.

- `author` [valfri]: Upphovsmannens namn och kontaktinformation.

- `license` [valfri]: Kort form av licensen, såsom BSD eller LGPLv3.

- `revision` [krävs]: Skriptets utgåva. Numret ska ökas så fort skriptet ändras.

- `kate-version` [krävs]: Minimal version av &kate; som krävs.

- `type` [krävs]: Typen måste vara `commands`, annars hoppar &kate; över skriptet.

- `functions` [krävs]: Lista åtskild med kommatecken av kommandon i skriptet.

- `i18n-catalog` [valfri]: Ytterligare meddelandekatalog (`po`-fil) inläst för översättning av skript från tredjepart.

&kate; läsera alla par av formen `nyckel`: `värde` till ett kolon inte längre hittas. Det betyder att huvudet kan innehålla valfri text som en licens, vilket visas i exemplet. Värdet på nyckeln functions är en lista åtskild med kommatecken av kommandon för kommandoraden. Varje funktion är tillgänglig via &kate;s inbyggda kommandorad.

#### Skriptets källkod

Alla funktioner specificerade i huvudet måste implementeras i skriptet. Exempelvis måste skriptfilen i exemplet ovan implementera de två funktionerna `sort` och `format-paragraph`. Alla funktioner har följande syntax:

    function <namn>(arg1, arg2, ...)
    {
        // ... implementering, se också: Programmeringsgränssnittet för skripthantering
    }

Argument på kommandoraden skickas till funktionen som `arg1`, `arg2`, etc. För att ge dokumentation av varje kommando, implementera helt enkelt funktionen '`help`' på följande sätt:

    function help(cmd)
    {
        if (cmd == "sort") {
            return "Sortera markerad text.";
        } else if (cmd == "...") {
            // ...
        }
    }

Att utföra `help sort` på kommandoraden anropar hjälpfunktionen med argumentet `cmd` inställd till det givna kommandot, dvs. `cmd == "sort"`. &kate; visar därefter den returnerade texten som dokumentation för användaren. Försäkra dig om att översätta strängarna.

##### Tilldela genvägar

För att kunna tilldela genvägar, måste skriptet tillhandahålla en funktion som heter `action` enligt följande:

    function action(cmd)
    {
        var a = new Object();
        if (cmd == "sort") {
            a.text = i18n("Sort Selected Text");
            a.icon = "";
            a.category = "";
            a.interactive = false;
            a.shortcut = "";
        } else if (cmd == "moveLinesDown") {
            // samma för nästa åtgärd
        }
        return a;
    }

Funktionens parameter `cmd` anger kommandot som genvägen begärs för. Det finns flera fält som du måste ange i Javascript-objektet som returneras:

- `a.text` [krävs]: Texten visas i menyn Verktyg Skript. Försäkra dig om att du använder `i18n` för översättning.

- `a.icon` [valfri]: Ikonen visas intill texten i menyn. Alla KDE:s ikonnamn kan användas här.

- `a.category` [valfri]: Om en kategori anges, visas skriptet i en undermeny. Försäkra dig om att använda `i18n` för översättning.

- `a.interactive` [valfri]: If the script needs user input, set this to `true`.

- `a.shortcut` [valfri]: Genvägen som anges här är förvald genväg. Exempel: Ctrl+Alt+t. Se Qt:s dokumentation för ytterligare detaljinformation.

Att utveckla ett kommandoradskript kräver att skript läses in igen för att se om ändringar beter sig lämpligt. Istället för att starta om programmet, byt helt enkelt till kommandoraden och utför kommandot `reload-scripts`.

Om du utvecklar användbara skript, fundera på att bidra med det till &kate;-projektet genom att kontakta e-postlistan.

### Programmeringsgränssnittet för skripthantering

Programmeringsgränssnittet för skripthantering som presenteras här är tillgängligt i alla skript, dvs. indenteringsskript och kommandon för kommandoraden. Innan innehållet i ett skript läses in, lägger &kate; först till flera prototyper och funktioner till skriptets omgivning. Detta bekvämlighetsprogrammeringsgränssnitt innehåller prototyper som textmarkörer och textintervall och är placerat i katalogen `$KDEDIR/share/apps/katepart/api`. Där följer filnamnen på varje Javascript-fil följande namngivningsmodell:

    <nummer>_<namn>.js

Numret har två siffror och namnet är ett godtyckligt namn som `mina_verktyg`. &kate; styr ordningen som programmeringsgränssnittet körs via numret, dvs. filen som heter `05_cursor.js` anropas innan filen `10_range.js`. (Det liknar startordningen i systemet med runlevel/init i Linux.)

För att utöka det vanliga skriptprogrammeringsgränssnittet med egna funktioner och prototyper, skapa helt enkelt en ny fil i KDE:s lokala inställningskatalog `$KDEHOME/share/apps/katepart/api` och försäkra dig om att det har ett större nummer (senare körningsordning) än de övriga `*.js`-filerna i den globala katalogen `$KDEDIR/share/apps/katepart/api`. &kate; söker automatiskt i båda katalogerna efter `*.js`-filer och kör dem i rätt ordning.

För att utöka befintliga prototyper som `Cursor` eller `Range`, är det rekommenderade sättet inte att ändra den globala `*.js`-filen. Skapa istället en `*.js`-fil i den lokala katalogen som körs istället för `05_cursor.js` och ändra därefter prototypen för `Cursor` i Javascript.

#### Markörer och intervall

Eftersom &kate; är en texteditor är alla programmeringsgränssnitt baserade på markörer och intervall om det är möjligt. En markör (Cursor) är ett enkelt par `(rad, kolumn)`, som representerar en textposition i dokumentet. Ett intervall (Range) omfattar text från en markörs startposition till en markörs slutposition. Programmeringsgränssnittet förklaras i detalj i följande avsnitt.

##### Prototypen för Cursor

    Cursor();

- Konstruktor. Returnerar en markör på position `(0, 0)`.

  Exempel: `var cursor = new Cursor();`

    Cursor(int rad, int kolumn);

- Konstruktor. Returnerar en markör på position (rad, kolumn).

  Exempel: `var cursor = new Cursor(3, 42);`

    Cursor(Cursor annan);

- Kopieringskonstruktor. Returnerar en kopia av markören `annan`.

  Exempel: `var copy = new Cursor(other);`

    Cursor Cursor.clone();

- Returnerar en klon av markören.

  Exempel: `var clone = cursor.clone();`

    bool Cursor.isValid();

- Kontrollera om markören är giltig. Markören är ogiltig om rad och/eller kolumn har värdet `-1`.

  Exampel: `var valid = cursor.isValid();`

    Cursor Cursor.invalid();

- Returnerar en ny ogiltig markör placerad på `(-1, -1)`.

  Exempel: `var invalidCursor = cursor.invalid();`

    int Cursor.compareTo(Cursor annan);

- Jämför den här markören med markören `annan`. Returnerar

  - `-1`, om den här markören är placerad innan markören `annan`,

  - `0`, om båda markörerna är lika, och

  - `+1`, om den här markören är placerad efter markören `annan`.

    bool Cursor.equals(Cursor annan);

- Returnerar `sant` om den här markören och markören `annan` är lika, annars `falskt`.

    String Cursor.toString();

- Returnerar markören som en sträng på formen `Cursor(rad, kolumn)`.

##### Prototyp för Range

    Range();

- Konstruktor. Att anropa `new Range()` returnerar intervallet (0, 0) - (0, 0).

    Range(Cursor start, Cursor slut);

- Konstruktor. Att anropa `new Range(`start`, `slut`)` returnerar intervallet (`start`, `slut`).

    Range(int startrad, int startkolumn, int slutrad, int slutkolumn);

- Constructor. Calling `new Range(`startrad`, `startkolumn`, `slutrad`, `slutkolumn`)` returnerar intervallet från (`startrad`, `startkolumn`) to (`startrad`, `slutkolumn`).

    Range(Range annat);

- Kopieringskonstruktor. Returnerar en kopia av intervallet `annat`.

    Range Range.clone();

- Returnerar en klon av intervallet.

  Exempel: `var clone = range.clone();`

    bool Range.isValid();

- Returnerar `sant` om både start- och slutmarkörerna är giltiga, annars `falskt`.

  Exempel: `var valid = range.isValid();`

    bool Range.invalid();

- Returnerar intervallet från (-1, -1) till (-1, -1).

    bool Range.contains(Cursor markör);

- Returnerar `true` om intervallet innehåller markörpositionen, annars `false`.

    bool Range.contains(Range annat);

- Returnerar `sant` om det här intervallet innehåller intervallet `annat`, annars `falskt`.

    bool Range.containsColumn(int kolumn);

- Returnerar `sant` om `kolumn` är i det halvöppna intervallet `[startkolumn, slutkolumn)`, annars `falskt`.

    bool Range.containsLine(int rad);

- Returnerar `sant` om `rad` är i det halvöppna intervallet `[startrad, slutrad)`, annars `falskt`.

    bool Range.overlaps(Range annat);

- Returnerar `sant` om det här intervallet och intervallet `annat` delar ett gemensamt område, annars `falskt`.

    bool Range.overlapsLine(int rad);

- Returnerar `sant` om `rad` är i intervallet `[startrad, slutrad]`, annars `falskt`.

    bool Range.overlapsColumn(int kolumn);

- Returnerar `sant` om `kolumn` är i intervallet `[startkolumn, slutkolumn]`, annars `falskt`.

    bool Range.equals(Range annan);

- Returnerar `sant` om det här intervallet och intervallet `annat` är lika, annars `falskt`.

    String Range.toString();

- Returnerar intervallet som en sträng på formen `Range(Cursor(rad, kolumn), Cursor(rad, kolumn))`.

#### Globala funktioner

Det här avsnittet listar alla globala funktioner.

##### Felsökning

    void debug(String text);

- Skriver ut `text` på `standardutmatningen` i terminalen som startade programmet.

##### Översättning

För att stödja fullständig landsanpassning, finns det flera funktioner för att översätta strängar i skript, närmare bestämt `i18n`, `i18nc`, `i18np` och `i18ncp`. Funktionerna beter sig exakt likadant som KDE:s översättningsfunktioner.

Översättningsfunktionerna översätter strängarna de omger via KDE:s översättningssystem till det språk som används i programmet. Strängar i skript som utvecklas i &kate;s officiella källkod extraheras automatiskt och är översättningsbara. Med andra ord, som utvecklare av &kate; behöver man inte bry dig om att extrahera och översätta meddelanden. För skript från tredjepart som utvecklas utanför KDE, måste man dock extrahera och översätta meddelandena själv. En översättningskatalog som innehåller alla översatta strängar måste distribueras tillsammans med skriptet. Dessutom måste skriptets huvud explicit definiera katalogen som ska läsas in genom att ange `i18n-catalog`.

    void i18n(String text, arg1, ...);

- Översätter `text` till språket som används av programmet. Parametrarna `arg1`, ... , är valfria och används för att ersätta platsmarkörerna `%1`, `%2`, etc.

    void i18nc(String sammanhang, String text, arg1, ...);

- Översätter `text` till språket som används av programmet. Dessutom är strängen `sammanhang` synlig för översättare, så att de kan tillhandahålla en bättre översättning. Parametrarna `arg1`, ... , är valfria och används för att ersätta platsmarkörerna `%1`, `%2`, etc.

    void i18np(String singularis, String pluralis, int antal, arg1, ...);

- Översätter antingen `singularis` eller `pluralis` till språket som används av programmet, beroende på angivet `antal`. Parametrarna `arg1`, ... , är valfria och används för att ersätta platsmarkörerna `%1`, `%2`, etc.

    void i18ncp(String sammanhang, String singularis, String pluralis, int antal, arg1, ...);

- Översätter antingen `singularis` eller `pluralis` till språket som används av programmet, beroende på angivet `antal`. Dessutom är strängen `sammanhang` synlig för översättare, så att de kan tillhandahålla en bättre översättning. Parametrarna `arg1`, ... , är valfria och används för att ersätta platsmarkörerna `%1`, `%2`, etc.

#### Programmeringsgränssnittet för vyn

När ett skript håller på att köras, finns det en global variabel `view` som representerar den för närvarande aktiva editorvyn. Det följande är en lista med alla tillgängliga funktioner i View.

    Cursor view.cursorPosition()

- Returnerar den nuvarande markörpositionen i vyn.

    void view.setCursorPosition(int rad, int kolumn)
    void view.setCursorPosition(Cursor markör)

- Returnerar den nuvarande markörpositionen i vyn.

    void view.setCursorPosition(int rad, int kolumn);
    void view.setCursorPosition(Cursor markör);

- Ställ in den nuvarande markörpositionen till antingen (rad, kolumn) eller till den givna markören.

    Cursor view.virtualCursorPosition();

- Returnerar den virtuella markörpositionen, där varje tabulator räknas som motsvarande antal mellanslag, beroende på nuvarande tabulatorbredd.

    void view.setVirtualCursorPosition(int rad, int kolumn);
    void view.setVirtualCursorPosition(Cursor markör);

- Ställ in den nuvarande virtuella markörpositionen till (rad, kolumn) eller till den givna markören.

    String view.selectedText();

- Returnerar den markerade texten. Om ingen text är markerad, är den returnerade strängen tom.

    bool view.hasSelection();

- Returnerar `true` om vyn har markerad text, annars `false`.

    Range view.selection();

- Returnerar det markerade textintervallet. Det returnerade intervallet är ogiltigt om det inte finns någon markerad text.

    void view.setSelection(Range intervall);

- Ställer in markerad text till angivet intervall.

    void view.removeSelectedText();

- Tar bort den markerade texten. Om vyn inte har någon markerad text, händer ingenting.

    void view.selectAll();

- Markerar hela texten i dokumentet.

    void view.clearSelection();

- Rensar textmarkeringen utan att ta bort texten.

#### Programmeringsgränssnittet för dokumentet

När ett skript håller på att köras, finns det en global variabel `document` som representerar det för närvarande aktiva dokumentet. Det följande är en lista med alla tillgängliga funktioner i Document.

    String document.fileName();

- Returnerar dokumentets filnamn eller en tom sträng för osparade textbuffrar.

    String document.url();

- Returnerar dokumentets fullständiga webbadress eller en tom sträng för osparade textbuffrar.

    String document.mimeType();

- Returnerar dokumentets Mime-typ eller Mime-typen `application/octet-stream` om ingen lämplig Mime-typ kunde hittas.

    String document.encoding();

- Returnerar den nuvarande kodningen använd för att spara filen.

    String document.highlightingMode();

- Returnerar det allmänna färgläggningsläget som används för hela dokumentet.

    String document.highlightingModeAt(Cursor pos);

- Returnerar färgläggningsläget som används på den givna positionen i dokumentet.

    Array document.embeddedHighlightingModes();

- Returnerar ett fält med färgläggningslägen inbäddade i det här dokumentet.

    bool document.isModified();

- Returnerar `true` om dokumentet har osparade ändringar (är modifierat), annars `false`.

    String document.text();

- Returnerar dokumentets hela innehåll i en enda textsträng. Nya rader är markerade med nyradstecknet `\n`.

    String document.text(int från_rad, int från_kolumn, int till_rad, int till_kolumn);
    String document.text(Cursor från, Cursor till);
    String document.text(Range intervall);

- Returnerar texten i det angivna intervallet. Det rekommenderas att använda markör- och intervallbaserade versioner för bättre läsbarhet hos källkoden.

    String document.line(int rad);

- Returnerar den givna textraden som en sträng. Strängen är tom om den begärda raden är utanför tillgängligt intervall.

    String document.wordAt(int rad, int kolumn);
    String document.wordAt(Cursor markör);

- Returnerar ordet på den angivna markörposition.

    String document.charAt(int rad, int kolumn);
    String document.charAt(Cursor markör);

- Returnerar tacknet på den angivna markörpositionen.

    String document.firstChar(int rad);

- Returnerar det första tecknet på angiven `rad` som inte är ett blanktecken. Det första tecknet finns på kolumn 0. Om raden är tom, eller bara innehåller blanktecken, är den returnerade strängen tom.

    String document.lastChar(int rad);

- Returnerar det sista tecknet på angiven `rad` som inte är ett blanktecken. Om raden är tom, eller bara innehåller blanktecken, är den returnerade strängen tom.

    bool document.isSpace(int rad, int kolumn);
    bool document.isSpace(Cursor markör);

- Returnerar `sant` om tecknet på den givna markörpositionen är ett blanktecken, annars `falskt`.

    bool document.matchesAt(int rad, int kolumn, int rad, String text);
    bool document.matchesAt(Cursor markör, String text);

- Returnerar `sant` om given `text` matchar på den motsvarande markörpositionen, annars `falskt`.

    bool document.startsWith(int rad, String text, bool hoppa_över_blanktecken);

- Returnerar `sant` om raden börjar med `text`, annars `falskt`. Argumentet `hoppa_över_blanktecken` bestämmer om inledande blanktecken ignoreras.

    bool document.endsWith(int rad, String text, bool hoppa_över_blanktecken);

- Returnerar `sant` om raden slutar med `text`, annars `falskt`. Argumentet `hoppa_över_blanktecken` bestämmer om inledande blanktecken ignoreras.

    bool document.setText(String text);

- Anger hela dokumentets text.

    bool document.clear();

- Tar bort hela texten i dokumentet.

    bool document.truncate(int rad, int kolumn);
    bool document.truncate(Cursor markör);

- Avkortar den givna raden på den givna kolumnen eller markörpositionen. Returnerar `sant` om det lyckas, eller `falskt` om den givna raden inte ingår i dokumentets intervall.

    bool document.insertText(int rad, int kolumn, int rad, String text);
    bool document.insertText(Cursor markör, String text);

- Infogar `text` på den givna markörpositionen. Returnerar `sant` om det lyckas, eller `falskt` om dokumentet är skrivskyddat.

    bool document.removeText(int från_rad, int från_kolumn, int till_rad, int till_kolumn);
    bool document.removeText(Cursor från, Cursor till);
    bool document.removeText(Range intervall);

- Tar bort text i det givna intervallet. Returnerar `sant` om det lyckas, eller `falskt` om dokumentet är skrivskyddat.

    bool document.insertLine(int rad, String text);

- Infogar text på den givna raden. Returnerar `sant` om det lyckas, eller `falskt` om dokumentet är skrivskyddat eller raden inte ingår i dokumentets intervall.

    bool document.removeLine(int rad);

- Tar bort den givna textraden. Returnerar `sant` om det lyckas, eller `falskt` om dokumentet är skrivskyddat eller raden inte ingår i dokumentets intervall.

    void document.joinLines(int startrad, int slutrad);

- Sammanfogar rader från `startrad` till `slutrad`. Två på varandra följande rader åtskiljs alltid med exakt ett mellanslag.

    int document.lines();

- Returnerar antal rader i dokumentet.

    int document.length();

- Returnerar antal tecken i dokumentet.

    int document.lineLength(int rad);

- Returnerar längden på `rad`.

    void document.editBegin();

- Startar en redigeringsgrupp för gruppering av ångra/gör om. Försäkra dig om att alltid anropa `editEnd()` lika många gånger som du anropar `editBegin()`. Att anropa `editBegin()` använder en referensräknare internt, dvs. anropet kan nästlas.

    void document.editEnd();

- Avslutar en redigeringsgrupp. Det sista anropet av `editEnd()` (dvs. det för det första anropet till `editBegin()`) avslutar redigeringssteget.

    int document.firstColumn(int rad);

- Returnerar det första tecknet som inte är ett blanktecken på given `rad`. Om det bara finns blanktecken på raden, är returvärdet `-1`.

    int document.lastColumn(int rad);

- Returnerar det sista tecknet som inte är ett blanktecken på given `rad`. Om det bara finns blanktecken på raden, är returvärdet `-1`.

    int document.prevNonSpaceColumn(int rad, int kolumn);
    int document.prevNonSpaceColumn(Cursor markör);

- Returnerar kolumnen med ett tecken som inte är ett blanktecken med början på given markörposition genom att söka bakåt.

    int document.nextNonSpaceColumn(int rad, int kolumn);
    int document.nextNonSpaceColumn(Cursor markör);

- Returnerar kolumnen med ett tecken som inte är ett blanktecken med början på given markörposition genom att söka framåt.

    int document.prevNonEmptyLine(int rad);

- Returnerar nästa rad som inte är tom och som innehåller tecken som inte är blanktecken, genom att söka bakåt.

    int document.nextNonEmptyLine(int rad);

- Returnerar nästa rad som inte är tom och som innehåller tecken som inte är blanktecken, genom att söka framåt.

    bool document.isInWord(String tecken, int egenskap);

- Returnerar `sant`, om givet `tecken` med given `egenskap` kan vara en del av ett ord, annars `falskt`.

    bool document.canBreakAt(String tecken, int egenskap);

- Returnerar `sant`, om givet `tecken` med given `egenskap` är lämpat att bryta en rad, annars `falskt`.

    bool document.canComment(int startegenskap, int slutegenskap);

- Returnerar `sant` om ett intervall som börjar och slutar med den givna egenskapen är lämpat att kommenteras bort, annars `falskt`.

    String document.commentMarker(int egenskap);

- Returnerar kommentarmarkören för enraderskommentarar för en given `egenskap`.

    String document.commentStart(int egenskap);

- Returnerar kommentarmarkören för början av flerraderskommentarer för en given `egenskap`.

    String document.commentEnd(int egenskap);

- Returnerar kommentarmarkören för slutet av flerraderskommentarer för en given `egenskap`.

    int document.attribute(int rad, int kolumn);
    int document.attribute(Cursor markör);

- Returnerar egenskapen på den angivna markörpositionen.

    bool document.isAttribute(int rad, int kolumn, int egenskap);
    bool document.isAttribute(Cursor markör, int egenskap);

- Returnerar `sant` om egenskapen på den givna markörpositionen är lika med `egenskap`, annars `falskt`.

    String document.attributeName(int rad, int kolumn);
    String document.attributeName(Cursor markör);

- Returnerar egenskapsnamnet som läsbar text. Det är lika med namnet `itemData` i syntaxfärgläggningsfilerna.

    bool document.isAttributeName(int rad, int kolumn, String namn);
    bool document.isAttributeName(Cursor markör, String namn);

- Returnerar `sant` om egenskapsnamnet på en viss markörposition motsvara givet `namn`, annars `falskt`.

    String document.variable(String nyckel);

- Returnerar värdet på den begärda dokumentvariabeln `nyckel`. Om dokumentvariabeln inte finns, är returvärdet en tom sträng.

    int document.firstVirtualColumn(int rad);

- Returnerar den virtuella kolumnen för det första tecknet som inte är ett blanktecken på den givna raden, eller `-1` om raden är tom eller bara innehåller blanktecken.

    int document.lastVirtualColumn(int rad);

- Returnerar den virtuella kolumnen för det sista tecknet som inte är ett blanktecken på den givna raden, eller `-1` om raden är tom eller bara innehåller blanktecken.

    int document.toVirtualColumn(int rad, int kolumn);
    int document.toVirtualColumn(Cursor markör);
    Cursor document.toVirtualCursor(Cursor markör);

- Konverterar den givna verkliga markörpositionen till en virtuell markörposition, och returnerar antingen ett heltal eller ett markörobjekt.

    int document.fromVirtualColumn(int rad, int virtuell_kolumn);
    int document.fromVirtualColumn(Cursor virtuell_markör);
    Cursor document.fromVirtualCursor(Cursor virtuell_markör);

- Konverterar den givna virtuella markörpositionen till en verklig markörposition, och returnerar antingen ett heltal eller ett markörobjekt.

    Cursor document.anchor(int rad, int kolumn, Char tecken);
    Cursor document.anchor(Cursor markör, Char tecken);

- Söker bakåt efter det givna tecknet med början på den givna markören. Om exempelvis '(' anges som tecken, returnerar funktionen positionen på ett inledande '('. Det sker med referensräkning, dvs. andra '(...)' ignoreras.

    Cursor document.rfind(int rad, int kolumn, String text, int egenskap = -1);
    Cursor document.rfind(Cursor markör, String text, int egenskap = -1);

- Söker bakåt efter den givna texten med lämplig `egenskap`. Argumentet `egenskap` ignoreras om det anges som `-1`. Den returnerade markören är ogiltig om texten inte kunde hittas.

    int document.defStyleNum(int rad, int kolumn);
    int document.defStyleNum(Cursor markör);

- Returnerar standardstilen som används på den givna markörpositionen.

    bool document.isCode(int rad, int kolumn);
    bool document.isCode(Cursor markör);

- Returnerar `sant` om egenskapen på given markörposition inte är lika med någon av följande stilar: `dsComment`, `dsString`, `dsRegionMarker`, `dsChar`, `dsOthers`.

    bool document.isComment(int rad, int kolumn);
    bool document.isComment(Cursor markör);

- Returnerar `sant`, om egenskapen för tecknet på markörpositionen är `dsComment`, annars `falskt`.

    bool document.isString(int rad, int kolumn);
    bool document.isString(Cursor markör);

- Returnerar `sant`, om egenskapen för tecknet på markörpositionen är `dsString`, annars `falskt`.

    bool document.isRegionMarker(int rad, int kolumn);
    bool document.isRegionMarker(Cursor markör);

- Returnerar `sant`, om egenskapen för tecknet på markörpositionen är `dsRegionMarker`, annars `falskt`.

    bool document.isChar(int rad, int kolumn);
    bool document.isChar(Cursor markör);

- Returnerar `sant`, om egenskapen för tecknet på markörpositionen är `dsChar`, annars `falskt`.

    bool document.isOthers(int rad, int kolumn);
    bool document.isOthers(Cursor markör);

- Returnerar `sant`, om egenskapen för tecknet på markörpositionen är `dsOthers`, annars `falskt`.