# Estendre la &katepart;

## Introducció

Igual que qualsevol editor de text avançat, la &katepart; ofereix una varietat de maneres d'estendre la seva funcionalitat. Podeu escriure scripts senzills per afegir funcionalitat amb JavaScript, afegir funcionalitat millorada al component d'edició amb Connectors del component d'edició. Finalment, un cop estengueu la &katepart;, sereu benvingut a unir-vos amb nosaltres i compartir les vostres millores amb el món!

## Treballar amb el ressaltat de la sintaxi

### Vista general

El ressaltat de la sintaxi és el que fa que l'editor mostri automàticament text en diferents estils/colors, depenent de la funció de la cadena en relació al propòsit del fitxer. En el codi font d'un programa, per exemple, les sentències de control es poden presentar en negreta, mentre que els tipus de dades i els comentaris poden tenir diferents colors que la resta del text. Això millora considerablement la llegibilitat del text, i ajuda a l'autor a ser més eficient i productiu.

Una funció de Perl, presentada amb ressaltat de la sintaxi.

Una funció de Perl, presentada amb ressaltat de la sintaxi.

La mateixa funció de Perl, sense ressaltat.

La mateixa funció de Perl, sense ressaltat.

Dels dos exemples, quin resulta més fàcil de llegir?

&kappname; compta amb un sistema de ressaltat de sintaxi flexible, configurable i capaç, la distribució estàndard proveeix definicions per a una gran varietat de llenguatges de programació, creació de scripts i de marques. A més podeu proveir les vostres pròpies definicions en simples fitxers &XML;.

&kappname; detectarà automàticament les regles de sintaxi correctes quan obriu un fitxer, basant-se en el tipus &MIME; del fitxer, determinat per la seva extensió, o, si no en té, pel seu contingut. Si l'elecció no és la correcta, podreu establir-la manualment des del menú Eines Ressaltat.

Els estils i colors usats per a cada definició de ressaltat de sintaxi es poden configurar usant la pestanya Estils text ressaltat del Diàleg de configuració, mentre que els tipus &MIME; i extensions de fitxer per als que s'hauran d'usar, es poden gestionar usant la pàgina Modes i tipus de fitxers.

El ressaltat de sintaxi té el seu ús en la millora de la llegibilitat del text, però no podeu confiar-hi per a validar que el text és correcte. Marcar el text en funció de la seva sintaxi pot ser difícil, depenent del format que s'estigui usant, i en alguns casos els autors de les regles de sintaxi poden estar orgullosos si es processa correctament el 98% del text, si bé caldrà un estil molt rar per a veure el 2% incorrecte.

Podeu descarregar actualitzacions o definicions de ressaltat de sintaxi addicionals des del lloc web de &kappname; fent clic en el botó Baixa els fitxers de ressaltat... a la pestanya Modes i tipus de fitxers del Diàleg de configuració.

### El sistema de ressaltat de la sintaxi del &kappname;

Aquesta secció tractarà sobre el mecanisme de ressaltat de la sintaxi del &kappname; amb més detall. Recomanem la seva lectura si desitgeu aprendre a sobre seu, o si desitgeu crear o canviar les definicions de sintaxi.

#### Com funciona

Sempre que obriu un fitxer, una de les primeres coses que fa l'editor del &kappname; és detectar quina definició de sintaxi s'usarà per al fitxer. Mentre va llegint el text del fitxer, i mentre hi va escrivint, el sistema de ressaltat de sintaxi analitza el text usant les regles establertes per la definició de sintaxi i marcant a on comencen i acaben els diferents contexts i estils.

Quan escriviu en el document, el text nou és analitzat i marcat al vol, de manera que si suprimiu un caràcter que marca el començament o el final d'un context, l'estil del text adjacent canviarà en conseqüència.

Les definicions de sintaxi utilitzades pel sistema de ressaltat de la sintaxi del &kappname; són fitxers &XML;, que contenen

- Regles per a detectar el paper del text, organitzades en blocs pel context

- Llistes de paraules clau

- Definicions d'elements d'estil

Quan s'analitza el text, les regles de detecció són avaluades en l'ordre en el que estan definides, i si el començament de la cadena actual coincideix amb la regla, s'usarà el context relacionat. El punt d'inici del text es mou al punt final en el que la regla coincideix i comença un nou cicle de regles, començant en el context establert per la regla coincident.

#### Regles

Les regles de detecció són el nucli del sistema de detecció de ressaltat. Una regla és una cadena, un caràcter o una expressió regular contra la que haurà de coincidir el text que s'està analitzant. Conté informació sobre l'estil a usar per a la part coincident del text. Es pot canviar el context de treball del sistema, ja sigui cap a un context mencionat explícitament o cap l'anterior context usat pel text.

Les regles s'organitzen en grups de context. Un grup de context s'usa per als conceptes del text principal dins del format, per exemple, les cadenes de text entre cometes o els blocs de comentaris en el codi font d'un programa. Això garanteix que el sistema de ressaltat no necessita realitzar un cicle per a totes les regles quan no és necessari, i que algunes seqüències de caràcters del text es poden tractar de forma diferent depenent del context actual.

En les regles és possible generar contexts dinàmicament per a permetre l'ús de dades específiques d'una instància.

#### Estils i paraules clau del context

En alguns llenguatges de programació, els números enters són tractats pel compilador (el programa que converteix el codi font en un executable binari) d'una forma diferent als de coma flotant, i poden haver-hi caràcters que tinguin un significat especial dins d'una cadena entre cometes. En aquests casos, té sentit processar-los de diferent manera que el text adjacent, per a que resultin fàcils d'identificar. De manera que si no representen contexts especials, poden ser vistos com a tals pel sistema de ressaltat de sintaxi, així que són marcats per a un processat diferent.

Una definició de sintaxi pot contenir tants estils com siguin requerits per a cobrir tots els conceptes del format per al que s'usa.

En molts formats hi ha llistes de paraules que representen un concepte específic. Per exemple, en els llenguatges de programació, les sentències de control són un concepte, els noms de tipus de dades un altra, i les funcions encastades en el llenguatge són un tercer. El sistema de ressaltat de sintaxi de &kappname; pot usar dites llistes per a detectar i marcar paraules en el text per emfatitzar conceptes dels formats de text.

#### Estils per omissió

Si obriu un fitxer de codi font de C++, un fitxer font de &Java; i un fitxer HTML en &kappname; podreu comprovar que tot i que els formats són diferents, i per tant les paraules que reben un tractament especial també són diferents, els colors usats són els mateixos. Això es deu a que &kappname; té una llista per omissió d'estils per omissió, que s'empren en les definicions de sintaxi individuals.

Això facilita el reconèixer conceptes similars en diferents formats de text. Per exemple, els comentaris estan presents en pràcticament qualsevol llenguatge de programació, creació de scripts o de marques, i si es presenten usant el mateix estil en tots els llenguatges, no haureu de parar-vos a pensar i identificar la seva posició en el text.

Tots els estils de definició de sintaxi usen un dels estils per omissió. Hi ha poques definicions de sintaxi que usin més estils dels que hi ha per omissió, així que, si useu un format molt sovint, potser us val la pena obrir el diàleg de configuració per a veure si alguns conceptes estan usant el mateix estil. Per exemple, tan sols hi ha un estil per omissió per a les cadenes, però com el llenguatge de programació Perl usa dos tipus de cadena, podeu millorar el ressaltat configurant ambdues de forma lleugerament diferent. Més endavant s'explicaran tots els estils per omissió disponibles.

### El format &XML; de definició del ressaltat

#### Vista general

Aquesta secció és una introducció al format &XML; de definició del ressaltat. Descriu els components principals, el seu significat i utilització. La següent secció entra en detalls amb les regles de detecció.

La definició formal, també coneguda com la DTD, es desa en el fitxer `language.dtd`, el qual hauria d'estar instal·lat a la carpeta `$`XDG_DATA_DIRS`/katepart5/syntax` del vostre sistema. En aquest sentit, la variable d'entorn `XDG_DATA_DIRS` normalment s'expandeix a `/usr/share`.

#### Principals seccions dels fitxers de definicions de ressaltat del &kappname;

Tots els fitxers de ressaltat contenen un capçalera que estableix la versió XML:

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

La part principal del fitxer de definició es l'element `languaje`. Els atributs disponibles són:

