Principals seccions dels fitxers de definició del ressaltat de la KatePart

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

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

La part principal del fitxer de la definició és l'element language. 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"

version especifica la versió actual del fitxer de definició en termes d'un nombre enter. Sempre que es canvia un fitxer de definició del ressaltat, assegureu-vos d'augmentar aquest número.

kateversion especifica l'última versió implementada de la KatePart.

Atributs opcionals:

mimetype fitxers associats amb el tipus MIME.

casesensitive defineix quan les paraules clau distingeixen o no les majúscules i minúscules.

priority és necessària si una altra definició de ressaltat utilitza les mateixes extensions. S'emprarà 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 la llicència del MIT per a fitxers nous de ressaltat de la sintaxi.

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

indenter defineix quin sagnat emprar de manera predeterminada. Els atributs disponibles són: ada, normal, cstyle, cmake, haskell, latex, lilypond, lisp, lua, pascal, python, replicode, ruby i xml.

hidden defineix quan hauria d'aparèixer el nom en els menús de la KatePart.

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

<language name="C++" version="1" 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.

Des del Frameworks del KDE™ 5.53, una llista pot incloure paraules clau d'una altra llista o llenguatge/fitxer, utilitzant l'element include. Els caràcters ## s'utilitzen per a separar el nom de la llista i el nom de la definició del llenguatge, de la mateixa manera que a la regla IncludeRules. Això és útil per a evitar la duplicació de llistes de paraules clau, si necessiteu incloure les paraules clau d'un altre llenguatge/fitxer. Per exemple, la llista altre_nom conté la paraula clau str i totes les paraules clau de la llista types, la qual pertany al llenguatge C++ de l'ISO.

L'element contexts conté tots els contexts. El primer és l'emprat de manera predeterminada i amb aquest s'iniciarà el ressaltat. Hi ha dues regles en el context text_normal, el qual farà 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 a aprendre més sobre les regles llegiu el següent capítol.

La tercera part és l'element itemDatas. Conté tots els colors i estils de lletra que necessiten els contexts i les regles. En aquest exemple, s'utilitzen itemData text_normal, cadena i paraula_clau.

<highlighting>
    <list name="algun_nom">
      <item>class</item>
      <item>const</item>
    </list>
    <list name="altre_nom">
      <item>str</item>
      <include>types##ISO C++</include>
    </list>
    <contexts>
      <context attribute="text_normal" lineEndContext="#pop" name="text_normal" >
        <keyword attribute="paraula_clau" context="#stay" String="algun_nom" />
        <keyword attribute="paraula_clau" context="#stay" String="altre_nom" />
        <DetectChar attribute="cadena" context="cadena" 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="dsKeyword" />
      <itemData name="cadena" defStyleNum="dsString" />
    </itemDatas>
  </highlighting>

L'última part de la definició del ressaltat és la secció opcional general. Pot contenir informació sobre paraules clau, plegat del codi, comentaris, sagnat, línies buides i verificació de l'ortografia.

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 utilitzant multiLine amb l'atribut addicional end. Això s'empra si l'usuari prem la drecera corresponent per a comenta/descomenta.

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

Les altres seccions, folding, emptyLines i spellchecking, normalment no són necessàries i s'expliquen més endavant.

<general>
    <comments>
      <comment name="singleLine" start="#"/>
      <comment name="multiLine" start="###" end="###" region="CommentFolding"/>
    </comments>
    <keywords casesensitive="1"/>
    <folding indentationsensitive="0"/>
    <emptyLines>
      <emptyLine regexpr="\s+"/>
      <emptyLine regexpr="\s*#.*"/>
    </emptyLines>
    <spellchecking>
      <encoding char="á" string="\'a"/>
      <encoding char="à" string="\`a"/>
    </spellchecking>
  </general>
</language>

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 utilitzaran el nom per a especificar el context al qual canviar si les regles coincideixen.

attribute identifica l'estil a utilitzar per a un caràcter quan no coincideix cap regla o quan una regla no especifica cap atribut. En aquest últim cas, s'utilitzarà attribute del context especificat a la regla context.

