# Strumenti avanzati di modifica

## Commenta/Decommenta

I comandi Commenta e Decommenta, disponibili nel menu Strumenti permettono di aggiungere o rimuovere indicatori di commento alla selezione, o alla riga attuale del testo se non hai selezionato niente, a patto che i commenti facciano parte del formato di testo del documento.

Le regole su come è applicato il commento sono definite in base alla sintassi del testo che stai scrivendo, quindi se non hai selezionato una modalità di evidenziazione, non potrai usare Commenta/Decommenta.

Alcuni formati usano indicatori di commento per righe singole, altri usano indicatori per più righe consecutive di commento ed altri ancora entrambi i sistemi. Se i marcatori multiriga non sono disponibili, commentare una selezione che non comprenda completamente la'ultima riga non è possibile.

Se sono disponibili i marcatori per righe singole è preferibile usarli ogni volta che è possibile, perché ciò evita i problemi dei commenti nidificati.

Quando rimuovi gli indicatori di commento devi fare attenzione a non selezionare testo che non fa parte del commento. Quando rimuovi i commenti su più righe da una selezione, gli spazi vuoti al di fuori degli indicatori di commento sono ignorati.

Per inserire gli indicatori di commento, usa il comando Strumenti Commenta oppure la relativa scorciatoria da tastiera, quella predefinita è &Ctrl;#.

Per rimuovere gli indicatori di commento, usa il comando Strumenti Decommenta oppure la relativa scorciatoia da tastiera; quella predefinita è &Ctrl;&Shift;#.

## La riga di comando per il componente dell'editor

Il componente editor di &kappname; ha una riga di comando interna che permette di effettuare varie azioni da una GUI minima. La riga di comando è una casella di testo nella parte inferiore dell'area di modifica, per mostrarla seleziona Visualizza Passa alla riga di comando o usa la scorciatoia (F7). L'editor fornisce l'insieme di comandi documentati di seguito, e comandi aggiuntivi sono forniti con le estensioni.

Per eseguire un comando, scrivilo e premi il tasto Invio. La riga di comando indicherà se ha avuto successo ed eventualmente mostrerà un messaggio. Se hai attivato la riga di comando premendo F7, verrà nascosta automaticamente dopo qualche secondo. Per pulire la riga ed inserire un nuovo comando, premi di nuovo F7.

La riga di comando ha un sistema di aiuto integrato, usa il comando `help` per iniziare. Per vedere un elenco di tutti i comandi disponibili usa `help list`, per vedere l'aiuto di un comando specifico usa `help `comando``.

La riga di comando si ricorda la cronologia dei comandi, per cui puoi riutilizzare i comandi che hai già inserito. Per scorrere la cronologia, usa i tasti Freccia su e Freccia giù. Quando vengono mostrati i comandi della cronologia, la parte degli argomenti del comando è selezionata, in modo da permetterti di sovrascrivere semplicemente gli argomenti.

### I comandi standard della riga di comando

### Tipi di argomento

BOOLEAN

- Questo tipo è usato nei comandi che devono attivare o disattivare una caratteristica. I valori ammessi sono `on`, `off`, `true`, `false`, `1` o `0`.

INTEGER

- Un numero intero.

STRING