- Atributs requerits:

  `name` estableix el nom del llenguatge. Després apareixerà als menús i als diàlegs.

  `section` especifica la categoria.

  `extensions` defineix les extensions dels fitxers, com "*.cpp;*.h"

  Atributs opcionals:

  `mimetype` fitxers associats amb el tipus &MIME;.

  `version` especifica la versió actual del fitxer de definició.

  `kateversion` especifica l'última versió implementada del &kappname;.

  `casesensitive` defineix quan les paraules clau són o no sensibles a majúscules i minúscules.

  `priority` es necessària si una altra definició de ressaltat usa les mateixes extensions. S'usarà la de major prioritat.

  `author` conté el nom de l'autor i la seva adreça de correu electrònic.

  `license` conté la llicència, normalment LPGL, Artística, GPL i d'altres.

  `style` conté el llenguatge proporcionat i és utilitzat pels sagnadors per a l'atribut `required-syntax-style`.

  `hidden` defineix quan hauria d'aparèixer el nom en els menús de &kappname;.

  De manera que la línia següent pot tenir un aspecte similar a:

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

A continuació estaria l'element `highlighting`, el qual conté l'element opcional `list` i els elements requerits `contexts` i `itemDatas`.

- Els elements `list` contenen una llista de paraules clau. En aquest cas les paraules clau són class i const. Podeu afegir tantes llistes com us calguin.

  L'element `contexts` conté tots els contexts. El primer és l'usat per omissió i amb aquest s'iniciarà el ressaltat. Hi ha dues regles en el context Normal Text, que faran coincidir la llista de paraules clau amb el nom algun_nom i una regla que detecta una cometa i canvia el context a cadena. Per aprendre més sobre les regles llegiu el següent capítol.

  La tercera part és l'element `itemDatas`. Conté tots els colors i tipus de lletra que necessiten els contexts i les regles. En aquest exemple, s'usen `itemData` Normal Text, String i Keyword.

      <highlighting>
          <list name="algun_nom">
            <item> class </item>
            <item> const </item>
          </list>
          <contexts>
            <context attribute="text_normal" lineEndContext="#pop" name="text_normal" >
              <keyword attribute="paraula_clau" context="#stay" String="algun_nom" />
              <DetectChar attribute="cadena" context="string" char="&quot;" />
            </context>
            <context attribute="cadena" lineEndContext="#stay" name="cadena" >
              <DetectChar attribute="cadena" context="#pop" char="&quot;" />
            </context>
          </contexts>
          <itemDatas>
            <itemData name="text_normal" defStyleNum="dsNormal" />
            <itemData name="paraula_clau" defStyleNum="dsParaula_clau" />
            <itemData name="cadena" defStyleNum="dsCadena" />
          </itemDatas>
        </highlighting>

L'última part de la definició de ressaltat és la secció opcional `general`. Pot contenir informació sobre paraules clau, plegat de codi, comentaris i sagnat.

- La secció `comment` defineix amb quina cadena s'introdueix un comentari en una línia senzilla. També podeu definir un comentari en múltiples línies usant multiLine amb l'atribut addicional end. Això s'usa si l'usuari prem la drecera corresponent per a comenta/descomenta.

  La secció `keywords` defineix si les llistes de paraules clau són sensibles a majúscules i minúscules o no. Més endavant s'explicaran d'altres atributs.

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

#### Les seccions al detall

Aquesta part descriu tots els atributs disponibles per als contexts, llistes de dades, paraules clau, comentaris, plegat de codi i sagnat.

L'element `context` pertany al grup `contexts`. Un context defineix les regles específiques de context que s'han de seguir quan el sistema de ressaltat abasta el final d'una línia. Els atributs disponibles són:

- `name` estableix el nom del context. Les regles usaran el nom per especificar el context al que canviar si les regles coincideixen.

  `lineEndContext` defineix el context al que canviarà el sistema de ressaltat si abasta el final de la línia. Pot ser un nom o un altra context, `#stay` permetrà que no es canviï el context (&pex;, no fer res) o `#pop` farà que deixi aquest context. És possible usar per exemple `#pop#pop#pop` per a sortir tres vegades, o fins i tot `#pop#pop!AltreContext` per a que aparegui dues vegades i canviar a un context anomenat `AltreContext`.

  `lineEmptyContext` defineix el context si es troba una línia buida. Per omissió: #stay.

  `fallthrough` defineix si el sistema de ressaltat canviarà al context especificat en fallthroughtContext si no coincideixen les regles. Per omissió: false.

  `fallthroughContext` especifica el context següent si no hi ha regles que coincideixin.

  `dynamic` si està a true, el context recordarà cadenes/marcadors de posició desats per les regles dinàmiques. Això es necessita per als documents HERE, per exemple. Per omissió: false.

L'element `itemData` es troba en el grup `itemDatas`. Defineix l'estil i els colors dels tipus de lletra. Per tant és possible definir els vostres propis estils i colors. Encara que recomanem usar els estils per omissió, atès que així l'usuari veurà colors homogenis per als diferents llenguatges. Si bé, algunes vegades no hi ha altres possibilitats i és necessari canviar el color i els atributs dels tipus de lletra. Els atributs «name» i «defStyleNum» són necessaris, els altres són opcionals. Els atributs disponibles són:

- `name` estableix el nom del «itemData». Els contexts i les regles usaran aquest nom en els seus atributs attribute per a fer referència a un «itemData».

  `defStyleNum` defineix quin estil s'usarà per omissió. Més endavant s'explicaran els estils per omissió disponibles.

  `color` defineix un color. Els formats vàlids són «#rrggbb» o «#rgb».

  `selColor` defineix el color de la selecció.

  `italic` si està a true, el text es mostrarà en cursiva.

  `bold` si està a true, el text es mostrarà en negreta.

  `underline` si està a true, el text es mostrarà subratllat.

  `strikeout` si està a true, el text es mostrarà taxat.

  `spellChecking` si està a true, el text es mostrarà amb la verificació ortogràfica.

L'element `keywords` en el grup `general` defineix les propietats «keyword». Els atributs disponibles són:

- `casesensitive` pot ser true o false. Si està a true, totes les paraules clau seran sensibles a majúscules i minúscules.

  `weakDeliminator` és una llista de caràcters que no actuen com a delimitadors de paraules (delimitador feble). Per exemple, el punt `'.'` és un delimitador de paraula. Si tenim una paraula clau en una `list` que conté un punt, tan sols la trobareu si especifiqueu el punt com a delimitador feble.

  `additionalDeliminator` defineix delimitadors addicionals.

  `wordWrapDeliminator` defineix els caràcters al darrera dels quals pot ocórrer un ajust de línia.

  Els delimitadors per omissió i els d'ajust de línia són els caràcters `.():!+,-<=>%&*/;?[]^{|}~\`, espai (`' '`) i tabulació (`'\t'`).

L'element `comment` en el grup `comments` defineix les propietats dels comentaris emprats per Eines Comenta i Eines Descomenta. Els atributs disponibles són:

- `name` pot ser singleLine o multiLine. Si escolliu multiLine es necessiten els atributs end i region.

  `start` defineix la cadena que s'usa per iniciar un comentari. En C++ seria "/*".

  `end` defineix la cadena usada per a tancar un comentari. En C++ seria "*/".

  `region` serà el nom amb el que es desarà el comentari multilínia. Si assumim que tenim una regió beginRegion="Comentari" ... endRegion="Comentari" en les regles, haureu d'usar region="Comentari". D'aquesta manera es descomentarà fins i tot si no heu seleccionat tot el text en un comentari multilínia. El cursor només haurà d'estar dins del comentari multilínia.

L'element `folding` en el grup `general` defineix les propietats del plegat de codi. Els atributs disponibles són:

- `indentationsensitive` si està a true, els marcadors de plegat de codi seran afegits al sagnat, com en el llenguatge per a la creació de scripts en Python. Normalment no us caldrà establir-lo, pel que per omissió és false.

L'element `indentation` en el grup `general` defineix quin sagnat s'usarà. Encara que us recomanem fervorosament que l'ometeu, atès que el sagnat sol ser establert en el tipus de fitxer o en afegir el mode de línia al fitxer de text. Tot i que si especifiqueu un sagnat, podreu forçar un sagnat específic per a un usuari, per un altra que us agradi més. Els atributs disponibles són:

- `mode` és el nom del sagnat. Els sagnats disponibles a la dreta són: normal, cstyle, haskell, lilypond, lisp, python, ruby i xml.

#### Estils per omissió disponibles

Els estils per omissió ja s'han explicat, a manera de resum: Els estils per omissió estan predefinits per als estils de colors i tipus de lletra.

Estils per omissió en general:

- `dsNormal`, quan no es requereix un ressaltat especial.

  `dsKeyword`, per a les paraules clau incloses.

  `dsFunction`, per a crides a funcions i definicions.

  `dsVariable`, si és aplicable: noms de les variables (p. ex. $algunaVar als llenguatges PHP/Perl).

  `dsControlFlow`, controla el flux de paraules clau com «if», «else», «switch», «break», «return», «yield»...

  `dsOperator`, operadors com + - * / :: < >

  `dsBuiltIn`, funcions, classes i objectes inclosos.

  `dsExtension`, extensions comunes, com les classes de Qt i les funcions/macros en els llenguatges C++ i Python.

  `dsPreprocessor`, per a les declaracions del pre-processador o per a les definicions de macros.

  `dsAttribute`, anotacions com «@override» i «__declspec(...)».

Estils per omissió relacionats amb les cadenes:

- `dsChar`, per a caràcters sols, com ara «x».

  `dsSpecialChar`, caràcters amb un significat especial en cadenes com escapades, substitucions o els operadors d'expressions regulars.

  `dsString`, per a cadenes com «hello world».

  `dsVerbatimString`, cadenes literals o crues com «raw \backlash» en els llenguatges Perl, CoffeeScript i intèrprets d'ordres, així com «r'\raw'» en llenguatge Python.

  `dsSpecialString`, SQL, expressions regulars, documentació HERE, mode matemàtic del LaTeX...

  `dsImport`, per a importar, incloure o requerir mòduls.

Estils per omissió relacionats amb números:

- `dsDataType`, tipus de dades incloses com «int», «void», «u64».

  `dsDecVal`, valors decimals.

  `dsBaseN`, per als valors en una base diferent de 10.

  `dsFloat`, per a valors de coma flotant.

  `dsConstant`, definicions incloses i definides per l'usuari com PI.

Estils per omissió relacionats amb la documentació i els comentaris:

- `dsComment`, per a comentaris.

  `dsDocumentation`, «/** Comentaris de documentació */» o «"""cadenes_de_documentació"""».

  `dsAnnotation`, ordres de la documentació com «@param», «@brief».

  `dsCommentVar`, els noms de les variables utilitzades en les ordres anteriors, com «foobar» a «@param foobar».

  `dsRegionMarker`, per a marcadors de regió com els comentaris «//BEGIN», «//END».

Altres estils per omissió:

- `dsInformation`, notes i consells como «@note» al doxygen.

  `dsWarning`, avisos com «@warning» al doxygen.

  `dsAlert`, paraules especials com «TODO», «FIXME», «XXXX».

  `dsError`, per a errors de ressaltat i sintaxi incorrecta.

  `dsOthers`, quan res més s'hi ajusti.

### Regles per a la detecció del ressaltat

Aquesta secció descriu les regles per a la detecció del ressaltat.

Cada regla pot coincidir en cap o amb varis caràcters al començament de la cadena amb la que es comparen. Si la regla coincideix, als caràcters coincidents se'ls assigna l'estil o attribute definit per la regla, tan mateix una regla pot demanar que es canviï el context actual.

Una regla té aquest aspecte:

    <NomRegla attribute="(identificador)" context="(identificador)" [atributs específics de la regla] />

L'attribute identifica l'estil que usaran els caràcters coincidents per nom, i el context identifica el context a usar des d'aquí.

El context es pot identificar per:

- Un identifier, que és el nom dels altres contexts.

- Una order us indica al motor que romandrà en el context actual (`#stay`), o que salti al context anterior (`#pop`).

  Per a retrocedir més passos, es pot repetir la paraula clau #pop: `#pop#pop#pop`

- Una ordre seguida per un signe d'exclamació (!) i un identificador, el qual farà que el motor segueixi primer l'ordre i després passi a l'altre context, &pex;, `#pop#pop!AltreContext`.

Algunes regles poden tenir regles fill que s'executen únicament si la regla pare resulta aplicable. A tota la cadena coincident se us donarà l'atribut definit per la regla pare. Una regla amb regles fills té aquest aspecte:

    <NomRegla (atributs)>
      <NomReglaFill (atributs) />
      ...
    </NomRegla>

Els atributs específics de la regla varien, i es descriuen en les següents seccions.

### Atributs comuns

Totes les regles tenen els següents atributs comuns i estan disponibles sempre que apareixen `(atributs comuns)`. attribute i context són atributs requerits, els demés són opcionals.

- attribute: Un mapa d'atributs d'un definit itemData.

- context: Especifica el context al que canviarà el sistema de ressaltat si les regles coincideixen.

- beginRegion: Inicia un bloc de plegat de codi. Per omissió: unset.

- endRegion: Tanca un bloc de plegat de codi. Per omissió: unset.

- lookAhead: Si està a true, el sistema de ressaltat no processarà les longituds coincidents. Per omissió: false.

- firstNonSpace: Tan sols coincidiran si la cadena no conté un espai en blanc al començament de la línia. Per omissió: false.

- column: Tan sols coincideix, si la columna coincideix. Per omissió: unset.

### Regles dinàmiques

Algunes regles permeten l'atribut opcional `dynamic` de tipus lògic que per omissió és false. Si dynamic està a true, la regla podrà usar arguments que representin el text coincident amb una regla d'una expressió regular que canviï al context actual per al contingut en els atributs `string` o `char`. En un `string`, l'argument `%N` (a on N és un número) se substituirà amb la corresponent `N` capturada des de l'expressió regular cridada. En un `char` l'argument haurà de ser un número `N` i serà substituït amb el primer caràcter de la corresponent `N` capturada des de l'expressió regular cridada. Sempre que un regla permeti aquest atribut haurà de contenir un (dynamic).

- dinàmic: pot ser (true|false).

#### Les regles en detall

DetectChar

- Detecta un únic caràcter específic. Normalment s'usa per a trobar el final de les cadenes entre cometes.

      <DetectChar char="(caràcter)" (atributs comuns) (dinàmic) />

  L'atribut `char` defineix el caràcter a comparar.

Detect2Chars

- Detecta dos caràcters especificats en l'ordre definit.

      <Detect2Chars char="(caràcter)" char1="(caràcter)" (atributs comuns) (dinàmic) />

  L'atribut `char` defineix el primer caràcter a comparar, `char1` el segon.

AnyChar

- Detecta un caràcter d'un conjunt de caràcters especificats.

      <AnyChar String="(cadena)" (atributs comuns) />

  L'atribut `String` defineix el conjunt de caràcters.

StringDetect

- Detecta una cadena exacta.

      <StringDetect String="(cadena)" [insensitive="true|false"] (atributs comuns) (dinàmic) />

  L'atribut `String` defineix la cadena a comparar. L'atribut `insensitive` per omissió és a `false` i es passa a la funció de comparació de cadena. Si el valor és `true` la comparació no serà sensible a majúscules i minúscules.

WordDetect

- Detectar una cadena exacta més requereix límits de paraula com un punt `«.»` o un espai en blanc al començament i al final de la paraula. Penseu en `\b<cadena>\b` en termes d'una expressió regular, però és més ràpid que la regla `RegExpr`.

      <WordDetect String="(cadena)" [insensitive="true|false"] (atributs comuns) (dinàmic) />

  L'atribut `String` defineix la cadena a comparar. L'atribut `insensitive` per omissió és a `false` i es passa a la funció de comparació de cadena. Si el valor és `true` la comparació no serà sensible a majúscules i minúscules.

  Des de: Kate 3.5 (KDE 4.5)

RegExpr

- Cerca la coincidència amb una expressió regular.

      <RegExpr String="(cadena)" [insensitive="true|false"] [minimal="true|false"] (atributs comuns) (dinàmic) />

  L'atribut `String` defineix l'expressió regular.

  `insensitive` per omissió és a `false` i és passada al motor d'expressions regulars.

  `minimal` per omissió és a `false` i és passada al motor d'expressions regulars.

  Atès que les regles coincideixen amb el començament de la cadena actual, una expressió regular que comenci amb l'accent circumflex (`^`) indica que la regla tan sols s'haurà de comparar amb el començament d'una línia.

  Mireu la secció sobre expressions regulars per a obtenir més informació.

keyword

- Detecta una paraula clau des d'una llista especificada.

      <keyword String="(nom de la llista)" (atributs comuns) />

  L'atribut `String` identifica la llista de paraules clau pel seu nom. Haurà d'existir una llista amb aquest nom.

  El sistema de ressaltat processa regles de paraules clau d'una manera molt optimitzada. Això fa que sigui una necessitat absoluta que qualsevol paraula clau que coincideixi necessitarà estar envoltada pels delimitadors definits, ja sigui implícitament (els delimitadors per omissió), o explícitament especificat dins la propietat additionalDeliminator de l'etiqueta keywords.

  Si una paraula clau coincideix haurà de contenir un caràcter de delimitador, aquest caràcter respectiu haurà d'afegir-se a la propietat weakDeliminator de l'etiqueta keywords. Aquest caràcter perdrà la seva propietat delimitadora en totes les regles keyword.

