# Estensione di &katepart;

## Introduzione

Come ogni componente editor di testi avanzato, &katepart; offre una moltitudine di modi per espandere le proprie funzionalità: puoi scrivere semplici script per aggiungere funzionalità con javaScript. Infine, dopo aver esteso &katepart; saresti il benvenuto nel nostro gruppo, per condividere il tuo lavoro con il mondo intero!

## Lavorare con l'evidenziazione della sintassi

### Panoramica

L'evidenziazione della sintassi è quel qualcosa che rende l'editor in grado di visualizzare automaticamente il testo con stili e colori differenti, a seconda delle funzioni delle stringhe in relazione allo scopo del file. Nel sorgente di un programma, per esempio, le istruzioni di controllo potrebbero essere rese in grassetto, mentre i tipi di dati e i commenti in colori diversi dal resto del testo. Questo migliora di molto la leggibilità del testo, e rende l'autore più efficiente e più produttivo.

Una funzione Perl, resa con l'evidenziazione della sintassi.

Una funzione Perl, resa con l'evidenziazione della sintassi.

La stessa funzione Perl, senza l'evidenziazione.

La stessa funzione Perl, senza l'evidenziazione.

Dei due esempi, qual è il più semplice da leggere?

&kappname; nasce con un sistema, flessibile, configurabile e in grado di eseguire l'evidenziazione della sintassi. Nella distribuzione standard sono fornite definizioni per una vasta gamma di linguaggi di programmazione, di scripting e di markup, e per altri formati di file di testo; inoltre puoi inserire le tue definizioni in un semplice file &XML;.

Quando apri un file basato sul tipo &MIME; del file &kappname; riconoscerà automaticamente le giuste regole della sintassi; questo in base alla sua estensione o, se assente, al suo contenuto. Puoi sempre impostare manualmente la sintassi da usare qualora notassi dei problemi, facendo clic su Strumenti Evidenziazione.

Gli stili e i colori usati da ciascuna definizione di evidenziazione della sintassi possono essere configurati usando la scheda Stili di testo evidenziato, mentre i tipi &MIME; e le estensioni del file che dovrebbero essere usate a questo scopo sono gestiti nella scheda Modi e tipi di file.

L'evidenziazione della sintassi serve per migliorare la leggibilità del testo, ma non puoi affidarti ad essa per convalidarlo. La marcatura del testo in base alla sintassi può essere difficoltosa a seconda del formato che si sta utilizzando, e in qualche caso l'autore delle regole della sintassi sarà orgoglioso qualora il 98% del testo venga correttamente renderizzato. Tuttavia, in genere, sarà difficile incontrare quel 2% non corretto.

Puoi scaricare le regole di evidenziazione della sintassi aggiornate o aggiuntive dal sito web di &kappname;; fai clic sul pulsante Scarica i file delle evidenziazioni... che si trova nella scheda Modi e tipi di file della Finestra di configurazione.

### Il sistema di evidenziazione della sintassi di &kappname;

In questa sezione sarà trattato più in dettaglio il meccanismo di evidenziazione della sintassi. Ti servirà se vorrai saperne di più, oppure se vorrai cambiare o creare delle definizioni di sintassi.

#### Come funziona

Una delle prime cose che l'editor &kappname; fa ogni volta che apri un file è quella di individuare quale sia la definizione di sintassi da usare. Mentre stai leggendo il testo del file, e mentre ci stai digitando qualcosa, il sistema di evidenziazione della sintassi analizza il testo usando le regole definite dalle definizioni di sintassi, e lo marca dove i diversi contesti e gli stili iniziano e finiscono.

Quando digiti nel documento il nuovo testo viene analizzato e marcato al volo. Cosicché, se cancelli un carattere che è marcato come inizio o fine di un contesto, lo stile del testo circostante viene cambiato di conseguenza.

Le definizioni di sintassi usate dal sistema di evidenziazione di &kappname; sono file &XML;, che contengono

- Regole per individuare il ruolo del testo, organizzate in blocchi di contesto

- Liste di parole chiave

- Definizioni di oggetti di stile

Quando il testo viene analizzato le regole di rilevamento sono valutate nell'ordine in cui sono definite, e, qualora l'inizio della stringa corrente coincida con una regola, viene usato il contesto relativo. Il punto di inizio del testo viene spostato nel punto finale in cui la regola è stata applicata, e inizia così un nuovo ciclo, che comincia nel contesto impostato dalla regola applicata.

#### Regole

Le regole di rilevamento sono il cuore del sistema di rilevamento della sintassi. Una regola è una stringa, un carattere o un'espressione regolare con cui confrontare il testo che viene analizzato. Contiene informazioni sullo stile da usare per la parte corrispondente del testo. Può passare il contesto di lavoro del sistema sia ad un contesto menzionato esplicitamente che al precedente contesto usato dal testo.

Le regole sono organizzate in gruppi di contesto, ciascuno dei quali viene usato per i concetti principali di testo all'interno del formato, per esempio le stringhe di testo virgolettato o i blocchi di commenti nei sorgenti dei programmi. Questo assicura che il sistema di evidenziazione non abbia necessità di cercare tra le regole se non è necessario, e che alcune sequenze di caratteri nel testo possono essere trattate in maniera diversa a seconda del contesto corrente.

I contesti possono essere generati dinamicamente per permettere l'uso di istanze di dati specifici nelle regole.

#### Stili di contesto e parole chiave