- Una stringa, delimitata da virgolette singole (') o doppie (") se contiene spazi.

#### Comandi per la configurazione dell'editor

Questi comandi sono forniti dal componente editor e permettono di configurare solo il documento attivo e la vista. Sono utili se vuoi usare impostazioni diverse da quelle predefinite, ad esempio per i rientri.

    set-tab-widthINTEGER ampiezza

- Imposta l'ampiezza della tabulazione al numero `ampiezza`.

    set-indent-widthINTEGER ampiezza

- Imposta l'ampiezza del rientro al numero `ampiezza`. È usata solo se fai rientrare con gli spazi.

    set-word-wrap-columnINTEGER ampiezza

- Imposta l'ampiezza della riga al numero `ampiezza`. È usata se il testo deve andare a capo automaticamente.

    set-icon-borderBOOLEAN abilitazione

- Imposta la visibilità del bordo per le icone.

    set-folding-markersBOOLEAN abilitazione

- Imposta la visibilità del pannello per gli indicatori di raggruppamento.

    set-line-numbersBOOLEAN abilitazione

- Imposta la visibilità del pannello per i numeri di riga.

    set-replace-tabsBOOLEAN abilitazione

- Se è abilitata, le tabulazioni sono sostituite con spazi durante l'inserimento.

    set-remove-trailing-spaceBOOLEAN abilitazione

- Se è abilitata, gli spazi in fin di riga vengono rimossi quando il cursore lascia una riga.

    set-show-tabsBOOLEAN abilitazione

- Se è abilitata, le tabulazioni e gli spazi in fin di riga saranno evidenziati con dei puntini.

    set-show-indentBOOLEAN abilitazione

- Se è abilitata, il rientro sarà evidenziato con una linea punteggiata verticale.

    set-indent-spacesBOOLEAN abilitazione

- Se è abilitata, l'editor farà rientrare il testo di `indent-width` spazi ad ogni livello di rientro, invece che di un carattere di tabulazione.

    set-mixed-indentBOOLEAN abilitazione

- Se abilitato, &kappname; userà una miscela di tabulazioni e spazi per i rientri delle righe. Ciascun livello di rientro sarà largo `indent-width`, e più livelli di rientro saranno ottimizzati usando il maggior numero possibile di tabulazioni.

  Quando viene eseguito, questo comando inoltre abilita i rientri con gli spazi, e se l'ampiezza dei rientri non è specificata, sarà impostata alla metà di `tab-width` del documento al momento dell'esecuzione.

    set-word-wrapBOOLEAN abilitazione

- Abilita o disabilita l'a capo automatico dinamico a seconda del parametro `abilitazione`.

    set-replace-tabs-saveBOOLEAN abilitazione

- Quando è attiva questa opzione, le tabulazioni verranno sostituite con spazi durante il salvataggio del documento.

    set-remove-trailing-space-saveBOOLEAN abilitazione

- Quando è attiva questa opzione, gli spazi alla fine delle righe saranno scartati durante il salvataggio del documento.

    set-indent-modeSTRING nome

- Imposta la modalità di autorientro a `nome`. Se `nome` è sconosciuto, la modalità sarà impostata a `none`. Le modalità valide sono `none`, `normal`, `cstyle`, `haskell`, `lilypond`, `lisp`, `python`, `ruby`, e `xml`.

    set-auto-identBOOLEAN script

- Abilita o disabilita il rientro automatico.

    set-highlightSTRING evidenziazione

- Imposta il sistema di evidenziazione della sintassi per il documento. L'argomento deve essere un nome di evidenziazione valido, così come è indicato nel menu Strumenti Evidenziazione. Questo comando fornisce un elenco per il completamento automatico dell'argomento.

    reload-scripts

- Ricarica tutti gli script in JavaScript usati da &kappname;, inclusi i rientratori e gli script dalla riga di comando.

    set-modeSTRING modalità

- Scegli lo schema di tipo di file per il documento attuale.

    nn[oremap]STRINGA originale STRINGA mappata

- Mappa la sequenza di tasti `originale` nella `mappata`.

#### Comandi di modifica

Questi comandi servono a modificare il documento attuale.

    indent

- Fa rientrare le righe selezionate o la riga attuale.

    unindent

- Elimina un passo di rientro delle righe selezionate o della riga attuale.

    cleanindent

- Riordina il rientro delle righe selezionate o della riga attuale secondo le impostazioni per il rientro del documento.

    comment

- Inserisce indicatori di commento per rendere la selezione o le righe selezionate o la riga attuale un commento secondo il formato di testo così com'è definito dalle regole di evidenziazione della sintassi del documento.

    uncomment

- Rimuove gli indicatori di commento dalla selezione o dalle righe selezionate o dalla riga attuale secondo il formato di testo così com'è definito dalle regole di evidenziazione della sintassi del documento.

    kill-line

- Elimina la riga attuale.

    replaceSTRINGA modello STRINGA sostituzione

- Sostituisce il testo corrispondente a `modello` con `sostituzione`. Se vuoi includere spazi nel `modello`, devi mettere le virgolette single o doppie attorno sia al modello, sia alla sostituzione. Se gli argomenti non sono tra virgolette,la prima parola è usata come `modello` ed il resto come `sostituzione`. Se la `sostituzione` è vuota, vengono rimosse le corrispondenze con il `modello`.

  Puoi impostare dei modificatori per configurare la ricerca aggiungendo un due punti, seguiti da una o più lettere rappresentanti la configurazione, data nella forma `replace:opzioni modello sostituzione`. Le opzioni disponibili sono:

  `b`

- Cerca all'indietro.

`c`

- Cerca dalla posizione del cursore.

`e`

- Cerca solo all'interno della selezione.

`r`

- Esegue la ricerca con un'espressione regolare. Se è impostata, puoi usare `\N`, dove N è un numero che rappresenta le catture nella stringa di sostituzione.

`s`

- Esegue la ricerca facendo distinzione fra maiuscole e minuscole.

`p`

- Chiede il permesso prima di effettuare la sostituzione.

`w`

- Fa in modo che la ricerca consideri solo parole intere.

    dateSTRINGA formato

- Inserisce la stringa dell'ora/data come è specificato in `formato`, o nel formato yyyy-MM-dd hh:mm:ss se non ne è specificato nessuno. Le seguenti traduzioni sono effettuate nell'interpretazione di `formato`:

  `d` | Il giorno in forma numerica senza zeri iniziali (1–31).
  `dd` | Il giorno in forma numerica con uno zero iniziale di allineamento (01–31).
  `ddd` | Il nome del giorno abbreviato in forma locale (cioè "lun" ... "dom").
  `dddd` | Il nome del giorno completo in forma locale (cioè "lunedì" ... "domenica").
  `M` | Il mese in forma numerica senza zeri iniziali (1–12).
  `MM` | Il mese in forma numerica con uno zero iniziale se necessario (01–12).
  `MMMM` | Il nome del mese per esteso in forma locale (cioè «Gennaio» ... «Dicembre»).
  `MMM` | Il nome del mese abbreviato in forma locale (cioè «gen» ... «dic»).
  `yy` | Le ultime due cifre dell'anno (00–99).
  `yyyy` | L'anno come numero di quattro cifre (1752–8000).
  `h` | L'ora senza zero iniziali (0–23 o 1–12 se in modalità AM/PM).
  `hh` | L'ora con zero iniziali (00–23 o 01–12 se in modalità AM/PM).
  `m` | I minuti senza zero iniziali (0–59).
  `mm` | I minuti con zero iniziali (00–59).
  `s` | I secondi senza zero iniziali (0–59).
  `ss` | I secondi con zero iniziali (00–59).
  `z` | I millisecondi senza zeri iniziali (0–999).
  `zzz` | I millisecondi con zeri iniziali (000–999).
  `AP` | Usa modalità AM/PM. AP sarà sostituito da "AM" per le ore antimeridiane o "PM" per quelle pomeridiane.
  `ap` | Usa modalità am/pm. ap sarà sostituito da "am" per le ore antimeridiane o "pm" per quelle pomeridiane.

    charSTRINGA identificativo

- Questo comando permette di inserire caratteri indicando il loro identificativo numerico, in decimale, ottale o esadecimale. Per usarlo apri la finestra dei comandi di modifica e digita `char: [numero]` nel campo di inserimento, quindi fai clic su OK.

  ##### Esempi con il comando `char`

  Inserisci: `char:234`

  Ottieni: `ê`

  Inserisci: `char:0x1234`

  Ottieni: `ሴ`

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

- Questo comando fa una ricerca/sostituzione nella riga di testo corrente o in tutto il file (`%s///`) in maniera del tutto simile a sed.

  In breve, la ricerca viene effettuata in base a un modello di ricerca, a una espressione regolare compresa tra la prima e la seconda barra. Quando viene trovata una corrispondenza, la parte che corrisponde viene sostituita con l'espressione compresa tra la seconda e la terza barra. Le parentesi nel modello di ricerca creano dei riferimenti all'indietro, vale a dire che il comando ricorda quali parti della stringa di ricerca tra parentesi hanno trovato corrispondenza; queste stringhe possono essere riutilizzate per sostituire pattern riferiti a `\1` per il primo gruppo di parentesi, `\2` per il secondo e così via.

  Per cercare precisamente il simbolo di parentesi `(` o `)`, devi evitare il problema usando la barra rovescia in questo modo: `\(\)`

  Se metti una `i` alla fine dell'espressione, la corrispondenza avverrà senza tener far distinzione fra maiuscole o minuscole. Se metti una `g`, verranno sostituite tutte le corrispondenze del modello, altrimenti verrà sostituita solo la prima.

  ##### Sostituire del testo nella riga corrente

  Il tuo caro vecchio compilatore ha appena finito di bloccarsi dicendoti che la classe `myClass` che compare nella riga 3902 del tuo file sorgente non è definita.

  "Naturale!" pensi, sai benissimo che si scrive `MyClass`. Vai alla riga 3902 e, invece di provare a cercare la parola nel testo, apri la finestra dei comandi di modifica, inserisci `s/myclass/MyClass/i`, premi OK, salvi il file e lo compili – con successo senza errori.

  ##### Sostituire del testo nell'intero file

  Immagina di avere un file, nel quale nomini Miss Jensen parecchie volte e arriva qualcuno che ti dice che si è appena sposata con Mr Jones. Naturalmente tu vuoi sostituire tutti i Miss Jensen con Ms Jones.

  Vai alla riga di comando e digita il comando `%s/Miss Jensen/Ms Jones/` e premi invio. Il gioco è fatto!

  ##### Un esempio più avanzato

  Questo esempio usa i riferimenti all'indietro e le classi di carattere (se non sai che cosa sono, leggi la relativa documentazione citata più in basso).

  Immagina di avere la seguente riga:

      void MyClass::DoStringOps( String      &foo, String &bar, String *p, int  &a, int &b )

  Ora ti rendi conto che il codice non va bene e decidi di usare la parola chiave `const` per tutti gli argomenti reference, quelli caratterizzati dall'operatore & posto davanti al nome dell'argomento. Inoltre vorresti semplificare lo spazio vuoto in modo che ci sia solo uno spazio tra ogni parola.

  Apri la finestra dei comandi di modifica e inserisci: `s/\s+(\w+)\s+(&)/ const \1 \2/g` e premi il pulsante OK. La `g` che alla fine dell'espressione fa ricompilare l'espressione regolare per ogni corrispondenza per salvarne i riferimenti all'indietro.

  Ottieni: `void MyClass::DoStringOps( const String &foo, const String &bar, String *p, const int &a, const int &b )`

  Missione compiuta! Ora cos'è successo? Abbiamo cercato alcuni spazi vuoti (`\s+`) seguiti da alcuni caratteri alfabetici (`\w+`), seguiti da altri spazi vuoti (`\s+`), seguiti da una e commerciale e la porzione alfabetica con la e commerciale salvati nel processo per essere usati nell'operazione di sostituzione. Quindi abbiamo sostituito la parte corrispondente della nostra riga con uno spazio vuoto seguito da const, seguito da un altro spazio vuoto, seguito dalla porzione alfabetica (`\1`), seguito da uno spazio vuoto e infine seguito dalla e commerciale salvata (`\2`)

  Ora, in alcuni casi la porzione alfabetica era una String. in altri int, quindi se usi `\w` e il quantificatore `+` sarà meglio.

    sort

- Ordina il testo selezionato o tutto il documento.

    natsort

- Ordina le righe selezionate o tutto il documento naturalmente.

  ##### `sort` e `natsort`

  `sort(a10, a1, a2)` produce `a1, a10, a2`.

  `natsort(a10, a1, a2)` produce `a1, a2, a10`.

    moveLinesDown

- Sposta in basso le righe selezionate.

    moveLinesUp

- Sposta in alto le righe selezionate.

    uniq

- Rimuovi le righe duplicate dal testo selezionato o tutto il documento.

    rtrim

- Rimuovi gli spazi finali dal testo selezionato o tutto il documento.

    ltrim

- Rimuovi gli spazi iniziali dal testo selezionato o tutto il documento.

    joinSTRINGA separatore

- Unisce le righe selezionate o tutto il documento. A scelta, prende un parametro che definisce un separatore, per esempio ``join` ', '`.

    rmblank

- Rimuove tutti gli spazi vuoti dal testo selezionato o da tutto il documento.

    unwrap

- Unisce il testo selezionato o tutto il documento.

    eachSTRINGA script

- Data una funzione JavaScript come argomento, la chiama per l'elenco di righe selezionate e le sostituisce con il valore restituito dalla funzione.

  ##### Unire le righe selezionate

  ``each` 'function(lines){return lines.join(", ")}'`

  O più brevemente:

  ``each` 'lines.join(", ")'`

    filterSTRINGA script

- Data una funzione JavaScript come argomento, la chiama per l'elenco di righe selezionate e rimuove quelle per cui la funzione restituisce falso.

  ##### Rimuovere le righe vuote

  ``filter` 'function(1){return 1.length > 0;}'`

  O più brevemente:

  ``filter` 'line.length > 0'`

    mapSTRINGA script

- Data una funzione JavaScript come argomento, la chiama per l'elenco di righe selezionate e sostituisce la riga con il valore della funzione.

  ##### Rimuovere le righe vuote

  ``map` 'function(line){return line.replace(/^s+/,"");}'`

  O più brevemente:

  ``map` 'line.replace(/^s+/,"")'`

    duplicateLinesUp

- Duplica le righe selezionate sopra la selezione attuale.

    duplicateLinesDown

- Duplica le righe selezionate sotto la selezione attuale.

#### Comandi per gli spostamenti

    gotoINT riga

- Questo comando sposta il cursore alla riga indicata.

    grep STRINGA modello

- Cerca nel documento l'espressione regolare `modello`. Per maggiori informazioni, vedi regular-expressions.

    findSTRINGA modello

- Questo comando si sposta alla prima corrispondenza del `modello` secondo la configurazione. Le corrispondenze successive possono essere trovate usando Modifica Trova successivo (la scorciatoia predefinita è F3).

  Il comando find può essere configurato aggiungendo in fondo un due punti seguito da una o più opzioni, nella forma `find:opzioni modello`. Le seguenti opzioni sono disponibili:

  `b`

- Cerca all'indietro.

`c`

- Cerca dalla posizione del cursore.

`e`

- Cerca solo all'interno della selezione.

`r`

- Esegue la ricerca con un'espressione regolare. Se è impostata, puoi usare `\N`, dove N è un numero che rappresenta le catture nella stringa di sostituzione.

`s`

- Esegue la ricerca facendo distinzione fra maiuscole e minuscole.

`w`

- Fa in modo che la ricerca consideri solo parole intere.

    ifindSTRINGA modello

- Questo comando fornisce la ricerca mentre scrivi. Puoi configurarne il comportamento aggiungendo in fondo un due punti seguito da una o più opzioni, nella forma `ifind:opzioni modello`. Le seguenti opzioni sono disponibili:

  `b`

- Cerca all'indietro.

`r`

- Esegue la ricerca di un'espressione regolare.

`s`

- Esegue la ricerca facendo distinzione fra maiuscole e minuscole.

`c`

- Cerca dalla posizione del cursore.

#### Comandi per le funzioni fondamentali dell'editor (dipendono dall'applicazione in cui il componente editor è in uso)

    w

- Salva il documento attuale.

    wa

- Salva tutti i documenti attualmente aperti.

    q

- Chiudi il documento attuale.

    qa

- Chiudi tutti i documenti aperti.

    wq

- Salva e chiudi il documento attuale.

    wqa

- Salva e chiudi tutti i documenti attualmente aperti.

    x

- Salva e chiudi il documento attuale solo se è stato modificato.

    x

- Salva e chiudi tutti i documenti attualmente aperti solo se sono stati modificati.

    bp

- Vai al documento precedente nell'elenco dei documenti.

    bn

- Vai al documento successivo nell'elenco dei documenti.

    new

- Apri un nuovo documento nella vista separata orizzontalmente.

    vnew

- Apri un nuovo documento nella vista separata verticalmente.

    e

- Ricarica il documento attuale se è stato modificato sul disco.

    enew

- Modifica un nuovo documento.

    print

- Apri la finestra di stampa per stampare il documento attuale.

## Uso del raggruppamento del codice

Il raggruppamento del codice permette di nascondere parti del documento nell'editor, rendendo più facile una panoramica di documenti di grandi dimensioni. In &kappname; le regioni raggruppabili sono classificate usando le regole delle definizioni dell'evidenziazione della sintassi, e quindi sono disponibili solo in alcuni formati — tipicamente codice sorgente, annotazioni XML e simili. La maggior parte delle definizioni di evidenziazione che permettono il raggruppamento del codice permettono anche la definizione manuale di regioni raggruppabili, tipicamente con l'uso delle parole chiave `BEGIN` ed `END`.

Per usare la funzione di raggruppamento del codice, attiva gli indicatori di raggruppamento usando la voce Visualizza Mostra segni di raggruppamento del menu se non sono già visibili. Il pannello degli indicatori di raggruppamento sul lato sinistro dello schermo mostra una vista grafica delle regioni raggruppabili, con simbolo di un triangolo indicante l'operazione possibile su una data regione: Un triangolo capovolto indica che la regione è espansa, facendo clic su di esso si ridurrà la regione ad una sola riga e successivamente verrà mostrato come simbolo un triangolo diritto.

Sono forniti undici comandi per manipolare lo stato delle regioni di raggruppamento del codice, vedi la documentazione del menu.

Le righe raggruppate vengono ricordate alla chiusura del file, così quando lo riapri i nodi raggruppati lo saranno ancora. Questo vale anche per le operazioni di ricarica.

Se non vuoi usare la funzione di raggruppamento del codice, puoi disabilitare l'opzione Mostra segni di raggruppamento (se disponibile) dalla pagina Aspetto dalla pagina di configurazione dell'editor.

## Estensione di &kappname; con script

Da &kappname; 3.4 in KDE 4.4 il componente editor di &kappname; è facilmente estendibile attraverso degli script. Il linguaggio di scipt è ECMAScript (comunemente noto come JavaScript). &kappname; supporta due tipi di script: rientro e riga di comando.

### Script di rientro

Gli script di rientro, noti anche come rientratori, fanno rientrare automaticamente il codice sorgente mentre si scrive. Per esempio, spesso il livello di rientro aumenta dopo aver premuto &Enter;.

Le sezioni seguenti descrivono passo-passo come creare la struttura di un semplice rientratore. Come primo passo, crea un nuovo file `.js`, per esempio `javascript.js` nella cartella Home locale `$`KDEHOME`/share/apps/katepart/script/indentation`.

#### L'intestazione dello script di rientro

L'intestazione del file `javascript.js` è incorporata in un commento e ha la forma seguente:

    /* kate-script
     * name: JavaScript
     * author: Pippo <pippo@topolinia.it>
     * license: GPL
     * revision: 1
     * kate-version: 3.4
     * required-syntax-style: javascript
     * indent-languages: javascript
     * priority: 0
     * i18n-catalog: mycatalog
     *
     * Una riga senza due punti «:» interrompe l'analisi dell'intestazione.
     * Puoi quindi aggiungere del testo qui, come il testo di una licenza.
     */

Ogni voce viene ora spiegata in dettaglio:

- `kate-script` [obbligatorio]: questa stringa di testo deve essere nella prima riga del file `.js`, altrimenti &kappname; salterà lo script.

- `name` [obbligatorio]: questo è il nome del rientratore che appare nel menu Strumenti Rientro e nella finestra di configurazione.

- `author` [facoltativo]: il nome dell'autore e informazioni per contattarlo.

- `license` [facoltativo]: forma breve della licenza, come BSD o LGPLv3.

- `revision` [obbligatorio]: la revisione dello script. Questo numero va aumentato a ogni sua modifica.

- `kate-version` [obbligatorio]: versione minima di &kappname; richiesta.

- `required-syntax-style` [facoltativo]: elenco separato da virgole di stili richiesti di evidenziazione della sintassi. È importante per i rientratori che richiedono informazioni di evidenziazione specifiche nel documento. Se uno stile di sintassi richiesto viene specificato, il rientratore è disponibile solo quando è attivo l'evidenziatore appropriato. Ciò impedisce il comportamento non definito causato dall'uso del rientratore senza lo schema di evidenziazione atteso. Per esempio, il rientratore di Ruby lo usa nei file `ruby.js` e `ruby.xml`.

- `indent-languages` [facoltativo]: elenco separato da virgole di stili di sintassi che il rientratore può far rientrare correttamente, per esempio: `c++, java`.

- `priority` [facoltativo]: se ci sono più rientratori che si adattano a un certo file evidenziato, la priorità decide quale viene scelto come predefinito.

- `i18n-catalog` [facoltativo]: catalogo di messaggi aggiuntivo (file `po`) caricato per la traduzione di rientratori di parti terze.

&kappname; legge tutte le coppie nella forma `chiave`:`valore` finché non trova più virgole. Ciò vuol dire che l'intestazione può contenere del testo a piacere, come una licenza, come mostrato nell'esempio.

#### Il codice sorgente del rientratore

Dopo aver specificato l'intestazione, questa sezione spiega come funziona lo script di rientro vero e proprio. La struttura fondamentale ha questo aspetto:

    // librerie katepart js necessarie, per esempio range.js se usi Range
    require ("range.js");

    triggerCharacters = "{}/:;";
    function indent(riga, larghezza_rientro, carattere)
    {
        // richiamato a ogni ritorno a capo (carattere == '\n') e per tutti i caratteri
        // specificati nella in variabile globale triggerCharacters. Quando si chiama
        // StrumentiAllinea, la variabile carattere è vuota, cioè caratteri == ''.
        //
        // Vedi anche: API di scripting
        return -2;
    }

La funzione `indent()` ha tre argomenti:

- `riga`: la riga da far rientrare;

- `larghezza_rientro`: la larghezza del rientro espressa come numero di spazi;

- `carattere`: un carattere di ritorno a capo (`carattere` == '\n'), un carattere di attivazione specificato in `triggerCharacters`, o vuota se l'utente ha attivato l'azione Strumenti Allinea.

Il valore restituito dalla funzione `indent()` specifica come far rientrare la riga. Se il valore è un semplice numero intero, viene interpretato come segue:

- Valore restituito -2: non fare nulla;

- Valore restituito -1: mantieni il rientro (cerca una riga non vuota precedente)

- Valore restituito 0: I numeri numbers ≥ 0 specificano il rientro in spazi

In alternativa, si può restituire un array di due elementi:

- `return [ indent, align ];`

In questo caso, il primo elemento è il rientro, con lo stesso significato di cui sopra. Il secondo elemento, invece, è un valore assoluto che rappresenta una colonna di allineamento. Se questo valore è maggiore del valore di rientro, la differenza rappresenta un numero di spazi da aggiungere dopo il rientro della prima variabile. Altrimenti, il secondo numero viene ignorato. Usare sia tabulatori che spazi per il rientro viene spesso indicato come modalità mista.

Considera il seguente esempio: supponiamo di usare le tabulazioni per il rientro, e la loro ampiezza è impostata a 4. Qui, <tab> indica una tabulazione e . uno spazio:

    1: <tab><tab>pippo("ciao",
    2: <tab><tab>......"mondo");

Quando si allinea la seconda riga, la funzione `indent()` restituisce [8, 15]. Perciò, si inseriscono due tabulazioni per far rientrare fino alla colonna 8, e vengono aggiunti sette spazi per allineare il secondo argomento al primo, in modo che rimanga allineato se il file viene visualizzato con un'ampiezza di tabulazione diversa.

Un'installazione predefinita di &kde; include &kappname; con diversi rientratori. Il codice JavaScript corrispondente si può trovare in `$`KDEDIR`/share/apps/katepart/script/indentation`.

Sviluppare un rientratore richiede ricaricare gli script per vedere se le modifiche funzionano correttamente. Invece di riavviare l'applicazione, basta passare alla riga di comando e digitare il comando `reload-scripts`.

Se sviluppi degli script utili, per piacere considera la possibilità di contribuirli al progetto &kappname; contattando la lista di distribuzione.

### Script dalla riga di comando

Essendo difficile soddisfare le necessità di tutti, &kappname; supporta dei piccoli strumenti di supporto per manipolare velocemente il testo attraverso la riga di comando integrata. Per esempio, il comando `sort` è implementato come uno script. Questa sezione spiega come creare file `*.js` per estendere &kappname; con script di supporto a piacere.

Gli script dalla riga di comando si trovano nella stessa cartella degli script di rientro. Come primo passo, crea un nuovo file `*.js` nella cartella Home locale `$`KDEHOME`/share/apps/katepart/script/commands`.

#### L'intestazione dello script da riga di comando

L'intestazione di ogni script da riga di comando è incorporata in un commento ed ha la forma seguente:

    /* kate-script
     * author: Pippo <pippo@topolinia.it>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * functions: sort, format-paragraph
     * i18n-catalog: mycatalog
     *
     * Una riga senza due punti «:» interrompe l'analisi dell'intestazione.
     * Puoi quindi aggiungere del testo qui, come il testo di una licenza.
     */

Ogni voce verrà ora spiegata in dettaglio:

- `kate-script` [obbligatorio]: questa stringa di testo deve essere nella prima riga del file `.js`, altrimenti &kappname; salterà lo script.

- `author` [facoltativo]: il nome dell'autore e informazioni per contattarlo.

- `license` [facoltativo]: forma breve della licenza, come BSD o LGPLv3.

- `revision` [obbligatorio]: la revisione dello script. Questo numero va aumentato a ogni sua modifica.

- `kate-version` [obbligatorio]: versione minima di &kappname; richiesta.

- `functions` [obbligatorio]: elenco separato da virgole dei comandi nello script.

- `i18n-catalog` [facoltativo]: catalogo di messaggi aggiuntivo (file `po`) caricato per la traduzione di script di parti terze.

&kappname; legge tutte le coppie nella forma `chiave`:`valore` finché non riesce a trovare più un carattere di due punti. Ciò vuol dire che l'intestazione può contenere caratteri a piacere, come nell'esempio una licenza. Il valore della chiave `functions` è un elenco separato da virgole di comandi da riga di comando. Ciò vuol dire che un solo script contiene un numero a piacere di questi comandi. Ogni funzione è disponibile attraverso la riga di comando incorporata di &kappname;.

#### Il codice sorgente dello script

Tutte le funzioni specificate nell'intestazione vanno implementate nello script. Lo script nell'esempio sopra deve implementare le due funzioni `sort` e `format-paragraph`. Tutte le funzioni hanno la sintassi seguente:

    // librerie katepart js necessarie, per esempio range.js se usi Range
    require ("range.js");

    function <nome>(argomento_1, argomento_2, ...)
    {
        // ... implementazione, vedi anche: API per gli script
    }

Gli argomenti nella riga di comando vengono passati alla funzione come `argomento_1`, `argomento_2`, eccetera. Per poter documentare ogni comando, basta implementare la funzione `help` come segue:

    function help(comando)
    {
        if (comando == "sort") {
            return i18n("Ordina il testo selezionato.");
        } else if (comando == "...") {
            // ...
        }
    }

Eseguire quindi `help sort` nella riga di comando chiamerà questa funzione ausiliaria con l'argomento `comando` impostato al comando dato, per esempio `comando == "sort"`. &kappname; presenterà quindi il testo risultante come documentazione per l'utente. Assicurati di tradurre le stringhe.

##### Stabilire le scorciatoie

Per poter assegnare delle scorciatoie, lo script deve fornire una funzione chiamata `action` come la seguente:

    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") {
            // stessa cosa per la prossima azione
        }
        return a;
    }