Int

- Detecta un número enter.

      <Int (atributs comuns) (dinàmic) />

  Aquesta regla no té atributs específics. Les regles fill normalment s'usen per a detectar combinacions de `L` i `U` després del número, indicant el tipus d'enter en el codi del programa. En realitat s'admeten totes les regles com a regles fill, tot i que, el `DTD` tan sols permet la regla fill `StringDetect`.

  El següent exemple troba números enters seguits del caràcter «L».

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

Flotant

- Detecta un número de coma flotant.

      <Float (atributs comuns) />

  Aquesta regla no té atributs específics. Es permet `AnyChar` com a regla fill i normalment s'usa per a detectar combinacions, mireu la regla `Int` com a referència.

HlCOct

- Detecta una representació numèrica d'un número octal.

      <HlCOct (atributs comuns) />

  Aquesta regla no té atributs específics.

HlCHex

- Detecta una representació numèrica d'un número hexadecimal.

      <HlCHex (atributs comuns) />

  Aquesta regla no té atributs específics.

HlCStringChar

- Detecta un caràcter escapat.

      <HlCStringChar (atributs comuns) />

  Aquesta regla no té atributs específics.

  Localitza representacions literals de caràcters que s'usen habitualment en el codi de programació, per exemple `\n` (nova línia) o `\t` (tabulació).

  Els següents caràcters coincideixen amb la regla si segueixen a una barra invertida (`\`): `abefnrtv"'?\`. A més seran vàlids els números hexadecimals escapats com per exemple `\xff`, i els números octals escapats, per exemple `\033`.

HlCChar

- Detecta un caràcter C.

      <HlCChar (atributs comuns) />

  Aquesta regla no té atributs específics.

  Localitza caràcters C tancats en una marca (Exemple: `'c'`). La marca pot ser un caràcter simple o un caràcter escapat. Veure «HICStringChar» per a localitzar seqüències de caràcters escapats.

RangeDetect

- Detecta una cadena amb caràcters d'inici i de final definits.

      <RangeDetect char="(caràcter)"  char1="(caràcter)" (atributs comuns) />

  `char` defineix el caràcter que inicia l'interval, `char1` el caràcter que finalitza l'interval.

  És molt útil per a detectar per exemple petites cadenes entre cometes i similars, però tingueu en compte que el motor de ressaltat tan sols pot treballar amb una línia alhora, de manera que no es detectaran cadenes que estiguin dividides en dues línies o més.

LineContinue

- Coincideix amb un caràcter específic al final d'una línia.

      <LineContinue (atributs comuns) [char="\"] />

  L'atribut `char` defineix un caràcter opcional a comparar, per defecte és la barra invertida (`'\'`). Nou des del &kde; 4.13.

  Aquesta regla és pràctica per a canviar el context al final de la línia. Això és necessari per exemple en C/C++ per a continuar macros o cadenes.

IncludeRules

- Inclou regles des d'un altra context o llenguatge/fitxer.

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

  L'atribut `context` defineix el context a incloure.

  Si és una cadena simple, inclourà totes les regles definides en el context actual, exemple:

      <IncludeRules context="anotherContext" />

  Si la cadena conté un `##` el sistema de ressaltat cercarà un context d'una altra definició del llenguatge amb el nom indicat, per exemple,

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

  inclouria el context String des de la definició de ressaltat de C++.

  Si l'atribut `includeAttrib` està a true, canvia l'atribut de destinació per un altra de la font. Això és necessari, per exemple, per al treball de comentar, si el text coincideix amb el context inclòs s'usarà un ressaltat diferent que amb el context amfitrió.

DetectSpaces

- Detecta espais en blanc.

      <DetectSpaces (atributs comuns) />

  Aquesta regla no té atributs específics.

  Useu aquesta regla si sabeu que hi poden haver varis espais en blanc al davant, per exemple, al començament de les línies sagnades. Aquesta regla ometrà tots els espais en blanc a la vegada, en comptes de comprovar múltiples regles i saltar si no hi ha coincidències.

DetectIdentifier

- Detecta identificadors de cadenes (com una expressió regular: [a-zA-Z_][a-zA-Z0-9_]*).

      <DetectIdentifier (atributs comuns) />

  Aquesta regla no té atributs específics.

  Useu aquesta regla per a saltar d'una vegada una cadena de paraula de caràcters, en comptes de comprovar múltiples regles i saltar si no hi ha coincidències.

#### Consells i trucs

Una vegada que hageu entès com funciona el canvi de context serà fàcil escriure definicions de ressaltat. Tot i que hauria de tenir cura de comprovar quina situació s'hauria de seleccionar una regla. Les expressions regulars són molt potents, però són lentes en comparació amb d'altres regles. Per això haureu de tenir en compte els següents consells.

- Si tan sols heu de localitzar dos caràcters useu `Detect2Chars` en comptes de `StringDetect`. El mateix s'aplica a `DetectChar`.

- Les expressions regulars són fàcils d'usar però a vegades hi ha formes molt més ràpides d'obtenir el mateix resultat. Imagineu que tan sols desitgeu localitzar el caràcter `'#'` si aquest és el primer caràcter de la línia. Una solució basada en una expressió regular seria quelcom semblant a això:

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

  Podeu aconseguir el mateix molt més ràpid usant:

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

  Si desitgeu que l'expressió regular localitzi `'^#'` també podeu usar `DetectChar` amb l'atribut `column="0"`. L'atribut `column` compta els caràcters, per tant el tabulador és tan sols un caràcter.

- Podeu canviar de context sense processar caràcters. Suposeu que desitgeu canviar de context quan trobeu una cadena `*/`, però us cal processar aquesta cadena en el següent context. La regla de a sota coincidirà, i l'atribut `lookAhead` farà que es desi la cadena coincident per al següent context.

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

- Useu `DetectSpaces` si sabeu quants espais en blanc hi ha.

- Useu `DetectIdentifier` en comptes de l'expressió regular `'[a-zA-Z_]\w*'`.

- Usa els estils per omissió sempre que es pugui. D'aquesta manera l'usuari es trobarà un entorn familiar.

- Mireu d'altres fitxers XML per a comprovar de quina forma implementen regles delicades les altres persones.

- Podeu validar cadascun dels fitxers XML usant l'ordre `xmllint --schema llenguatge.xsd mevaSintaxi.xml`.

- Si tot sovint repetiu expressions regulars complexes podeu usar ENTITIES. Exemple:

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

  Ara podeu usar &la_meva_ref; en comptes de l'expressió regular.

## Crear scripts amb JavaScript

El component d'edició del &kappname; és fàcilment extensible, escrivint scripts. El llenguatge per crear scripts és ECMAScript (conegut com Javascript). &kappname; admet dos tipus de script: de sagnat i de línia d'ordres.

### Scripts de sagnat

Els scripts de sagnat: També coneguts com «indenters», sagnen automàticament el codi font en escriure text. Com a exemple, després de prémer la tecla de retorn el nivell de sagnat sovint és incrementat.

En les següents seccions es descriuen pas a pas com crear l'esquelet d'un sagnat simple. Com a primer pas, creeu una nou fitxer `*.js` anomenat &pex;, `javascript.js` a la carpeta d'inici local `$`XDG_DATA_HOME`/katepart5/script/indentation`. En aquest sentit, la variable d'entorn `XDG_DATA_HOME` normalment s'expandeix a `~/.local` o `~/.local/share`.

#### La capçalera de l'script de sagnat

La capçalera del fitxer `javascript.js` està inclosa com un JSON al començament del document de la forma següent:

    var katescript = {
        "name": "JavaScript",
        "author": "Nom exemple <nom.exemple@alguna.adreça.org>",
        "license": "BSD License",
        "revision": 1,
        "kate-version": "5.1",
        "required-syntax-style": "javascript",
        "indent-languages": ["javascript"],
        "priority": 0,
    }; // kate-script-header, haurà d'estar al començament del fitxer sense comentaris

Cada entrada s'explica en detall tot seguit:

- `name` [requerit]: Aquest és el nom del sagnat que apareix al menú Eines Sagnat i en el diàleg de configuració.

- `author` [opcional]: El nom de l'autor i la informació de contacte.

- `license` [opcional]: La forma curta de la llicència, com ara BSD o LGPLv3.

- `revision` [requerit]: La revisió de l'script. Aquest número ha de ser major cada vegada que l'script es modifica.

- `kate-version` [requerit]: La versió mínima requerida per &kappname;.

- `required-syntax-style` [opcional]: L'estil de la sintaxi requerida, el qual coincideix amb `style` especificat als fitxers de ressaltat de la sintaxi. Això és important per als sagnats que es basen en la informació de ressaltat específica en el document. Si s'especifica un estil de sintaxi requerit, el sagnat només estarà disponible amb el ressaltat actiu apropiat. Això evita «comportament sense definir» causat per l'ús del sagnat sense l'esquema de ressaltat esperat. Per exemple, el sagnat de Ruby en fa ús en els fitxers `ruby.js` i `ruby.xml`.

- `indent-languages` [opcional]: Una matriu JSON dels estils de la sintaxi que pot sagnar correctament, &pex;: `["c++", "java"]`.

- `priority` [opcional]: Si els diversos sagnats són adequats per a un determinat fitxer ressaltat, la prioritat decideix quin sagnat és triat com sagnat per omissió.

#### El codi font del sagnat

Després d'haver especificat la capçalera aquesta secció explica com funciona la creació de scripts de sagnat. L'esquelet bàsic del cos s'assembla a això:

    // es necessiten les biblioteques «js» de katepart, per exemple, «range.js»
    // si utilitzeu «Range»
    require ("range.js");

    triggerCharacters = "{}/:;";
    function indent(line, indentWidth, ch)
    {
        // crida per a cada línia nova (ch == «\n») i tots els caràcters s'especifiquen en
        // la variable global triggerCharacters. Quan es crida EinesAlinea
        // la variable ch és buidada, &ead;, ch == «».
        //
        // Veure també: L'API per a la creació de scripts
        return -2;
    }

La funció `indent()` té tres paràmetres:

- `line`: La línia que ha d'estar amb sagnat.

- `indentWidth`: L'amplada del sagnat en nombre d'espais.

- `ch`: o bé un caràcter de línia nova (`ch == '\n'`),el caràcter de tall especificat en `triggerCharacters` o buida si l'usuari invoca l'acció Eines Alinea.

El valor retornat de la funció `indent()` especifica com se sagna la línia. Si el valor retornat és un nombre enter simple, aquest s'interpreta de la següent manera:

- El valor retornat `-2`: No fa res.

- El valor retornat `-1`: Es manté el sagnat (cerca la línia anterior que no estigui en blanc).

- El valor retornat `0`: Un número >= 0 especifica la profunditat del sagnat en nombre d'espais.

Alternativament, un conjunt de dos elements es poden retornar:

- `return [ indent, align ];`

En aquest cas, el primer element és la profunditat de sagnat com anteriorment amb el mateix significat dels valors especials. No obstant, el segon element és un valor absolut que representa una columna d'«alineació». Si aquest valor és major que el valor de sagnat, la diferència representa un nombre d'espais a afegir després del sagnat del primer paràmetre. En cas contrari, el segon nombre serà ignorat. L'ús de tabulacions i espais per al sagnat sovint és referit com «mode mixt».

Considerem el següent exemple: Suposem que s'usen tabulacions per a sagnar, i l'amplada de la tabulació és 4. Aquí, <tab> representa una tabulació i «.» un espai:

    1: <tab><tab>foobar("hola",
    2: <tab><tab>......."món");

Quan se sagna la línia 2, la funció `indent()` retorna [8, 15]. Com a resultat, s'insereixen dues tabulacions per a sagnar fins a la columna 8, i s'afegeixen 7 espais per alinear el segon paràmetre a la primera, de manera que quedi alineat si el fitxer es veu amb una amplada de tabulació diferent.

Una instal·lació per omissió del &kde; ens dóna el &kappname; amb diversos sagnats. El corresponent codi font de JavaScript d'origen pot trobar-se en `$`XDG_DATA_DIRS`/katepart5/script/indentation`.

El desenvolupament d'un sagnat requereix tornar a carregar els scripts per veure si els canvis es comporten adequadament. En comptes de reiniciar l'aplicació, simplement canvieu a la línia d'ordres i crideu l'ordre `reload-scripts`.

Si desenvolupeu scripts útils, si us plau, considereu el contribuir al projecte &kappname; posant-vos en contacte amb la llista de correu.

### Els scripts de la línia d'ordres

Com és difícil satisfer les necessitats de tothom, el &kappname; suporta unes quantes eines d'ajuda per a la manipulació ràpida de text a través de la línia d'ordres encastada. Per exemple, l'ordre `sort` s'implementa com un script. En aquesta secció s'explica com crear fitxers `*.js` per estendre el &kappname; amb scripts d'ajuda arbitrària.

Scripts de línia d'ordres es troben en la mateixa carpeta que els scripts de sagnat. Així que com a primer pas, creeu un nou fitxer `*.js` anomenat `myutils.js` a la carpeta d'inici local `$`XDG_DATA_HOME`/katepart5/script/commands`. En aquest sentit, la variable d'entorn `XDG_DATA_HOME` normalment s'expandeix a `~/.local` o `~/.local/share`.

#### La capçalera de l'script de línia d'ordres

La capçalera del fitxer `javascript.js` està inclosa en el JSON al començament de l'script de la forma següent:

    var katescript = {
        "author": "Nom exemple <nom.exemple@alguna.adreça.org>",
        "license": "LGPLv2+",
        "revision": 1,
        "kate-version": "5.1",
        "functions": ["sort", "moveLinesDown"],
        "actions": [
            {   "function": "sort",
                "name": "Sort Selected Text",
                "category": "Editing",
                "interactive": "false"
            },
            {   "function": "moveLinesDown",
                "name": "Move Lines Down",
                "category": "Editing",
                "shortcut": "Ctrl+Shift+Down",
                "interactive": "false"
            }
        ]
    }; // kate-script-header, haurà d'estar al començament del fitxer sense comentaris

Cada entrada s'explica en detall tot seguit:

- `author` [opcional]: El nom de l'autor i la informació de contacte.

- `license` [opcional]: La forma curta de la llicència, com ara BSD o LGPLv2.

- `revision` [requerit]: La revisió de l'script. Aquest número ha de ser major cada vegada que l'script es modifica.

- `kate-version` [requerit]: La versió mínima requerida per &kappname;.

- `functions` [requerit]: Matriu JSON de les ordres a l'script.

- `actions` [opcional]: La matriu JSON dels objectes JSON que defineixen les accions que apareixen al menú de l'aplicació. Es proporciona informació detallada a la secció Vincular dreceres.

Atès que el valor de `functions` és una matriu JSON, un únic script és capaç de contenir un nombre arbitrari d'ordres de la línia d'ordres. Cada funció està disponible a través de la línia d'ordres integrada al &kappname;.

#### El codi font de l'script

Totes les funcions especificades a la capçalera s'han d'implementar a l'script. Per exemple, el fitxer de script en l'exemple anterior necessita implementar les dues funcions `sort` i `moveLinesDown`. Totes les funcions tenen la següent sintaxi:

    // es necessiten les biblioteques «js» de katepart, per exemple, «range.js»
    // si utilitzeu «Range»
    require ("range.js");

    function <nom>(arg1, arg2...)
    {
        // «...» implementació, veure també: L'API per a la creació de scripts.
    }

Els arguments en la línia d'ordres es passen a la funció com `arg1`, `arg2`, &etc; Per tal de proveir documentació per a cada ordre, simplement implementeu la funció «`help`» de la següent manera:

    {
        if (cmd == "sort") {
            return i18n("Ordena el text seleccionat.");
        } else if (cmd == "...") {
            // ...
        }
    }

Executar `help sort` en la línia d'ordres crida a aquesta funció d'ajuda amb l'argument `cmd` establert en l'ordre donada, &ead;, `cmd == "sort"`. &kappname; presentarà el text retornat com a documentació per a l'usuari. Assegureu-vos de traduir les cadenes.

El desenvolupament d'un script de línia d'ordres requereix tornar a carregar els scripts per veure si els canvis es comporten adequadament. En comptes de reiniciar l'aplicació, simplement canvieu a la línia d'ordres i crideu l'ordre `reload-scripts`.

##### Vincular dreceres

Per tal de fer que els scripts siguin accessibles al menú de l'aplicació i assignar dreceres, l'script ha de proporcionar una capçalera de script adequada. En l'exemple anterior, ambdues funcions `sort` i `moveLinesDown` apareixen al menú degut a la següent part a la capçalera de l'script:

    var katescript = {
        ...
        "actions": [
            {   "function": "sort",
                "name": "Sort Selected Text",
                "icon": "",
                "category": "Editing",
                "interactive": "false"
            },
            {   "function": "moveLinesDown",
                "name": "Move Lines Down",
                "icon": "",
                "category": "Editing",
                "shortcut": "Ctrl+Shift+Down",
                "interactive": "false"
            }
        ]
    };

Els camps per a una acció són els següents:

- `function` [requerit]: La funció que ha d'aparèixer al menú Eines Scripts.

- `name` [requerit]: El text apareix al menú de l'script.

- `icon` [opcional]: La icona apareix al costat del text en el menú. Aquí es poden usar tots els noms d'icones del &kde;.

- `category` [opcional]: Si s'especifica una categoria, l'script apareixerà en un submenú.

- `shortcut` [opcional]: La drecera que aquí és la drecera per omissió. Exemple: `Ctrl+Alt+t`. Per a més detalls consulteu la Documentació de Qt.

- `interactive` [opcional]: Si l'script necessita usar l'entrada a la línia d'ordres, establiu-ho a `true` (vertader).

Si desenvolupeu scripts útils, si us plau, considereu el contribuir al projecte &kappname; posant-vos en contacte amb la llista de correu.

### L'API per a la creació de scripts

L'API per a la creació de scripts que es presenta aquí està disponible per a tots els scripts, &pex;, els scripts de sagnat i una ordre de línia d'ordres. Les classes `Cursor` i `Range` són proporcionades pels fitxers de la biblioteca a `$`XDG_DATA_DIRS`/katepart5/libraries`. Si voleu utilitzar-los en el seu vostre script, serà necessari utilitzar algunes de les funcions `Document` o `View`, si us plau, afegiu la biblioteca necessària mitjançant:

    // es necessiten les biblioteques «js» de katepart, per exemple, «range.js»
    // si utilitzeu «Range»
    require ("range.js");

Per estendre la norma de l'API per a la creació de scripts amb les vostres pròpies funcions i prototips n'hi ha prou amb crear un nou fitxer a la carpeta de configuració local del KDE `$`XDG_DATA_HOME`/katepart5/libraries` i incloure'l a l'script utilitzant:

    require ("nom_script.js");

Per estendre els prototips com `Cursor` o `Range`, la manera més recomanable és no modificar els fitxers `*.js` globals. En el seu lloc, canvieu el prototip `Cursor` en JavaScript després afegiu el `cursor.js` al vostre script mitjançant `require`.

#### Cursors i intervals

Com &kappname; és un editor de text, tota l'API per a la creació de scripts es basa en els cursors i els intervals sempre que sigui possible. Un Cursor és una simple `(line, column)` que representa una posició del text en el document. Un «Range» s'estén pel text des de la posició del cursor fins a una posició final del cursor. L'API s'explica amb detall en les següents seccions.

##### El prototip de «Cursor»

    Cursor();

- Constructor. Retorna un cursor a la posició `(0, 0)`.

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

    Cursor(int línia, int columna);

- Constructor. Retorna un cursor a la posició (línia, columna).

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

    Cursor(Cursor altra);

- El constructor de còpia. Retorna una còpia del cursor `altra`.

  Exemple: `var copy = new Cursor(altra);`

    Cursor Cursor.clone();

- Retorna una còpia del cursor.

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

    Cursor.setPosition(int línia, int columna);

- Estableix la posició del cursor a `línia` i `columna`.

  Des de: &kde; 4.11

    bool Cursor.isValid();

- Comproveu si el cursor és vàlid. El cursor no és vàlid, si la línia i/o la columna s'estableix a `-1`.

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

    Cursor Cursor.invalid();

- Retorna un nou cursor no vàlid situat a `(-1, -1)`.

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

    int Cursor.compareTo(Cursor altra);

- Compara aquest cursor al cursor `altra`. Retorna

  - `-1`, si el cursor està situat abans del cursor `altra`,

  - `0`, si tots dos cursors són iguals i

  - `+1`, si el cursor està situat després del cursor `altra`.

    bool Cursor.equals(Cursor altra);

- Retorna `true` (vertader), si aquest cursor i el cursor `altra` són iguals, en cas contrari retornarà `false` (fals).

    String Cursor.toString();

- Retorna el cursor com una cadena de la forma `Cursor(line, column)`.

##### El prototip «Range»

    Range();

- El constructor. Crida `new Range()` retornant un interval (0, 0) - (0, 0).

    Range(Cursor inici, Cursor final);

- El constructor. Crida `new Range(`inici`, `final`)` retorna l'interval (`inici`, `final`).

    Range(int líniaInici, int columnaInici, int líniaFinal, int columnaFinal);

- El constructor. Crida `new Range(`líniaInici`, `columnaInici`, `líniaFinal`, `columnaFinal`)` retorna l'interval de (`líniaInici`, `columnaInici`) a (`líniaFinal`, `columnaFinal`).

    Range(Range altra);

- El constructor de còpia. Retorna una còpia de l'interval `altra`.

    Range Range.clone();

- Retorna una còpia de l'interval.

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

    bool Range.isEmpty();

- Retorna `true` (vertader), si inici i final del cursor són iguals.

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

  Des de: &kde; 4.11

    bool Range.isValid();

- Retorna `true` (vertader), si inici i final del cursor són vàlids, en cas contrari retornarà `false` (fals).

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

    Range Range.invalid();

- Retorna l'interval de (-1, -1) a (-1, -1).

    bool Range.contains(Cursor cursor);

- Retorna `true` (vertader) si aquest interval conté la posició de cursor, en cas contrari retornarà `false` (fals).

    bool Range.contains(Range altra);

- Retorna `true` (vertader), si aquest interval conté l'interval `altra`, en cas contrari retornarà `false` (fals).

    bool Range.containsColumn(int columna);

- Retorna `true` (vertader), si `columna` està en l'interval obert medi `[start.column, end.column)`, en cas contrari retornarà `false` (fals).

    bool Range.containsLine(int línia);

- Retorna `true` (vertader), si `línia` està en l'interval obert medi `[start.line, end.line)`, en cas contrari retornarà `false` (fals).

    bool Range.overlaps(Range altra);

- Retorna `true` (vertader), si aquest interval i l'interval `altra` comparteixen una regió comuna, en cas contrari retornarà `false` (fals).

    bool Range.overlapsLine(int línia);

- Retorna `true` (vertader), si `línia` està en l'interval `[start.line, end.line]`, en cas contrari retornarà `false` (fals).

    bool Range.overlapsColumn(int columna);

- Retorna `true` (vertader), si `columna` està en l'interval `[start.column, end.column]`, en cas contrari retornarà `false` (fals).

    bool Range.onSingleLine();

- Retorna `true` (vertader), si l'interval comença i finalitza a la mateixa línia, &ead; si `Línia.comença.interval == Línia.finalitza.interval`.

  Des de: &kde; 4.9

    bool Range.equals(Range altra);

- Retorna `true` (vertader), si aquest interval i l'interval de `altra` són iguals, en cas contrari retornarà `false` (fals).

    String Range.toString();

- Retorna l'interval com una cadena de la forma «`Rang(Cursor(line, column), Cursor(line, column))`».

#### Funcions globals

Aquesta secció llista totes les funcions globals.

##### Llegir i incloure fitxers

    String read(String fitxer);

- Cercarà el `fitxer` donat en relació al directori `katepart/script/files` i retorna el seu contingut com una cadena.

    void require(String fitxer);

- Cercarà el `fitxer` donat en relació al directori `katepart/script/libraries` i l'avaluarà. `require` està internament protegit contra inclusions múltiples del mateix `fitxer`.

  Des de: &kde; 4.10

##### Depuració

    void debug(String text);

- Imprimeix `text` a `stdout` a la consola de llançament de l'aplicació.

##### Traducció

Per tal de donar suport a la completa localització, hi ha diverses funcions per convertir cadenes en els scripts, anomenades `i18n`, `i18nc`, `i18np` i `i18ncp`. Aquestes funcions es comporten exactament com les funcions de traducció del &kde;.

Les funcions de traducció tradueixen les cadenes embolcallades a través del sistema de traducció del &kde; per a l'idioma utilitzat en l'aplicació. Les cadenes als scripts es desenvolupen a les fonts oficials de &kappname; i s'extrauen de forma automàtica i traduïble. En altres paraules, com a desenvolupador de &kappname; no us haureu de preocupar per l'extracció dels missatges i la traducció. Cal assenyalar però, que la traducció només funciona dins de la infraestructura del &kde;, &ead; les cadenes noves als scripts de terceres parts desenvolupats fora del &kde; no seran traduïbles. Per tant, considereu en contribuir els vostres scripts al &kate;, de tal manera que sigui possible una traducció apropiada.

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

- Tradueix `text` a la llengua utilitzada per l'aplicació. Els arguments `arg1`..., són opcionals i s'utilitzen per substituir els arguments `%1`, `%2`, &etc;

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

- Tradueix `text` a la llengua utilitzada per l'aplicació. A més, la cadena `context` és visible als traductors perquè puguin oferir una millor traducció. Els arguments `arg1`..., són opcionals i s'utilitzen per substituir els arguments `%1`, `%2`, &etc;

    void i18np(String singular, String plural, int número, arg1...);

- Tradueix `singular` o `plural` a la llengua utilitzada per l'aplicació, en funció del `número` indicat. Els arguments `arg1`..., són opcionals i s'utilitzen per substituir els arguments `%1`, `%2`, &etc;

    void i18ncp(String context, String singular, String plural, int número, arg1...);

- Tradueix `singular` o `plural` a la llengua utilitzada per l'aplicació, en funció del `número` indicat. A més, la cadena `context` és visible als traductors perquè puguin oferir una millor traducció. Els arguments `arg1`..., són opcionals i s'utilitzen per substituir els arguments `%1`, `%2`, &etc;

#### L'API de «View»

Cada vegada que s'executa un script, si no hi ha una variable global «`view`» que representa la vista actual de l'editor actiu. La següent és una llista de totes les funcions «View» disponibles.

    Cursor view.cursorPosition()

- Retorna la posició actual del cursor en la vista.

    void view.setCursorPosition(int línia, int columna);
    void view.setCursorPosition(Cursor cursor);

- Estableix la posició actual del cursor a (línia, columna) o el cursor indicat.

    Cursor view.virtualCursorPosition();

- Retorna la posició del cursor virtual amb cada tabulació comptant la corresponent quantitat d'espais depenent de l'amplada de la tabulació actual.

    void view.setVirtualCursorPosition(int línia, int column);
    void view.setVirtualCursorPosition(Cursor cursor);

- Estableix la posició actual del cursor virtual (línia, columna) o el cursor indicat.

    String view.selectedText();

- Retorna el text seleccionat. Si no hi ha text seleccionat, la cadena retornada estarà buida.

    bool view.hasSelection();

- Retorna `true` (vertader), si la vista conté el text seleccionat, en cas contrari retornarà `false` (fals).

    Range view.selection();

- Retorna l'interval de text seleccionat. L'interval retornat no serà vàlid si no hi ha text seleccionat.

    void view.setSelection(Range rang);

- Estableix el text seleccionat a l'interval indicat.

    void view.removeSelectedText();

- Elimina el text seleccionat. Si la vista no té cap text seleccionat, no fa res.

    void view.selectAll();

- Selecciona el text sencer en el document.

    void view.clearSelection();

- Neteja la selecció de text sense eliminar-lo.

#### L'API de «Document»

Cada vegada que s'executa un script, si no hi ha una variable global «`document`» que representa el document actiu actual. La següent és una llista de totes les funcions de «Document» disponibles.

    String document.fileName();

- Retorna el nom de fitxer del document o una cadena buida per a la memòria cau de text sense desar.

    String document.url();

- Retorna l'URL complet del document o una cadena buida per a la memòria cau de text sense desar.

    String document.mimeType();

- Retorna el tipus mime del document o el tipus mime `application/octet-stream` si no es pot trobar un tipus mime adequat.

    String document.encoding();

- Retorna la codificació usada actualment per a desar el fitxer.

    String document.highlightingMode();

- Retorna el mode de ressaltat global usat per a tot el document.

    String document.highlightingModeAt(Cursor pos);

- Retorna el mode de ressaltat usat a la posició indicada en el document.

    Array document.embeddedHighlightingModes();

- Retorna una cadena de modes de ressaltat inclosos en aquest document.

    bool document.isModified();

- Retorna `true` (vertader), si el document conté canvis sense desar (modificat), en cas contrari retornarà `false` (fals).

    String document.text();

- Retorna el contingut complet del document en una cadena de text única. Els salts de línia estan marcats amb el caràcter de nova línia «`\n`».

    String document.text(int desdeLínia, int desdeColumna, int alaLínia, int alaColumna);
    String document.text(Cursor desde, Cursor a);
    String document.text(Range rang);

- Retorna el text en l'interval donat. Es recomana utilitzar el cursor i la versió basada en l'interval per a una millor lectura del codi font.

    String document.line(int línia);

- Retorna la línia de text donada com a cadena. La cadena estarà buida si la línia demanada està fora de l'interval.

    String document.wordAt(int línia, int columna);
    String document.wordAt(Cursor cursor);

- Retorna la paraula a la posició del cursor donada.

    Range document.wordRangeAt(int línia, int columna);
    Range document.wordRangeAt(Cursor cursor);

- Retorna l'interval de la paraula a la posició del cursor donada. L'interval retornat no serà vàlid (veure Range.isValid()), si la posició del text és després del final d'una línia. Si no hi ha paraula al cursor donat, es retornarà un interval buit.

  Des de: &kde; 4.9

    String document.charAt(int línia, int columna);
    String document.charAt(Cursor cursor);

- Retorna el caràcter a la posició del cursor donada.

    String document.firstChar(int línia);

- Retorna el primer caràcter en la `línia` donada que no és un espai en blanc. El primer caràcter és a la columna 0. Si la línia està buida o només conté espais en blanc, la cadena retornada estarà buida.

    String document.lastChar(int línia);

- Retorna l'últim caràcter de la `línia` donada que no és un espai en blanc. Si la línia està buida o només conté espais en blanc, la cadena retornada estarà buida.

    bool document.isSpace(int línia, int columna);
    bool document.isSpace(Cursor cursor);

- Retorna `true` (vertader), si el caràcter a la posició del cursor donada és un espai en blanc, en cas contrari retornarà `false` (fals).

    bool document.matchesAt(int línia, int columna, String text);
    bool document.matchesAt(Cursor cursor, String text);

- Retorna `true` (vertader), si el `text` donat coincideix a la posició del cursor corresponent, en cas contrari retornarà `false` (fals).

    bool document.startsWith(int línia, String text, bool skipWhiteSpaces);

- Retorna `true` (vertader), si la línia comença amb `text`, en cas contrari retornarà `false` (fals). L'argument `skipWhiteSpaces` controla si s'han d'ometre els espais en blanc al davant.

    bool document.endsWith(int línia, String text, bool skipWhiteSpaces);

- Retorna `true` (vertader), si la línia acaba amb `text`, en cas contrari retornarà `false` (fals). L'argument `skipWhiteSpaces` controla si s'han d'ometre els espais en blanc finals.

    bool document.setText(String text);

- Estableix el text a tot el document.

    bool document.clear();

- Elimina tot el text en el document.

    bool document.truncate(int línia, int columna);
    bool document.truncate(Cursor cursor);

- Trunca la línia donada a la columna o la posició donada del cursor. Retorna `true` (vertader) en cas d'èxit, o `false` (fals) si la línia donada no forma part de l'interval del document.

    bool document.insertText(int línia, int columna, String text);
    bool document.insertText(Cursor cursor, String text);

- Insereix el `text` en la posició donada del cursor. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), si el document està en mode de només lectura.

    bool document.removeText(int desdeLínia, int desdeColumna, int alaLínia, int alaColumna);
    bool document.removeText(Cursor desde, Cursor a);
    bool document.removeText(Range rang);

- Elimina el text dins de l'interval donat. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), si el document està en mode de només lectura.

    bool document.insertLine(int línia, String text);

- Insereix text en la línia donada. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), si el document està en mode de només lectura o la línia no està en l'interval document.

    bool document.removeLine(int línia);