In alcuni linguaggi di programmazione i numeri interi sono trattati dal compilatore (il programma che converte il codice sorgente in binario eseguibile) in maniera diversa da quelli in virgola mobile, e all'interno di una stringa virgolettata ci possono essere dei caratteri con un significato speciale. In questi casi ha senso visualizzarli in modo differente da quelli circostanti, in modo che possano essere identificati facilmente durante la lettura del testo. Così, pur non rappresentando un contesto speciale, questi possono essere comunque trattati come tali dal sistema di evidenziazione della sintassi, in modo da essere contrassegnati e quindi visualizzati in modo diverso.

Una definizione di sintassi può contenere tutti gli stili richiesti per racchiudere i concetti del formato per cui è usata.

In molti formati ci sono liste di parole che rappresentano un concetto specifico: per esempio nei linguaggi di programmazione le istruzioni di controllo sono un concetto, i nomi dei tipi di dato un altro, e le funzioni proprie del linguaggio un terzo. Il sistema di evidenziazione della sintassi di &kappname; può usare queste liste per individuare le parole marcandole nel testo, in modo da enfatizzare i concetti dei formati di testo.

#### Stili predefiniti

Se apri un file sorgente in C++, un sorgente &Java; e un documento HTML in &kappname; vedrai che, anche se i formati e le parole scelte per il trattamento speciale sono diversi, i colori utilizzati sono gli stessi. Questo succede perché &kappname; ha una lista di stili predefiniti che sono impiegati dalle definizioni individuali di sintassi.

Questo rende semplice riconoscere concetti simili in formati di testo diversi. Per esempio, i commenti sono presenti in quasi tutti i linguaggi di programmazione, di scripting e di markup: se sono sempre renderizzati utilizzando lo stesso stile in tutti i linguaggi non avrai bisogno di fermarti a pensare per identificarli nel testo.

Tutti gli stili di una definizione di sintassi usano uno degli stili predefiniti: solo poche definizioni di sintassi fanno usa di altri non predefiniti. Potrebbe valer la pena lanciare la finestra di configurazione se usi spesso un formato, per vedere se alcuni concetti fanno uso di uno stesso stile. Per esempio, c'è solo uno stile predefinito per le stringhe, ma il linguaggio di programmazione Perl opera con due: potresti quindi migliorarne l'evidenziazione configurandole in modo che siano leggermente diverse. Tutti gli stili predefiniti disponibili saranno spiegati in seguito.

### Il formato &XML; di definizione dell'evidenziazione

#### Panoramica

Questa sezione è una panoramica sul formato &XML; di definizione dell'evidenziazione. Basandosi su un piccolo esempio saranno descritti i componenti principali, il loro significato e il loro uso. La prossima sezione scenderà invece nei dettagli delle regole di rilevamento dell'evidenziazione.

La definizione formale, conosciuta anche come XSD, è immagazzinata nel file `language.xsd`, che dovrebbe essere installato nel tuo sistema, nella cartella `$`XDG_DATA_DIRS`/katepart5/syntax`. Al suo interno la variabile `XDG_DATA_DIRS` viene tipicamente espansa in `/usr/share`.

In &Windows; questi file si trovano in `%USER%\AppData\Local\katepart5\syntax`. `%USER%` viene generalmente espanso in `C:\\Users\\`user``.

#### Le sezioni principali dei file di definizione dell'evidenziazione di &kappname;

Un file di evidenziazione contiene un'intestazione che imposta la versione XML:

-     <?xml version="1.0" encoding="UTF-8"?>

Il file di definizione inizia con l'elemento `language`. Gli attributi disponibili sono:

- Attributi richiesti:

  `name` imposta il nome del linguaggio. Appare successivamente nei menu e nelle finestre.

  `section` specifica la categoria.

  `extensions` definisce le estensioni dei file, come "*.cpp;*.h"

  Attributi opzionali:

  `mimetype` associa i tipi &MIME; dei file.

  `version` specifica l'attuale versione del file di definizione.

  `kateversion` specifica l'ultima versione supportata di &kappname;.

  `casesensitive` definisce se le parole chiave sono sensibili alle maiuscole oppure no.

  `priority` è necessaria se un'altra definizione di evidenziazione usa le stesse estensioni; vince quella con priorità più alta.

  `author` contiene il nome dell'autore e il suo indirizzo di posta elettronica.

  `license` contiene la licenza, di solito LGPL, Artistic, GPL, oppure altre.

  `style` contiene il linguaggio fornito, ed è usato dai rientratori per gli attributi `required-syntax-style`.

  `hidden` definisce se il nome deve apparire nei menu di &kappname;.

  Allora la prossima riga potrebbe apparire così:

      <language name="C++" version="1.00" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" />

Viene poi l'elemento `highlighting`, che contiene l'elemento opzionale `list`, e i richiesti `contexts` e `itemDatas`.