Il parametro `cmd` della funzione specifica il comando per cui si richiede una scorciatoia. Ci sono diversi campi che vanno specificati nell'oggetto JavaScript restituito:

- `a.name` [obbligatorio]: il testo che compare nel menu Strumenti Script. Assicurati di usare `i18n` per le traduzioni dall'inglese.

- `a.icon` [facoltativo]: l'icona che appare di fianco al testo nel menu. Qui si possono usare tutti i nomi delle icone di &kde;.

- `a.category` [facoltativo]: se si specifica una categoria, lo script compare in un sottomenu. Assicurati di usare `i18n` per le traduzioni dall'inglese.

- `a.interactive` [facoltativo]: se allo script serve che l'utente faccia qualcosa, impostalo a `true`.

- `a.shortcut` [facoltativo]: la scorciatoia qui data è la predefinita, per esempio &Ctrl;&Alt;T. Vedi la documentazione di &Qt; per maggiori dettagli.

Sviluppare uno script da riga di comando richiede di ricaricarlo per vedere se le modifiche si funzionano correttamente. Invece di riavviare l'applicazione, basta passare alla riga di comando e lanciare il comando `reload-scripts`.

Se sviluppi degli script utili, per piacere considera la possibilità di contribuirli al progetto &kappname; contattando la lista di distribuzione.