- Elimina la línia de text donada. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), si el document està en mode de només lectura o la línia no està en l'interval document.

    bool document.wrapLine(int línia, int columna);
    bool document.wrapLine(Cursor cursor);

- Ajusta la línia en la posició del cursor donada. Retorna `true` (vertader) en cas d'èxit, o `false` (fals), &pex; si la línia < 0.

  Des de: &kde; 4.9

    void document.joinLines(int iniciLínia, int finalLínia);

- S'uneix a les línies de `iniciLínia` a `finalLínia`. Dues línies de text successives sempre estan separades per un espai.

    int document.lines();

- Retorna el nombre de línies en el document.

    bool document.isLineModified(int línia);

- Retorna `true` (vertader), si la `línia` actual conté dades sense desar.

  Des de: &kde; 5.0

    bool document.isLineSaved(int línia);

- Retorna `true` (vertader), si la `línia` ha canviat, però el document ha estat desat. Per tant, la línia actual no conté cap dada sense desar.

  Des de: &kde; 5.0

    bool document.isLineTouched(int línia);

- Retorna `true` (vertader), si la `línia` actual conté dades sense desar o que s'han canviat abans.

  Des de: &kde; 5.0

    bool document.findTouchedLine(int iniciLínia, bool avall);

- Cerca la següent línia tocada començant per la `línia`. La cerca es realitza ja sigui amunt o avall depenent de la direcció especificada a `avall`.

  Des de: &kde; 5.0

    int document.length();