- L'elemento `list` contiene una lista di parole chiave; in questo caso le parole chiave sono class e const; puoi aggiungere tutte le liste di cui hai bisogno.

  L'elemento `contexts` contiene tutti i contesti; il primo è di default l'inizio dell'evidenziazione. Ci sono due regole nel contesto Normal Text, una associa la lista delle parole chiave con nome somename, e un'altra rileva una virgoletta, passando il contesto a string. Per saperne di più leggi il prossimo capitolo.

  La terza parte è l'elemento `itemDatas`: contiene tutti i colori e gli stili dei caratteri che sono necessari per il contesto e per le regole. In questo esempio vengono usati `itemData` Normal Text, String e Keyword.

      <highlighting>
          <list name="somename">
            <item> class </item>
            <item> const </item>
          </list>
          <contexts>
            <context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" >
              <keyword attribute="Keyword" context="#stay" String="somename" />
              <DetectChar attribute="String" context="string" char="&quot;" />
            </context>
            <context attribute="String" lineEndContext="#stay" name="string" >
              <DetectChar attribute="String" context="#pop" char="&quot;" />
            </context>
          </contexts>
          <itemDatas>
            <itemData name="Normal Text" defStyleNum="dsNormal" />
            <itemData name="Keyword" defStyleNum="dsKeyword" />
            <itemData name="String" defStyleNum="dsString" />
          </itemDatas>
        </highlighting>

L'ultima parte di una definizione di evidenziazione è la sezione opzionale `general`. Può contenere informazioni sulle parole chiave, il raggruppamento del codice, i commenti e i rientri.

- La sezione `comment` definisce con quale stringa viene introdotta una singola riga di commento. Puoi anche definire un commento multi-riga usando multiLine con l'attributo addizionale end. Questo viene usato se l'utente preme la scorciatoia per commentare/non commentare.

  La sezione `keywords` definisce se la lista delle parole chiave è sensibile alle maiuscole oppure no. Altri attributi verranno spiegati più tardi.

      <general>
          <comments>
            <comment name="singleLine" start="#"/>
          </comments>
          <keywords casesensitive="1"/>
        </general>
      </language>

#### Le sezioni in dettaglio

Questa parte descriverà tutti gli attributi disponibili per contexts, itemDatas, keywords, comments, il raggruppamento del codice e i rientri.

L'elemento `context` appartiene al gruppo `contexts`. Di per sé un contesto definisce le regole specifiche del contesto, tipo cosa dovrebbe accadere qualora il sistema di evidenziazione raggiunga il fine riga. Gli attributi disponibili sono:

- `name` dichiara il nome del contesto. Le regole faranno uso di questo nome per specificare il contesto al quale passare se la regola viene soddisfatta.

  `lineEndContext` definisce il contesto a cui il sistema di evidenziazione passa se viene raggiunta la fine della riga. Questo può essere sia il nome di un altro contesto, `#stay` per non lasciare il contesto (⪚. non fare niente), oppure `#pop`, che causerà l'abbandono di questo contesto. È possibile usare per esempio `#pop#pop#pop` per saltare tre volte, o anche `#pop#pop!OtherContext` per saltare due volte e passare al contesto chiamato `OtherContext`.

  `lineEmptyContext` definisce il contesto se viene incontrata una riga vuota. Predefinito: #stay.

  `fallthrough` definisce se il sistema di evidenziazione deve passare al contesto specificato in fallthroughContext qualora nessuna regola venga soddisfatta. Predefinito: false.

  `fallthroughContext` specifica il prossimo contesto se nessuna regola viene soddisfatta.

  Se `dynamic` è true il contesto si ricorderà delle stringhe e dei segnaposti salvati dalle regole dinamiche. Questo serve per esempio nei documenti HERE. Predefinito: false.

L'elemento `itemData` appartiene al gruppo `itemDatas`. Definisce lo stile del carattere e i colori, e quindi è possibile definire i propri stili e i propri colori. Raccomandiamo però di attenersi agli stili predefiniti, se possibile, cosicché gli utenti vedranno sempre gli stessi colori anche in linguaggi diversi. Tuttavia a volte non c'è altro modo se non quello di cambiare i colori e gli attributi dei caratteri. Sono richiesti il nome degli attributi e StileNumDef, ma gli altri sono opzionali. Gli attributi disponibili sono:

- `name` imposta il nome di itemData. I contesti e le regole useranno questo nome nei loro attributi attribute a cui fa riferimento itemData.

  `defStyleNum` definisce quale stile predefinito usare. Gli stili predefiniti disponibili sono spiegati in dettaglio più tardi.

  `color` definisce un colore. Sono validi i formati «#rrggbb» o «#rgb».

  `selColor` definisce la selezione del colore.

  Il testo sarà in corsivo se `italic` è true.

  Il testo sarà in grassetto se `bold` è true.

  Il testo sarà sottolineato se `underline` è true.

  Il testo sarà in barrato se `strikeout` è true.

  Il testo sarà controllato ortograficamente se `spellChecking` è true.

L'elemento `keywords` del gruppo `general` definisce le proprietà delle parole chiave. Gli attributi disponibili sono:

- `casesensitive` può essere true oppure false; se è true tutte le parole chiave soddisfano la sensibilità alle maiuscole.

  `weakDeliminator` è una lista di caratteri che non agiscono da delimitatori di parole; per esempio, il punto `«.»` è un delimitatore di parola. Se assumiamo che una parola chiave in una `lista` possa contenere un punto, sarà soddisfatta solo se specifichi che il punto è un delimitatore debole.

  `additionalDeliminator` definisce delimitatori addizionali.

  `wordWrapDeliminator` definisce i caratteri dopo dei quali una riga può andare a capo.

  Sono delimitatori predefiniti e terminatori di parola i caratteri `.():!+,-<=>%&*/;?[]^{|}~\`, gli spazi (`« »`) e i tabulatori (`«\t»`).

L'elemento `comment` del gruppo `comments` definisce le proprietà che sono usate in Strumenti Commenta e Strumenti Decommenta. Gli attributi disponibili sono:

- `name` è sia singleLine che multiLine. Se scegli multiLine sono richiesti gli attributi end e region.

  `start` definisce la stringa usata per iniziare un commento. In C++ sarebbe "/*".

  `end` definisce la stringa per chiudere un commento. In C++ questo sarebbe "*/".

  `region` dovrebbe essere il nome dei commenti multi-riga raggruppabili. Assumendo di avere nelle regole beginRegion="Comment" ... endRegion="Comment" si dovrebbe usare region="Comment". In questo modo l'azione di decommento funziona anche se non viene selezionato tutto il testo di un commento multi-riga, il cursore deve solo essere all'interno del commento.

L'elemento `raggruppamento` del gruppo `general` definisce le proprietà di raggruppamento del codice. Gli attributi disponibili sono:

- Se `indentationsensitive` è true i marcatori del raggruppamento del codice saranno aggiunti basandosi sul rientro, come nel linguaggio di scripting Python. Di solito non hai necessità di impostarlo, e di solito è impostato a false.

L'elemento `indentation`del gruppo `general` definisce quali rientratori verranno usati. Raccomandiamo caldamente però di omettere questo elemento, dato che il rientratore sarà impostato sia definendo un tipo di file, sia aggiungendo un modello di riga al file di testo. Se si specifica un rientratore, infatti, si forzerà l'uso un rientro specifico, che potrebbe non andar bene sempre. Gli attributi disponibili sono:

- `modo` è il nome del rientratore. I rientratori disponibili sono: normal, cstyle, haskell, lilypond, lisp, python, ruby e xml.

#### Stili predefiniti disponibili

Gli stili predefiniti sono stati già trattati, come piccolo riassunto: gli stili predefiniti sono i caratteri predefiniti e gli stili colore.

Stili generali predefiniti:

- `dsNormal`, quando non è richiesta nessuna evidenziazione speciale.

  `dsKeyword`, parola chiave integrata nel linguaggio.

  `dsFunction`, chiamate di funzioni e definizioni.

  `dsVariabile`, se applicabile: nomi delle variabili (ad es. $someVar in PHP/Perl).

  `dsControlFlow`, parole chiave per il controllo del flusso, come if, else, switch, break, return, yield, ...

  `dsOperator`, operatori come + - * / :: < >

  `dsBuiltIn`, funzioni integrate, classi e oggetti.

  `dsExtension`, estensioni comuni, come le classi Qt e le funzioni o le macro in C++ e in Python.

  `dsPreprocessor`, direttive al preprocessore o definizioni di macro.

  `dsAttribute`, annotazioni come @override e __declspec(...).

Stili predefiniti relativi alle stringhe:

- `dsChar`, caratteri singoli, come 'x'.

  `dsSpecialChar`, caratteri con significati speciali nelle stringhe, come escape, sostituzioni, oppure operatori regex.

  `dsString`, stringhe come "hello world".

  `dsVerbatimString`, letterale o stringa grezza, come 'raw \backlash' in Perl, CoffeeScript, e shell, come r'\raw' in Python.

  `dsSpecialString`, SQL, regexes, documenti HERE, modi LaTeX math, ...

  `dsImport`, importazione, inclusione, richieste di moduli.

Stili predefiniti relativi ai numeri:

- `dsDataType`, tipi di dati integrati, come int, void, u64.

  `dsDecVal`, valori decimali.

  `dsBaseN`, valori con base diversa da 10.

  `dsFloat`, valori in virgola mobile.

  `dsCostant`, costanti integrate e definite dall'utente, come PI.

Commenti e stili predefiniti relativi alla documentazione:

- `dsComment`, commenti.

  `dsDocumentation`, /** Commenti nella documentazione */ o """docstrings""".

  `dsAnnotation`, comandi nella documentazione, come @param, @brief.

  `dsCommentVar`, i nomi delle variabili usati nei comandi precedenti, come "pippobar" in @param pippobar.

  `dsRegionMarker`, delimitatori di regioni, come //BEGIN e //END nei commenti.

Altri stili predefiniti:

- `dsInformation`, annotazioni e suggerimenti, come @note in doxygen.

  `dsWarning`, avvisi, come @warning in doxygen.

  `dsAlert`, parole speciali, come TODO, FIXME, XXXX.

  `dsError`, evidenziazione di errori e sintassi errata.

  `dsOthers` per tutto il resto.

### Regole di rilevamento dell'evidenziazione

Questa sezione descrive le regole di rilevamento della sintassi.

Ogni regola può associare zero o più caratteri all'inizio della stringa su cui è testata. Se la regola corrisponde i caratteri associati sono assegnati allo stile o all'attributo definito dalla regola; una regola può chiedere che l'attuale contesto venga cambiato.

Una regola è un qualcosa che assomiglia a questo:

    <RuleName attribute="(identifier)" context="(identifier)" [attributi specifici della regola] />

attribute identifica lo stile da usare per i caratteri associati secondo il nome, mentre context identifica il contesto da usare da qui in avanti.

context può essere identificato da:

- identifier, che è il nome dell'altro contesto.

- order, che dice al motore di rimanere nel contesto attuale (`#stay`), oppure di ritornare a quello precedentemente usato nella stringa (`#pop`).

  Per tornare indietro di più passi la parola chiave #pop può essere ripetuta: `#pop#pop#pop`

- order seguito da un punto esclamativo (!) e identifier, che faranno prima seguire al motore l'ordine, e poi lo mandano in un altro contesto, ad esempio `#pop#pop!OtherContext`.