lineEndContext defineix el context al qual canviarà el sistema de ressaltat si abasta el final de la línia. Pot ser un nom o un altre context, #stay permetrà que no es canviï el context (p. ex., no fer res) o #pop farà que deixi aquest context. És possible utilitzar, per exemple #pop#pop#pop per a sortir tres vegades, o fins i tot #pop#pop!AltreContext perquè aparegui dues vegades i canviar a un context anomenat AltreContext. També és possible canviar a un context que pertanyi a una altra definició de llenguatge, de la mateixa manera que en les regles IncludeRules, p. ex., AlgunContext##JavaScript. Els canvis de context també es descriuen a «Regles de detecció del ressaltat». De manera predeterminada: #stay.

lineEmptyContext defineix el context si es troba una línia buida. La nomenclatura dels commutadors de context és la mateixa que s'ha descrit anteriorment a lineEndContext. De manera predeterminada: #stay.

fallthroughContext especifica el context següent al qual canviar si no coincideix cap regla. La nomenclatura dels commutadors de context és la mateixa que s'ha descrit anteriorment a lineEndContext. De manera predeterminada: #stay.

fallthrough defineix si el sistema de ressaltat canviarà al context especificat a fallthroughContext si no coincideix cap regla. Cal tenir en compte que, des dels Frameworks™ 5.62 del KDE, aquest atribut està en desús a favor de fallthroughContext, ja que si està present aquest atribut, s'entendrà implícitament que el valor de fallthrough és true (cert). De manera predeterminada: false (fals).

noIndentationBasedFolding inhabilita el plegat basat en el sagnat dintre del context. Si el plegat basat en el sagnat no està activat, aquest atribut és inútil. Això es defineix en l'element folding del grup general. De manera predeterminada a: false.

L'element itemData es troba en el grup itemDatas. Defineix l'estil i els colors de les lletres. Per tant, és possible definir els vostres propis estils i colors. Encara que recomanem utilitzar els estils predeterminats, 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 de la 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 utilitzaran aquest nom en els seus atributs attribute per a fer referència a un «itemData».

defStyleNum defineix quin estil s'emprarà de manera predeterminada. Més endavant s'explicaran els estils predeterminats 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 distingiran les 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 darrere dels quals pot ocórrer un ajust de la línia.

Els delimitadors predeterminats i els d'ajust de la 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 a Eines → Comenta, Eines → Descomenta i Eines → Commuta els comentaris. Els atributs disponibles són:

name pot ser singleLine o multiLine. Si escolliu multiLine es necessiten els atributs end i region. Si escolliu singleLine podreu afegir l'atribut opcional position.

start defineix la cadena que s'utilitza per a iniciar un comentari. En C++ seria "/*" en comentaris multilínia. Aquest atribut és requerit per als tipus multiLine i singleLine.

end defineix la cadena utilitzada per a tancar un comentari. En C++ seria "*/". Només està disponible aquest atribut i es necessita per als comentaris del tipus multiLine.

region serà el nom amb el qual es desarà el comentari multilínia. Si assumim que tenim una regió beginRegion="Comentari" ... endRegion="Comentari" en les regles, haureu d'emprar 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. Només està disponible aquest atribut i es necessita per als comentaris del tipus multiLine.

position defineix on s'insereix el comentari d'una sola línia. De manera predeterminada, el comentari d'una sola línia es col·loca al començament de la línia a la columna 0, però si utilitzeu position="afterwhitespace", el comentari s'insereix a la dreta després dels espais en blanc inicials, abans del primer caràcter que no sigui un espai en blanc. Això és útil per a posar comentaris correctament en llenguatges on la sagnia és important, com el Python o YAML. Aquest atribut és opcional i l'únic valor possible és afterwhitespace. Només està disponible per als tipus singleLine.

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

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

L'element emptyLine pertany al grup emptyLines defineix quines línies s'hauran de tractar com a línies buides. Això permet modificar el comportament de l'atribut lineEmptyContext en els elements context. Els atributs disponibles són:

regexpr defineix una expressió regular que es tractarà com una línia buida. De manera predeterminada, les línies buides no contenen cap caràcter, per tant, això afegirà línies buides addicionals, per exemple, si voleu que les línies amb espais també es consideren com a línies buides. No obstant això, en la majoria de les definicions de la sintaxi no caldrà establir aquest atribut.

L'element encoding en el grup spellchecking defineix una codificació de caràcters per a la verificació ortogràfica. Els atributs disponibles són:

char, és un caràcter codificat.

string és una seqüència de caràcters que es codificaran com el caràcter char a la verificació ortogràfica. Per exemple, en el llenguatge LaTeX, la cadena \"{A} representa el caràcter Ä.

Estils predeterminats en general:

dsNormal, quan no es requereix un ressaltat especial.

dsKeyword, paraules clau integrades.

dsFunction, 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 integrats.

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

dsPreprocessor, declaracions del preprocessador o de definicions de macros.

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

Estils predeterminats relacionats amb les cadenes:

dsChar, 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, cadenes com «hello world».

dsVerbatimString, cadenes literals o sense processar 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 de L^AT_EX...

dsImport, importar, incloure o requerir mòduls.

Estils predeterminats relacionats amb números:

dsDataType, tipus de dades integrats com «int», «void», «u64».

dsDecVal, valors decimals.

dsBaseN, valors en una base diferent de 10.

dsFloat, valors de coma flotant.

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

Estils predeterminats relacionats amb la documentació i els comentaris:

dsComment, 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, marcadors de regió com els comentaris «//BEGIN», «//END».

Altres estils predeterminats:

dsInformation, notes i consells com «@note» al doxygen.

dsWarning, avisos com «@warning» al doxygen.

dsAlert, paraules especials com «Per fer», «TODO», «FIXME», «XXXX».

dsError, errors de ressaltat i sintaxi incorrecta.

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

DetectChar

Detecta un únic caràcter específic. Normalment s'utilitza 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) />

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

Aquesta regla és present per raons històriques i per llegibilitat és preferible utilitzar StringDetect.

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 predeterminat és false i es passa a la funció de comparació de la cadena. Si el valor és true la comparació no distingirà les majúscules i minúscules.

WordDetect

Detectar una cadena exacta 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) (delimitadors locals) />

L'atribut String defineix la cadena a comparar. L'atribut insensitive predeterminat és false i es passa a la funció de comparació de la cadena. Si el valor és true la comparació no distingirà les majúscules i minúscules.

Des del: 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 de manera predeterminada és false i és passada al motor d'expressions regulars.

minimal de manera predeterminada és 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.

Per a obtenir més informació, vegeu la secció sobre expressions regulars.

keyword

Detecta una paraula clau des d'una llista especificada.

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

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 les 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 predeterminats), 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. També és possible utilitzar l'atribut weakDeliminator de la keyword perquè aquesta modificació només s'apliqui a aquesta regla.

Int

Detecta un nombre enter (com l'expressió regular: \b[0-9]+).

<Int (atributs comuns) (delimitadors locals) />

Aquesta regla no té atributs específics.

Decimals

Detecta un nombre decimal (com l'expressió regular: (\b[0-9]+\.[0-9]*|\.[0-9]+)([eE][-+]?[0-9]+)?).

<Float (atributs comuns) (delimitadors locals) />

Aquesta regla no té atributs específics.

HlCOct

Detecta una representació numèrica d'un nombre octal (com l'expressió regular: \b0[0-7]+).

<HlCOct (atributs comuns) (delimitadors locals) />

Aquesta regla no té atributs específics.

HlCHex

Detecta una representació numèrica d'un nombre hexadecimal (com una expressió regular: \b0[xX][0-9a-fA-F]+).

<HlCHex (atributs comuns) (delimitadors locals) />

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 habitualment s'utilitzen en el codi de programació, per exemple \n (línia nova) o \t (tabulació).

Els següents caràcters coincideixen amb la regla si segueixen a una barra inversa (\): abefnrtv"'?\. A més seran vàlids els nombres hexadecimals escapats com per exemple \xff, i els nombres 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. Vegeu «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ò teniu en compte que el motor de ressaltat només pot treballar amb una línia a la vegada, de manera que no es detectaran les 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, de manera predeterminada és la barra inversa ('\'). 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 altre 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 en C++.

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

DetectSpaces

Detecta els espais en blanc.

<DetectSpaces (atributs comuns) />

Aquesta regla no té atributs específics.

Utilitzeu aquesta regla si sabeu que hi poden haver diversos 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 coincidències.

DetectIdentifier

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

<DetectIdentifier (atributs comuns) />

Aquesta regla no té atributs específics.

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