- Retorna el nombre de caràcters en el document.

    int document.lineLength(int línia);

- Retorna la longitud de la `línia`.

    void document.editBegin();

- Comença un grup d'edició per agrupar desfer/refer. Assegureu-vos de cridar sempre `editEnd()` tan aviat com crideu `editBegin()`. La crida `editBegin()` utilitza internament un comptador de referència, &ead;, aquesta crida es pot niar.

    void document.editEnd();

- Finalitza un grup d'edició. L'última crida de `editEnd()` (&ead;, una per a la primera crida de `editBegin()`) finalitza el pas d'edició.

    int document.firstColumn(int línia);

- Retorna la primera columna que no està en blanc en la `línia` donada. Si només hi ha espais en blanc en la línia, el valor retornat serà `-1`.

    int document.lastColumn(int línia);

- Retorna la darrera columna que no està en blanc en la `línia` donada. Si només hi ha espais en blanc en la línia, el valor retornat serà `-1`.

    int document.prevNonSpaceColumn(int línia, int columna);
    int document.prevNonSpaceColumn(Cursor cursor);

- Retorna la columna no buida que conté un caràcter no en blanc a partir de la posició donada del cursor i cercant cap enrere.

    int document.nextNonSpaceColumn(int línia, int columna);
    int document.nextNonSpaceColumn(Cursor cursor);