Alcune regole possono avere delle regole figlie, che vengono valutate solo se la regola genitore corrisponde. All'intera stringa corrispondente sarà dato l'attributo definito dalla regola genitore. Una regola con delle regole figlie assomiglia a questo:

    <RuleName (attributi)>
      <ChildRuleName (attributi) />
      ...
    </RuleName>

Gli attributi specifici per la regola variano, e sono descritti nelle sezioni seguenti.

### Attributi comuni

Tutte le regole hanno in comune i seguenti attributi, e sono disponibili ogni volta che compare `(attributi comuni)`. Sono attributi richiesti attribute e context, tutti gli altri sono opzionali.

- attribute: un attributo associato ad un determinato itemData.

- context: specifica il contesto al quale il sistema di evidenziazione passa se la regola corrisponde.

- beginRegion: inizia un blocco di raggruppamento del codice. Predefinito: non impostato.

- endRegion: chiude un un blocco di raggruppamento del codice. Predefinito: non impostato.

- lookAhead: se impostato a true il sistema di evidenziazione non processerà la lunghezza assegnata. Predefinito: false.

- firstNonSpace: corrisponde solo se la stringa è la prima senza spazi nella riga. Predefinito: false.

- column: corrisponde solo se la colonna combacia. Predefinito: non impostato.

### Regole dinamiche

Alcune regole permettono di usare l'attributo opzionale `dynamic` di tipo booleano il cui valore predefinito è false. Se dynamic è true, una regola può usare un segnaposto che rappresenta le corrispondenze di una regola di tipo espressione regolare che è passata al contesto corretto nei proprio attributi `string` o `char`. Nel caso di `string` il segnaposto `%N` (dove N è un numero) sarà sostituito con la corrispondente stringa di cattura `N` dall'espressione regolare chiamante. Nel caso di `char` il segnaposto deve essere un numero `N` e sarà sostituito con il primo carattere della corrispondente stringa di cattura `N` dall'espressione regolare chiamante. Quando una regola permette l'uso di questo attributo conterrà (dynamic).

- dynamic: può essere (true|false).

#### Le regole in dettaglio

DetectChar

- Rileva un singolo carattere specifico. Usato comunemente per trovare ad esempio la fine di una stringa tra virgolette.

      <DetectChar char="(carattere)" (attributi comuni) (dynamic) />

  L'attributo `char` definisce il carattere da abbinare.

Detect2Chars

- Rileva due caratteri specifici in un ordine definito.

      <Detect2Chars char="(carattere)" char1="(carattere)" (attributi comuni) (dynamic) />

  L'attributo `char` definisce il primo carattere da associare, `char1` il secondo.

AnyChar

- Rileva un carattere da un insieme di caratteri specificati.

      <AnyChar String="(stringa)" (attributi comuni) />

  L'attributo `String` definisce l'insieme dei caratteri.

StringDetect

- Rileva una stringa esatta.

      <StringDetect String="(stringa)" [insensitive="true|false"] (attributi comuni) (dynamic) />

  L'attributo `String` definisce la stringa da abbinare. All'attributo `insensitive` viene assegnato come valore predefinito false, e viene passato alla funzione di confronto della stringa. Se il valore è true allora nel confronto non si terrebbe conto delle maiuscole.

WordDetect

- Non rileva una stringa esatta, ma i confini di una parola quali un punto `'.'` o uno spazio all'inizio o alla fine della parola. Pensa `\b<string>\b` come un'espressione regolare, ma più veloce della regola `RegExpr`.

      <WordDetect String="(stringa)" [insensitive="true|false"] (attributi comuni) (dynamic) />

  L'attributo `String` definisce la stringa da abbinare. All'attributo `insensitive` viene assegnato come valore predefinito false, e viene passato alla funzione di confronto della stringa. Se il valore è true allora nel confronto non si terrebbe conto delle maiuscole.

  Da: Kate 3.5 (KDE 4.5)

RegExpr

- Corrisponde con un'espressione regolare.

      <RegExpr String="(stringa)" [insensitive="true|false"] [minimal="true|false"] (attributi comuni) (dynamic) />

  L'attributo `String` definisce l'espressione regolare.

  `insensitive` ha come valore predefinito false, e viene passato al motore per le espressioni regolari.

  `minimal` ha come valore predefinito false, e viene passato al motore per le espressioni regolari.

  Le regole sono sempre confrontate con l'inizio della stringa corrente, tuttavia un'espressione regolare iniziante con un apice (`^`) è segno che la regola dovrebbe essere confrontata invece con l'inizio di una riga.

  Vedi Espressioni regolari per maggiori informazioni.

keyword

- Rileva una parola chiava da una lista specifica.

      <keyword String="(nome lista)" (attributi comuni) />

  L'attributo `String` identifica la lista di parole chiave per nome. Deve esistere una lista con questo nome.

  Il sistema di evidenziazione elabora regole di parole chiave in maniera molto ottimizzata. Questo rende assolutamente necessario che ogni parola chiave da confrontare sia circondata da delimitatori definiti, sia impliciti (i delimitatori predefiniti) che espliciti, specificati dalla proprietà additionalDeliminator con l'etichetta keywords.

  Se una parola chiave da confrontare dovesse contenere un carattere di delimitazione, allora questo dovrebbe essere aggiunto alla proprietà weakDeliminator con l'etichetta keywords. Questo carattere perderebbe le sue proprietà di delimitatore in tutte le regole keywords.

Int