### API per gli script

L'API per script qui presentata è disponibile in tutti gli script, cioè gli script di rientro e i comandi da riga di comando. Le classi `Cursor` e `Range` sono fornite dalle librerie presenti in `$`KDEDIR`/share/apps/katepart/libraries`. Se le vuoi usare nel tuo script, il che è necessario per usare alcune delle funzioni di `Document` o `View`, includi la libreria necessaria con:

    // librerie katepart js necessarie, per esempio range.js se usi Range
    require ("range.js");

Per estendere l'API standard per gli script con funzioni e prototipi propri, basta creare un nuovo file nella cartella di configurazione locale di &kde; `$`KDEHOME`/share/apps/katepart/libraries`, includerlo nel tuo script con:

    require ("nome_del_mio_script.js");

Per estendere i prototipi preesistenti, come `Cursor` o `Range`, il modo raccomandato di procedere non è di modificare i file `*.js` globali. Cambia piuttosto il prototipo `Cursor` in JavaScript dopo aver incluso `cursor.js` nello script con `require`.

#### Cursori e intervalli

Essendo &kappname; un editor di testo, tutta l'API per gli script si basa su cursori e intervalli ovunque sia possibile. Un cursore (`Cursor`) è una semplice tupla del tipo `(riga, colonna)` che rappresenta una posizione nel testo del documento. Un intervallo (`Range`) si estende sul testo a partire da una posizione di partenza a una finale del cursore. L'API viene spiegata in dettaglio nelle sezioni seguenti.