- Retorna la columna no buida que conté un caràcter no en blanc a partir de la posició donada del cursor i cercant cap endavant.

    int document.prevNonEmptyLine(int línia);

- Retorna la línia següent no buida que conté caràcters no en blanc a la cerca cap enrere.

    int document.nextNonEmptyLine(int línia);

- Retorna la línia següent no buida que conté caràcters no en blanc a la cerca cap endavant.

    bool document.isInWord(String caràcter, int atribut);

- Retorna `true` (vertader), si el `caràcter` donat amb l'`atribut` donat pot formar part d'una paraula, en cas contrari retornarà `false` (fals).

    bool document.canBreakAt(String caràcter, int atribut);

- Retorna `true` (vertader), si el `caràcter` donat amb l'`atribut` donat és adequat com a embolcall d'una línia, en cas contrari retornarà `false` (fals).

    bool document.canComment(int iniciAtribut, int finalAtribut);

- Retorna `true` (vertader), si un interval inicial i final amb els atributs donats es presten a ser descomentats, en cas contrari retornarà `false` (fals).

    String document.commentMarker(int atribut);

- Retorna el marcador de comentari per als comentaris de línia única per a un `atribut` donat.

    String document.commentStart(int atribut);

- Retorna el marcador de comentari per al començament de comentaris de múltiples línies per a un `atribut` donat.

    String document.commentEnd(int atribut);