- Rileva un numero intero.

      <Int (attributi comuni) (dynamic) />

  Questa regola non ha attributi specifici. Le regole figlie sono usate tipicamente per individuare combinazioni di `L` e `U` dopo il numero che sta ad indicare il tipo di intero nel codice programma. Al momento tutte le regole sono consentite come regole figlie, però la DTD permette solo la regola figlia `StringDetect`.

  L'esempio seguente associa numeri interi seguiti dal carattere «L».

      <Int attribute="Decimal" context="#stay" >
        <StringDetect attribute="Decimal" context="#stay" String="L" insensitive="true"/>
      </Int>

Float

- Rileva un numero in virgola mobile.

      <Float (attributi comuni) />

  Questa regola non ha attributi specifici. `AnyChar` è permesso come regola figlia e tipicamente usato per rilevare combinazioni, vedi come riferimento la regola `Int`.

HlCOct

- Rileva un numero con rappresentazione ottale.

      <HlCOct (attributi comuni) />

  Questa regola non ha attributi specifici.

HlCHex

- Rileva un numero con rappresentazione esadecimale.

      <HlCHex (attributi comuni) />

  Questa regola non ha attributi specifici.

HlCStringChar

- Rileva un carattere di escape.

      <HlCStringChar (attributi comuni) />

  Questa regola non ha attributi specifici.

  Controlla la corrispondenza di espressioni letterali di caratteri generalmente usate nel codice dei programmi, per esempio `\n` (nuova riga) o `\t` (TAB).

  I seguenti caratteri corrisponderanno se saranno seguiti da una barra inversa (`\`): `abefnrtv"'?\`. Inoltre corrisponderanno numeri esadecimali preceduti dal carattere di escape, come per esempio `\xff` e numeri ottali preceduti dal carattere di escape, per esempio `\033`.

HlCChar

- Rileva il carattere C

      <HlCChar (attributi comuni) />

  Questa regola non ha attributi specifici.

  Controlla la corrispondenza di caratteri C racchiusi da un accento (Esempio: `'c'`). Gli accenti possono essere caratteri singoli o caratteri di escape. Vedi HlCStringChar per le sequenze di caratteri di escape associate.

RangeDetect

- Rileva una stringa con caratteri di inizio e di fine definiti.

      <RangeDetect char="(carattere)"  char1="(carattere)" (attributi comuni) />

  `char` definisce il carattere con cui inizia l'intervallo, `char1` il carattere con cui finisce.

  Utile per individuare per esempio piccole stringhe tra virgolette e simili; nota però che non verranno in questo modo trovate le stringhe che si estendono dopo un'interruzione di riga. Questo perché il motore di evidenziazione lavora su una riga alla volta.

LineContinue

- Associa un carattere specificato con la fine di una riga.

      <LineContinue (attributi comuni) [char="\"] />

  `char` carattere opzionale da associare; come predefinito c'è la barra inversa (`'\'`). Novità da KDE 4.13.

  Questa regola è utile per cambiare il contesto alla fine di una riga. È necessaria per esempio in C/C++, per continuare le macro o le stringhe.

IncludeRules

- Include delle regole da un altro file di contesto o da un linguaggio.

      <IncludeRules context="contextlink" [includeAttrib="true|false"] />

  L'attributo `context` definisce quale contesto includere.

  Se è una stringa semplice include tutte le regole nel contesto corrente, per esempio:

      <IncludeRules context="altroContesto" />

  Se la stringa contiene `##` il sistema di evidenziazione cercherà un contesto in un altra definizione di linguaggio con il nome assegnato, per esempio

      <IncludeRules context="String##C++" />

  dovrebbe includere il contesto String dalle definizioni di evidenziazione del C++.

  Se l'attributo `includeAttrib` è true cambia l'attributo di destinazione con uno del sorgente. Questo è richiesto per esempio per fare dei commenti, se il testo associato al contesto incluso ha una diversa evidenziazione dal contesto che lo ospita.

DetectSpaces

- Rileva gli spazi.

      <DetectSpaces (attributi comuni) />

  Questa regola non ha attributi specifici.

  Usa questa regola quando sai che potrai incontrare numerosi spazi, per esempio all'inizio di righe rientrate. Questa regola salterà tutti gli spazi in un colpo solo, invece di provare regole multiple da scartarle di volta in volta per mancanza di corrispondenza.

DetectIdentifier

- Rileva gli identificatori di stringhe (come un'espressione regolare [a-zA-Z_][a-zA-Z0-9_]*).

      <DetectIdentifier (attributi comuni) />

  Questa regola non ha attributi specifici.

  Usa questa regola per saltare subito una stringa di caratteri alfanumerici, invece di usare più regole e saltare i caratteri uno alla volta per mancanza di corrispondenza.

#### Suggerimenti e trucchi

Una volta che hai capito come funziona il passaggio del contesto sarà semplice scrivere definizioni di evidenziazione, anche se dovresti controllare attentamente quale regola scegliere e in quale situazione. Le espressioni regolari sono molto potenti, ma sono lente se comparate con altre regole. Così tieni conto dei suggerimenti seguenti.

- Se cerchi la corrispondenza di solo due caratteri usa `Detect2Chars` invece che `StringDetect`. Lo stesso vale per `DetectChar`.

- Le espressioni regolari sono semplici da usare, ma spesso c'è un altro modo molto più veloce per ottenere gli stessi risultati. Considera di voler semplicemente cercare la corrispondenza del carattere `«#»` solo quando è il primo della riga. Una soluzione basata su un'espressione regolare assomiglierebbe a questo:

      <RegExpr attribute="Macro" context="macro" String="^\s*#" />

  . Puoi ottenere lo stesso risultato in maniera più veloce usando:

      <DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" />

  . Se vuoi cercare corrispondenze per l'espressione regolare `'^#'` puoi sempre usare `DetectChar` con l'attributo `column="0"`. L'attributo `column` conta i caratteri, e un tabulatore è un solo carattere.

- Puoi cambiare i contesti senza bisogno di elaborare dei caratteri. Se vuoi cambiare contesto quando incontri la stringa `*/` devi almeno elaborare quella stringa nel contesto del testo. La regola qui sotto corrisponderà, e l'attributo `lookAhead` farà in modo che l'evidenziatore tenga la stringa corrispondente per il contesto successivo.

      <Detect2Chars attribute="Comment" context="#pop" char="*" char1="/" lookAhead="true" />

- Usa `DetectSpaces` se sai di incontrare molti spazi.

- Usa `DetectIdentifier` al posto dell'espressione regolare `'[a-zA-Z_]\w*'`.

- Usa gli stili predefiniti ogni volta che puoi. In questo modo l'utente si troverà in un ambiente familiare.

- Guarda dentro altri file XML, per vedere come le altre persone implementano le regole difficili.

- Puoi convalidare qualsiasi file XML usando il comando `xmllint --schema language.xsd miaSintassi.xml`.

- Se ripeti molto spesso delle espressioni regolari complesse puoi usare ENTITIES. Esempio:

      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE language SYSTEM "language.dtd"
      [
              <!ENTITY myref    "[A-Za-z_:][\w.:_-]*">
      ]>

  Ora puoi usare &myref; invece dell'espressione regolare.

## Scripting con JavaScript

Il componente editor di &kappname; è facilmente estendibile attraverso degli script. Il linguaggio di script è ECMAScript (comunemente noto come JavaScript). &kappname; supporta due tipi di script: script di rientro e a 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 Invio.

Le sezioni seguenti descrivono passo-passo come creare la struttura di un semplice rientratore. Come primo passo crea un nuovo file `*.js` chiamato ⪚ `javascript.js` nella cartella home locale `$`XDG_DATA_HOME`/katepart5/script/indentation`. Al suo interno la variabile di ambiente `XDG_DATA_HOME` viene tipicamente espansa sia in `~/.local` che in `~/.local/share`.

In &Windows; questi file si trovano in `%USER%\AppData\Local\katepart5\indentation`. `%USER%` viene generalmente espanso in `C:\\Users\\`user``.

#### L'intestazione dello script di rientro

L'intestazione del file `javascript.js` è incorporata come JSON all'inizio del documento, e ha la forma seguente:

    var katescript = {
        "name": "JavaScript",
        "author": "Pippo <pippo@topolinia.it>"
        "license": "BSD License",
        "revision": 1,
        "kate-version": "5.1",
        "required-syntax-style":"javascript",
        "indent-languages": ["javascript"],
        "priority": 0,
    }; // kate-script-header, deve essere all'inizio della riga senza commenti

Ogni voce viene ora spiegata in dettaglio:

- `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 Licenza BSD o LGPLv3.

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

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

- `required-syntax-style` [facoltativo]: lo stile della sintassi richiesto, se soddisfa lo `stile` specificato nei file 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 JSON di stili di sintassi che il rientratore può far rientrare correttamente, ⪚: `["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.

#### 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 `$`XDG_DATA_DIRS`/katepart5/script/indentation`.

In &Windows; questi file si trovano in `%USER%\AppData\Local\katepart5\indentation`. `%USER%` viene generalmente espanso in `C:\\Users\\`user``.

Lo sviluppo di un rientratore richiede il ricaricamento gli script, per testare le modifiche. Invece di riavviare l'applicazione puoi però 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 da 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 da riga di comando si trovano nella stessa cartella degli script di rientro. Come primo passo, crea un nuovo file `*.js` chiamato `myutils.js` nella home locale `$`XDG_DATA_HOME`/katepart5/script/commands`. Al suo interno la variabile di ambiente `XDG_DATA_HOME` viene tipicamente espansa sia in `~/.local` che in `~/.local/share`.

In &Windows; questi file si trovano in `%USER%\AppData\Local\katepart5\commands`. `%USER%` viene generalmente espanso in `C:\\Users\\`user``.

#### L'intestazione dello script per la riga di comando

L'intestazione di ciascuno script da riga di comando è incorporata in JSON all'inizio dello script come segue:

    var katescript = {
        "author": "Example Name <example.name@some.address.org>",
        "license": "LGPLv2+",
        "revision": 1,
        "kate-version": "5.1",
        "functions": ["sort", "moveLinesDown"],
        "actions": [
            {   "function": "sort",
                "name": "Ordina il testo selezionato",
                "category": "Editing",
                "interactive": "false"
            },
            {   "function": "moveLinesDown",
                "name": "Sposta le righe in basso",
                "category": "Editing",
                "shortcut": "Ctrl+Shift+Down",
                "interactive": "false"
            }
        ]
    }; // l'intestazione dello script di kate deve essere all'inizio del file senza commento

Ciascuna voce è spiegata ora in dettaglio:

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

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

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

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

- `functions` [obbligatorio]: vettore JSON di comandi nello script.

- `actions` [opzionale]: un vettore JSON di oggetti JSON che definiscono le azioni che appaiono nel menu dell'applicazione. Informazioni dettagliate sono fornite nella sezione Stabilire le scorciatoie.

Dal momento che il valore di `functions` è un vettore JSON, un singolo script può contenere un numero arbitrario di comandi per la riga di comando. Ciascuna funzione è disponibile attraverso il menu riga di comando integrata di &kappname;.

#### Il codice sorgente dello script

Tutte le funzioni specificate nell'intestazione devono essere implementate nello script. Lo script nell'esempio qui sopra deve implementare le due funzioni `sort` e `moveLinesDown`. 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`, ecc. 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, &ie; `comando == "sort"`. &kappname; presenterà quindi il testo risultante come documentazione per l'utente. Assicurati di tradurre le stringhe.

Lo sviluppo di uno script da riga di comando richiede il ricaricamento gli script stesso, per testare le modifiche. Invece di riavviare l'applicazione puoi però passare alla riga di comando, e digitare il comando `reload-scripts`.

##### Stabilire le scorciatoie

Per rendere gli script accessibili nel menu dell'applicazione e per potergli assegnare delle scorciatoie, gli script devono fornire un'appropriata intestazione. Nell'esempio sottostante entrambe le funzioni `sort` e `moveLinesDown` appaiono nel menu grazie alla seguente parte dell'intestazione dello script:

    var katescript = {
        ...
        "actions": [
            {   "function": "sort",
                "name": "Ordina il testo selezionato",
                "icon": "",
                "category": "Editing",
                "interactive": "false"
            },
            {   "function": "moveLinesDown",
                "name": "Sposta le righe in basso",
                "icon": "",
                "category": "Editing",
                "shortcut": "Ctrl+Shift+Down",
                "interactive": "false"
            }
        ]
    };

I campi necessari sono i seguenti:

- `function` [obbligatorio]: la funzione che dovrebbe comparire nel menu Strumenti Script.

- `name` [obbligatorio]: il testo che compare nel menu script.

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

- `category` [facoltativo]: se si specifica una categoria, lo script compare in un sottomenu.

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

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

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 `$`XDG_DATA_DIRS`/katepart5/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;, `$`XDG_DATA_HOME`/katepart5/libraries`, e includerlo nel tuo script con:

    require ("nome_del_mio_script.js");

In &Windows; questi file si trovano in `%USER%\AppData\Local\katepart5\libraries`. `%USER%` viene generalmente espanso in `C:\\Users\\`user``.

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, ovunque sia possibile, su cursori e intervalli. 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();`

    Cursor.setPosition(int riga, int colonna);

- Imposta la posizione del cursore a `riga` e `colonna`.

  Da: &kde; 4.11

    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.isEmpty();

- Restituisce `true` se i cursori di inizio e fine sono uguali.

  Esempio: `var empty = range.isEmpty();`

  Da: &kde; 4.11

    bool Range.isValid();

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

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

    Range 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, &ie; 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: in altre parole gli sviluppatori di &kappname; non devono preoccuparsi di estrarre e tradurre i messaggi. Va anche notato, però, che la traduzione funziona solo all'interno dell'infrastruttura di &kde;: &ie; nuove stringhe negli script di terze parti sviluppati al di fuori di &kde; non sarebbero tradotte. Tuttavia prendi in considerazione l'idea di contribuire con i tuoi script a &kate;, in modo che sia possibile una traduzione appropriata.

    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();

- Rimuove 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. Per migliorare la leggibilità del codice si raccomanda di usare le versioni con cursori o intervalli.

    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 oppure 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 oppure 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`, ⪚ se la riga < 0.

  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.

    bool document.isLineModified(int riga);

- Restituisce `true` se la `riga` attuale contiene dati non salvati.

  Da: &kde; 5.0

    bool document.isLineSaved(int riga);

- Restituisce `true` se la `riga` è cambiata ma il documento è stato salvato, e quindi la riga corrente non contiene dati non salvati.

  Da: &kde; 5.0

    bool document.isLineTouched(int riga);

- Restituisce `true` se la `riga` contiene dati non salvati o è stata cambiata in precedenza.

  Da: &kde; 5.0

    bool document.findTouchedLine(int startLine, bool giù);

- Cerca la successiva riga modificata, a partire da `riga`. La ricerca è eseguita verso l'alto o verso il basso, a seconda della direzione specificata in `giù`.

  Da: &kde; 5.0

    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()`. Chiamando `editBegin` viene usato internamente un contatore di riferimenti, &ie;, questa chiamata può essere annidata.

    void document.editEnd();

- Chiude un gruppo di modifica. L'ultima chiamata di `editEnd()` (&ie; 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, 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, 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 multi-riga per un `attributo`.

    String document.commentEnd(int attributo);

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

    Range document.documentRange();

- Restituisce un intervallo che comprende tutto il documento.

    Cursor documentEnd();

- Restituisce un cursore posizionato nell'ultima colonna dell'ultima riga del documento.

    bool isValidTextPosition(int riga, int colonna);
    bool isValidTextPosition(Cursor cursore);

- Restituisce `true` se la posizione del cursore ricade in una posizione di testo valida, cioè se è localizzata all'inizio, nel mezzo o alla fine di una riga valida. Una posizione di testo non è valida se si trova in un surrogato Unicode.

  Da: &kde; 5.0

    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.

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

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

  Vedi anche: le variabili nei 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 oppure 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 oppure 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, &ie; 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);

- Cerca 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`.