##### Il prototipo dei cursori

    Cursor();

- Costruttore. Restituisce un cursore alla posizione `(0, 0)`.

  Esempio: `var cursore = new Cursor();`

    Cursor(int riga, int colonna);

- Costruttore. Restituisce un cursore alla posizione `(riga, colonna)`.

  Esempio: `var cursore = new Cursor(3, 42);`

    Cursor(Cursor altro);

- Costruttore di copia. Restituisce una copia dell'`altro` cursore.

  Esempio: `var copia = new Cursor(altro);`

    Cursor Cursor.clone();

- Restituisce un clone del cursore.

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

    bool Cursor.isValid();

- Controlla se il cursore è valido. Non lo è se la riga o la colonna sono impostate a `-1`.

  Esempio: `var valido = cursor.isValid();`

    Cursor Cursor.invalid();

- Restituisce un nuovo cursore non valido posizionato a `(-1, -1)`.

  Esempio: `var cursoreNonValido = cursor.invalid();`

    int Cursor.compareTo(Cursor altro);

- Confronta un cursore con un `altro`. Restituisce:

  - `-1`, se il cursore è posizionato prima dell'`altro`,

  - `0`, se sono uguali, e

  - `+1`, se il cursore è posizionato dopo l'`altro`.

    bool Cursor.equals(Cursor altro);