- Retorna el marcador de comentari per al final de comentaris de múltiples línies per a un `atribut` donat.

    Range document.documentRange();

- Retorna un interval que abasta tot el document.

    Cursor documentEnd();

- Retorna un cursor ubicat a l'última columna de l'última línia al document.

    bool isValidTextPosition(int línia, int columna);
    bool isValidTextPosition(Cursor cursor);

- Retorna `true` (vertader), si la posició indicada del cursor està situada a una posició vàlida de text. Una posició de text només és vàlida si es localitza al començament, al mig o al final d'una línia vàlida. A més, una posició de text no serà vàlida si es troba en un substitut Unicode.

  Des de: &kde; 5.0

    int document.attribute(int línia, int columna);
    int document.attribute(Cursor cursor);

- Retorna l'atribut a la posició del cursor donada.

    bool document.isAttribute(int línia, int columna, int atribut);
    bool document.isAttribute(Cursor cursor, int atribut);

- Retorna `true` (vertader), si l'atribut a la posició del cursor és igual que l'`atribut`, en cas contrari retornarà `false` (fals).

    String document.attributeName(int línia, int columna);
    String document.attributeName(Cursor cursor);

- Retorna el nom de l'atribut com a text llegible. Això equival al nom `itemData` en els fitxers de ressaltat de sintaxi.

    bool document.isAttributeName(int línia, int columna, String nom);
    bool document.isAttributeName(Cursor cursor, String nom);

- Retorna `true` (vertader), si el nom de l'atribut en una posició determinada del cursor coincideix amb el `nom` donat, en cas contrari retornarà `false` (fals).

    String document.variable(String clau);

- Retorna el valor de la variable de document demanada `clau`. Si la variable de document no existeix, el valor retornat serà una cadena buida.

    void document.setVariable(String clau, String valor);

- Estableix el valor de la variable de document demanada `clau`.

  Veure també: variables de document de Kate

  Des de: &kde; 4.8

    int document.firstVirtualColumn(int línia);

- Retorna la columna virtual del primer caràcter que no està en blanc en la línia donada o `-1`, si la línia està buida o només conté caràcters d'espai en blanc.

    int document.lastVirtualColumn(int línia);

- Retorna la columna virtual de l'últim caràcter que no està en blanc en la línia donada o `-1`, si la línia està buida o només conté caràcters d'espai en blanc.

    int document.toVirtualColumn(int línia, int columna);
    int document.toVirtualColumn(Cursor cursor);
    Cursor document.toVirtualCursor(Cursor cursor);

- Converteix la posició «real» donada del cursor a una posició virtual del cursor, d'altra manera retorna un int o un objecte Cursor.

    int document.fromVirtualColumn(int línia, int virtualColumna);
    int document.fromVirtualColumn(Cursor virtualCursor);
    Cursor document.fromVirtualCursor(Cursor virtualCursor);

- Converteix la posició virtual donada del cursor a una posició «real» del cursor, d'altra manera retorna un int o un objecte Cursor.

    Cursor document.anchor(int línia, int columna, Char caràcter);
    Cursor document.anchor(Cursor cursor, Char caràcter);

- Cerca enrere pel caràcter donat a partir del cursor donat. Com exemple, si es passa «(» com a caràcter, aquesta funció retornarà la posició de l'obertura «(». Això compta la referència, &ead;, els altres «(...)» seran ignorats.

    Cursor document.rfind(int línia, int columna, String text, int atribut = -1);
    Cursor document.rfind(Cursor cursor, String text, int atribut = -1);

- Cerca cap enrere el text donat amb l'`atribut` adequat. L'argument `atribut` s'ignorarà si s'estableix a `-1`. El cursor retornat no serà vàlid, si el text no s'ha pogut trobar.

    int document.defStyleNum(int línia, int columna);
    int document.defStyleNum(Cursor cursor);

- Retorna l'estil per omissió utilitzat a la posició donada del cursor.

    bool document.isCode(int línia, int columna);
    bool document.isCode(Cursor cursor);

- Retorna `true` (vertader), si l'atribut a la posició donada del cursor no és igual per a tots els següents estils: `dsComment`, `dsString`, `dsRegionMarker`, `dsChar`, `dsOthers`.

    bool document.isComment(int línia, int columna);
    bool document.isComment(Cursor cursor);

- Retorna `true` (vertader), si l'atribut del caràcter a la posició del cursor és `dsComment`, en cas contrari retornarà `false` (fals).

    bool document.isString(int línia, int columna);
    bool document.isString(Cursor cursor);

- Retorna `true` (vertader), si l'atribut del caràcter a la posició del cursor és `dsString`, en cas contrari retornarà `false` (fals).

    bool document.isRegionMarker(int línia, int columna);
    bool document.isRegionMarker(Cursor cursor);

- Retorna `true` (vertader), si l'atribut del caràcter a la posició del cursor és `dsRegionMarker`, en cas contrari retornarà `false` (fals).

    bool document.isChar(int línia, int columna);
    bool document.isChar(Cursor cursor);

- Retorna `true` (vertader), si l'atribut del caràcter a la posició del cursor és `dsChar`, en cas contrari retornarà `false` (fals).

    bool document.isOthers(int línia, int columna);
    bool document.isOthers(Cursor cursor);

- Retorna `true` (vertader), si l'atribut del caràcter a la posició del cursor és `dsOthers`, en cas contrari retornarà `false` (fals).

## Extensions del component d'edició

Les extensions per al component d'edició estenen la KatePart, el component de l'editor de text avançat és utilitzat en moltes aplicacions del &kde;, com &kate;, &kwrite;, Kile i KDevelop. La creació d'un connector per al component d'edició us permetrà estendre la funcionalitat de l'editor a tots i cadascun d'aquests programes.

Per començar, veure la Guia d'aprenentatge per a connectors del KTextEditor a TechBase del &kde;. Per més, veure la Guia d'aprenentatge avançada, també a TechBase.

Podeu trobar la documentació de la API a la referència de la API del &kde;.