- Restituisce `true` se il cursore e l'`altro` sono uguali, altrimenti `false`.

    String Cursor.toString();

- Restituisce un cursore sotto forma di stringa nella forma `Cursor(riga, colonna)`.

##### Il prototipo degli intervalli

    Range();

- Costruttore. Chiamare `new Range()` restituisce un intervallo tra `(0, 0)` e `(0, 0)`.

    Range(Cursor inizio, Cursor fine);

- Costruttore. Chiamare `new Range(`inizio`, `fine`)` restituisce l'intervallo (`inizio`, `fine`).

    Range(int riga_inizio, int colonna_inizio, int riga_fine, int colonna_fine);

- Costruttore. Chiamare `new Range(`riga_inizio`, `colonna_inizio`, `riga_fine`, `colonna_fine`)` restituisce l'intervallo da (`riga_inizio`, `colonna_inizio`) a (`riga_fine`, `colonna_fine`).

    Range(Range altro);

- Costruttore di copia. Restituisce una copia dell'`altro` intervallo.

    Range Range.clone();

- Restituisce un clone dell'intervallo.

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

    bool Range.isValid();

- Restituisce `true` se entrambi i cursori iniziale e finale sono validi, altrimenti `false`.

  Esempio: `var valido = range.isValid();`

    bool Range.invalid();

- Restituisce l'intervallo da `(-1, -1)` a `(-1, -1)`.

    bool Range.contains(Cursor cursore);

- Restituisce `true` se l'intervallo contiene la posizione del `cursore`, altrimenti `false`.

    bool Range.contains(Range altro);

- Restituisce `true` se l'intervallo contiene l'`altro`, altrimenti `false`.

    bool Range.containsColumn(int colonna);

- Restituisce `true` se la `colonna` è nell'intervallo semiaperto `[inizio.colonna, fine.colonna)`, altrimenti `false`.

    bool Range.containsLine(int riga);

- Restituisce `true` se la `riga` è nell'intervallo semiaperto `[inizio.riga, fine.riga)`, altrimenti `false`.

    bool Range.overlaps(Range altro);

- Restituisce `true` se l'intervallo e l'`altro` hanno una regione in comune, altrimenti `false`.

    bool Range.overlapsLine(int riga);

- Restituisce `true` se la `riga` è nell'intervallo `[inizio.riga, fine.riga]`, altrimenti `false`.

    bool Range.overlapsColumn(int colonna);

- Restituisce `true` se la `colonna` è nell'intervallo `[inizio.colonna, fine.colonna]`, altrimenti `false`.

    bool Range.onSingleLine();

- Restituisce `true` se l'intervallo comincia e finisce sulla stessa riga, cioè se `Range.start.line == Range.end.line`.

  Da: KDE 4.9

    bool Range.equals(Range altro);

- Restituisce `true` se l'intervallo e l'`altro` sono uguali, altrimenti `false`.

    String Range.toString();

- Restituisce un intervallo sotto forma di stringa nella forma `Range(Cursor(riga, colonna), Cursor(riga, colonna))`.

#### Funzioni globali

Questa sezione elenca tutte le funzioni globali.

##### Leggere e includere file

    String read(String file);

- Cercherà nel `file` dato, relativamente alla cartella `katepart/script/files`, e ne restituirà i contenuti in forma di stringa.

    void require(String file);

- Cercherà nel `file` dato, relativamente alla cartella `katepart/script/libraries`, e lo valuterà. `require` è già programmato per evitare inclusioni multiple dello stesso `file`.

  Da: KDE 4.10

##### Debug

    void debug(String testo);

- Stampa il `testo` su `stdout` nella console che ha avviato l'applicazione.

##### Traduzione

Per supportare una localizzazione completa, ci sono diverse funzioni per tradurre le stringhe negli script, cioè `i18n`, `i18nc`, `i18np` e `i18ncp`. Queste funzioni si comportano esattamente come le funzioni di traduzione di &kde;.

Le funzioni traducono le stringhe incluse con il sistema di traduzione di &kde; nella lingua usata nell'applicazione. Le stringhe negli script sviluppati nel codice sorgente ufficiale di &kappname; sono automaticamente estratte e traducibili: gli sviluppatori di &kappname; non devono preoccuparsi di estrarre e tradurre i messaggi. Tuttavia, nel caso di script di terze parti sviluppati al di fuori di &kde;, i messaggi vanno estratti e tradotti a parte. Assieme ai tuoi script dovrai quindi distribuire un catalogo di traduzioni che includa tutte le stringhe tradotte. Inoltre, l'intestazione dello script dovrà specificare esplicitamente il catalogo da caricare indicandolo con `i18n-catalog`.

    void i18n(String testo, argomento_1, ... );

- Traduce `testo` nella lingua usata dall'applicazione. Gli argomenti `argomento_1` e seguenti sono facoltativi e vengono usati per sostituire i segnaposti `%1`, `%2`, e così via.

    void i18nc(String contesto, String testo, argomento_1, ... );

- Traduce `testo` nella lingua usata dall'applicazione. Inoltre, la stringa `contesto` viene resa visibile ai traduttori per chiarire eventuali equivoci e produrre una traduzione migliore. Gli argomenti `argomento_1` e seguenti sono facoltativi e vengono usati per sostituire i segnaposti `%1`, `%2`, e così via.

    void i18np(String singolare, String plurale, int numero, argomento_1, ... );

- Traduce `singolare` o `plurale` nella lingua usata dall'applicazione, a seconda del `numero` dato. Gli argomenti `argomento_1` e seguenti sono facoltativi e vengono usati per sostituire i segnaposti `%1`, `%2`, e così via.

    void i18ncp(String contesto, String singolare, String plurale, int numero, argomento_1, ... );

- Traduce `singolare` o `plurale` nella lingua usata dall'applicazione, a seconda del `numero` dato. Inoltre, la stringa `contesto` viene resa visibile ai traduttori per chiarire eventuali equivoci e produrre una traduzione migliore. Gli argomenti `argomento_1` e seguenti sono facoltativi e vengono usati per sostituire i segnaposti `%1`, `%2`, e così via.

#### L'API delle viste

Ogni volta che uno script viene eseguito è presente una variabile globale, `view`, che rappresenta la vista attiva dell'editor. Segue un elenco di tutte le funzioni di vista disponibili.

    Cursor view.cursorPosition()

- Restituisce la posizione attuale del cursore nella vista.

    void view.setCursorPosition(int riga, int colonna);
    void view.setCursorPosition(Cursor cursore);

- Imposta la posizione attuale del cursore a `(`riga`, `colonna`)` o al `cursore` dato.

    Cursor view.virtualCursorPosition();

- Restituisce la posizione virtuale del cursore con ogni tabulazione che conta una quantità di spazi dipendente dall'attuale ampiezza di tabulazione.

    void view.setVirtualCursorPosition(int riga, int colonna);
    void view.setVirtualCursorPosition(Cursor cursore);

- Imposta la posizione virtuale attuale del cursore a `(`riga`, `colonna`)` o al `cursore` dato.

    String view.selectedText();

- Restituisce il testo selezionato. Se non c'è del testo selezionato, la stringa restituita è vuota.

    bool view.hasSelection();

- Restituisce `true` se la vista contiene del testo selezionato, altrimenti `false`.

    Range view.selection();

- Restituisce l'intervallo di testo selezionato. L'intervallo di testo non è valido se non c'è testo selezionato.

    void view.setSelection(Range intervallo);

- Imposta il testo selezionato all'`intervallo` dato.

    void view.removeSelectedText();

- Rimuovi il testo selezionato. Se la vista non ne ha, non fa nulla.

    void view.selectAll();

- Seleziona tutto il testo del documento.

    void view.clearSelection();

- Pulisce la selezione di testo senza rimuoverlo.

#### L'API dei documenti

Ogni volta che uno script viene eseguito è presente una variabile globale, `document`, che rappresenta il documento attivo. Segue un elenco di tutte le funzioni del documento disponibili.

    String document.fileName();

- Restituisce il nome del file del documento o una stringa vuota per i documenti non salvati.

    String document.url();

- Restituisce l'URL completo del documento, o una stringa vuota per i documenti non salvati.

    String document.mimeType();

- Restituisce il tipo di file del documento, o il tipo di file `application/octet-stream` se non se ne può trovare uno appropriato.

    String document.encoding();

- Restituisce la codifica attualmente usata per salvare il file.

    String document.highlightingMode();

- Restituisce la modalità di evidenziazione globale usata per tutto il documento.

    String document.highlightingModeAt(Cursor posizione);

- Restituisce la modalità di evidenziazione usata alla `posizione` nel documento.

    Array document.embeddedHighlightingModes();

- Restituisce un array di modalità di evidenziazione incorporate in questo documento.

    bool document.isModified();

- Restituisce `true` se il documento ha modifiche non salvate, altrimenti `false`.

    String document.text();

- Restituisce tutto il contenuto del documento in una sola stringa di testo. I ritorni a capo sono indicati con il carattere `\n`.

    String document.text(int da_riga, int da_colonna, int a_riga, int a_colonna);
    String document.text(Cursor da, Cursor a);
    String document.text(Range intervallo);

- Restituisce il testo nell'intervallo dato. Si raccomanda di usare le versioni con cursori o intervalli per migliorare la leggibilità del codice.

    String document.line(int riga);

- Restituisce la riga di testo richiesta come stringa. La stringa è vuota se la riga richiesta è oltre i limiti.

    String document.wordAt(int riga, int colonna);
    String document.wordAt(Cursor cursore);

- Restituisce la parola alla posizione del cursore data.

    Range document.wordRangeAt(int riga, int colonna);
    Range document.wordRangeAt(Cursor cursore);

- Restituisce l'intervallo di una parola alla posizione del cursore data. L'intervallo restituito non è valido (vedi Range.isValid()) se la posizione è oltre la fine di una riga. Se non c'è una parola alla fine del cursore, viene restituito un intervallo vuoto.

  Da: KDE 4.9

    String document.charAt(int riga, int colonna);
    String document.charAt(Cursor cursore);

- Restituisce il carattere alla posizione del cursore data.

    String document.firstChar(int riga);

- Restituisce il primo carattere nella `riga` data che non sia uno spazio. Il primo carattere è alla colonna 0. Se la riga è vuota o contiene solo spazi, la stringa restituita è vuota.

    String document.lastChar(int riga);

- Restituisce l'ultimo carattere nella `riga` data che non sia uno spazio. Se la riga è vuota o contiene solo spazi, la stringa restituita è vuota.

    bool document.isSpace(int riga, int colonna);
    bool document.isSpace(Cursor cursore);

- Restituisce `true` se il carattere alla posizione del cursore data è uno spazio, altrimenti `false`.

    bool document.matchesAt(int riga, int colonna, String testo);
    bool document.matchesAt(Cursor cursore, String testo);

- Restituisce `true` se il `testo` corrisponde a quello presente alla posizione del cursore, altrimenti `false`.

    bool document.startsWith(int riga, String testo, bool salta_spazi);

- Restituisce `true` se la riga comincia con il `testo`, altrimenti `false`. L'argomento `salta_spazi` decide se gli spazi iniziali vanno ignorati.

    bool document.endsWith(int riga, String testo, bool salta_spazi);

- Restituisce `true` se la riga finisce con il `testo`, altrimenti `false`. L'argomento `salta_spazi` decide se gli spazi finali vanno ignorati.

    bool document.setText(String testo);

- Imposta tutto il testo del documento.

    bool document.clear();

- Rimuove tutto il testo del documento.

    bool document.truncate(int riga, int colonna);
    bool document.truncate(Cursor cursore);

- Tronca la `riga` alla `colonna`. Restituisce `true` se funziona, o `false` se la `riga` non fa parte dell'intervallo del documento.

    bool document.insertText(int riga, int colonna, String testo);
    bool document.insertText(Cursor cursore, String testo);

- Inserisce il `testo` alla posizione del cursore data. Restituisce `true` se funziona, o `false` se il documento è in modalità a sola lettura.

    bool document.removeText(int da_riga, int da_colonna, int a_riga, int a_colonna);
    bool document.removeText(Cursor da, Cursor a);
    bool document.removeText(Range intervallo);

- Rimuove il testo nell'intervallo dato. Restituisce `true` se funziona, o `false` se il documento è in modalità di sola lettura.

    bool document.insertLine(int riga, String testo);

- Inserisce il testo nella riga data. Restituisce `true` se funziona, o `false` se il documento è in modalità di sola lettura o la riga non è nell'intervallo del documento.

    bool document.removeLine(int riga);

- Rimuove la riga di testo data. Restituisce `true` se funziona, o `false` se il documento è in modalità di sola lettura o la riga non è nell'intervallo del documento.

    bool document.wrapLine(int riga, int colonna);
    bool document.wrapLine(Cursor cursore);

- Manda a capo la `riga` alla posizione del `cursore` data. Restituisce `true` se funziona, altrimenti `false`, per esempio se la `riga` è minore di zero.

  Da: KDE 4.9

    void document.joinLines(int riga_inizio, int riga_fine);

- Unisce le righe da `riga_inizio` a `riga_fine`. Due righe di testo consecutive sono sempre separate da un solo spazio.

    int document.lines();

- Restituisce il numero di righe nel documento.

    int document.length();

- Restituisce il numero di caratteri nel documento.

    int document.lineLength(int riga);

- Restituisce la lunghezza della `riga`.

    void document.editBegin();

- Avvia un gruppo di modifica per un raggruppamento di azioni annullabili. Assicurati di chiamare sempre `editEnd()` con la stessa frequenza di `editBegin()`. Chiamare `editBegin` usa internamente un contatore di riferimenti, quindi questa chiamata può essere annidata.

    void document.editEnd();

- Chiude un gruppo di modifica. L'ultima chiamata di `editEnd()` (cioè quella corrispondente alla prima chiamata a `editBegin()`) conclude il passo di modifica.

    int document.firstColumn(int riga);

- Restituisce la prima colonna non di spazi nella `riga`. Se nella `riga` ci sono solo spazi, viene restituito `-1`.

    int document.lastColumn(int riga);

- Restituisce l'ultima colonna non di spazi nella `riga`. Se nella `riga` ci sono solo spazi, viene restituito `-1`.

    int document.prevNonSpaceColumn(int riga, int colonna);
    int document.prevNonSpaceColumn(Cursor cursore);

- Restituisce la colonna con caratteri non di spaziatura che comincia alla posizione del cursore data e cercando indietro.

    int document.nextNonSpaceColumn(int riga, int colonna);
    int document.nextNonSpaceColumn(Cursor cursore);

- Restituisce la colonna con caratteri non di spaziatura che comincia alla posizione del cursore data e cercando in avanti.

    int document.prevNonEmptyLine(int riga);

- Restituisce la prossima riga non vuota con caratteri non di spaziatura cercando indietro.

    int document.nextNonEmptyLine(int riga);

- Restituisce la prossima riga non vuota con caratteri non di spaziatura cercando in avanti.

    bool document.isInWord(String carattere, int attributo);

- Restituisce `true` se il `carattere` con l'`attributo` può far parte di una parola, altrimenti `false`.

    bool document.canBreakAt(String carattere, int attributo);

- Restituisce `true` se il `carattere` con l'`attributo` può essere mandato a capo, altrimenti `false`.

    bool document.canComment(int attributo_inizio, int attributo_fine);

- Restituisce `true` se un intervallo che inizia e finisce con gli attributi dati può essere fatto diventare un commento, altrimenti `false`.

    String document.commentMarker(int attributo);

- Restituisce l'indicatore di commento per i commenti di una sola riga per un `attributo`.

    String document.commentStart(int attributo);

- Restituisce l'indicatore di commento per l'inizio di commenti multiriga per un `attributo`.

    String document.commentEnd(int attributo);

- Restituisce l'indicatore di commento per la fine di commenti multiriga per un `attributo`.

    int document.attribute(int riga, int colonna);
    int document.attribute(Cursor cursore);

- Restituisce l'attributo alla posizione del cursore data.

    bool document.isAttribute(int riga, int colonna, int attributo);
    bool document.isAttribute(Cursor cursore, int attributo);

- Restituisce `true` se l'attributo alla posizione del cursore data è uguale a `attributo`, altrimenti `false`.

    String document.attributeName(int riga, int colonna);
    String document.attributeName(Cursor cursore);

- Restituisce il nome dell'attributo in testo leggibile. È uguale al nome `itemData` nei file di evidenziazione della sintassi.

    bool document.isAttributeName(int riga, int colonna, String nome);
    bool document.isAttributeName(Cursor cursore, String nome);

- Restituisce `true` se il nome dell'attributo a una certa posizione del cursore corrisponde al `nome`, altrimenti `false`.

    String document.variable(String chiave);

- Restituisce il valore della variabile del documento `chiave`. Se la variabile non esiste, il valore restituito è una stringa vuota.

    String document.setVariable(String chiave, String valore);

- Imposta il valore della variabile del documento richiesta `chiave`. Restituisce il valore della variabile impostata.

  Vedi anche: le variabili dei documenti di Kate.

  Da: KDE 4.8

    int document.firstVirtualColumn(int riga);

- Restituisce la colonna virtuale del primo carattere non di spaziatura nella riga indicata, o `-1` se la riga è vuota o contiene solo caratteri di spaziatura.

    int document.lastVirtualColumn(int riga);

- Restituisce la colonna virtuale dell'ultimo carattere non di spaziatura nella riga indicata, o `-1` se la riga è vuota o contiene solo caratteri di spaziatura.

    int document.toVirtualColumn(int riga, int colonna);
    int document.toVirtualColumn(Cursor cursore);
    Cursor document.toVirtualCursor(Cursor cursore);

- Converte la posizione reale del cursore in una virtuale, restituendo un oggetto `int` o `Cursor`.

    int document.fromVirtualColumn(int riga, int colonna_virtuale);
    int document.fromVirtualColumn(Cursor cursore_virtuale);
    Cursor document.fromVirtualCursor(Cursor cursore_virtuale);

- Converte la posizione virtuale data del cursore in una reale, restituendo un oggetto `int` o `Cursor`.

    Cursor document.anchor(int riga, int colonna, Char carattere);
    Cursor document.anchor(Cursor cursore, Char carattere);

- Cerca indietro il `carattere` partendo dal cursore dato. Per esempio, se si passa come carattere `(`, la funzione restituirà la posizione dell'apertura `(`. Questo conteggio dei riferimenti, cioè altri `(...)`, vengono ignorati.

    Cursor document.rfind(int riga, int colonna, String testo, int attributo = -1);
    Cursor document.rfind(Cursor cursore, String testo, int attributo = -1);

- Trova all'indietro il `testo` con l'`attributo` appropriato. L'`attributo` viene ignorato se è impostato a `-1`. Il cursore restituito non è valido se non si trova il `testo`.

    int document.defStyleNum(int riga, int colonna);
    int document.defStyleNum(Cursor cursore);

- Restituisce lo stile predefinito usato alla posizione data del cursore.

    bool document.isCode(int riga, int colonna);
    bool document.isCode(Cursor cursore);

- Restituisce `true` se l'attributo alla posizione data del cursore non è uguale a tutti i seguenti stili: `dsComment`, `dsString`, `dsRegionMarker`, `dsChar`, `dsOthers`.

    bool document.isComment(int riga, int colonna);
    bool document.isComment(Cursor cursore);

- Restituisce `true` se l'attributo del carattere alla posizione del cursore data è `dsComment`, altrimenti `false`.

    bool document.isString(int riga, int colonna);
    bool document.isString(Cursor cursore);

- Restituisce `true` se l'attributo del carattere alla posizione del cursore data è `dsString`, altrimenti `false`.

    bool document.isRegionMarker(int riga, int colonna);
    bool document.isRegionMarker(Cursor cursore);

- Restituisce `true` se l'attributo del carattere alla posizione del cursore data è `dsRegionMarker`, altrimenti `false`.

    bool document.isChar(int riga, int colonna);
    bool document.isChar(Cursor cursore);

- Restituisce `true` se l'attributo del carattere alla posizione del cursore data è `dsChar`, altrimenti `false`.

    bool document.isOthers(int riga, int colonna);
    bool document.isOthers(Cursor cursore);

- Restituisce `true` se l'attributo del carattere alla posizione del cursore data è `dsOthers`, altrimenti `false`.