Huvudkomponenter i KateParts färgläggningsdefinitioner

En syntaxfärgläggningsfil innehåller ett huvud som anger XML-versionen:

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

Definitionsfilens rot är elementet language. Följande egenskaper är tillgängliga:

Egenskaper som krävs:

name anger språkets namn. Det visas senare i menyer och dialogrutor.

section anger kategorin.

extensions definierar filändelser, såsom "*.cpp;*.h".

version anger aktuell version av definitionsfilen i form av ett heltal. När en definitionsfil för färgläggning ändras, försäkra dig om att talet ökas.

kateversion anger senaste version av KatePart som stöds.

Valfria egenskaper:

mimetype associerar filers MIME-typ.

casesensitive definierar om nyckelord är skiftlägeskänsliga eller inte.

priority krävs om en annan syntaxfärgläggningsfil använder samma filändelse. Den högsta prioriteten vinner.

author innehåller författarens namn och e-postadress.

license innehåller licensen, oftast MIT-licensen för nya syntaxfärgläggningsfiler.

stil innehåller språket som tillhandahålls och används av indenterare för egenskapen required-syntax-style.

indenter definierar vilken indenterare som normalt används. Tillgängliga indenterare är:ada, normal, cstyle, cmake, haskell, latex, lilypond, lisp, lua, pascal, python, replicode, ruby och xml.

hidden definierar om namnet ska visas i KateParts menyer.

Nästa rad kan alltså se ut så här:

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

Därefter kommer elementet highlighting som innehåller det valfria elementet list och det nödvändiga elementen contexts och itemDatas.

list element innehåller en lista med nyckelord. I det här fallet är nyckelorden class och const. Du kan lägga till så många listor som du behöver.

Sedan KDE Ramverk 5.53 kan en lista inkludera nyckelord från en annan lista, språk eller fil, genom att använda elementet include element.## är att separera listnamnet och språkdefinitionens namn, på samma sätt som regeln IncludeRules. Det är användbart för att undvika att duplicera nyckelordslistor, om du behöver inkludera nyckelorden från ett annat språk eller fil. Exempelvis innehåller listan annat-namn nyckelordet str och alla nyckelorden från listan types, vilken hör till språket ISO C++.

Elementet contexts innehåller alla sammanhang. Det första sammanhanget är förvalt som start för färgläggningen. Det finns två regler i sammanhanget Normal Text som matchar listan av nyckelord med namnet något-namn och en regel som detekterar ett citationstecken och byter sammanhang till string. För att lära dig mer om regler, läs nästa kapitel.

Den tredje delen är elementet itemDatas. Det innehåller alla färger och teckenstilar som behövs av sammanhangen och reglerna. I det här exemplet används itemData Normal Text, String och Keyword.

<highlighting>
    <list name="något-namn">
      <item> class </item>
      <item> const </item>
    </list>
    <list name="annat-namn">
      <item>str</item>
      <include>types##ISO C++</include>
    </list>
    <contexts>
      <context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" >
        <keyword attribute="Keyword" context="#stay" String="något-namn" />
        <DetectChar attribute="String" context="String="annat-namn" />
        <DetectChar attribute="String" context="string" char="&quot;" />
      </context>
      <context attribute="String" lineEndContext="#stay" name="string" >
        <DetectChar attribute="String" context="#pop" char="&quot;" />
      </context>
    </contexts>
    <itemDatas>
      <itemData name="Normal Text" defStyleNum="dsNormal" />
      <itemData name="Keyword" defStyleNum="dsKeyword" />
      <itemData name="String" defStyleNum="dsString" />
    </itemDatas>
  </highlighting>

Den sista delen av färgläggningsdefinitionen är den valfria sektionen general. Den kan innehålla information om nyckelord, kodvikning, kommentarer, indentering, tomma rader och stavningskontroll.

Sektionen comment definierar den sträng som enradskommentarer inleds med. Du kan också definiera en flerradskommentar med multiLine och den ytterligare egenskapen end. Det är användbart när användaren trycker på snabbtangenten som motsvarar kommentera/avkommentera.

Sektionen keywords definierar om listor med nyckelord är skiftlägeskänsliga eller inte. Andra egenskaper förklaras senare.

Övriga sektioner, folding, emptyLines och spellchecking, behövs oftast inte och förklaras senare.

<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>

Elementet context hör till gruppen contexts. Själva sammanhanget definierar sammanhangsspecifika regler, som vad som ska ske om färgläggningssystemet når slutet på en rad. Tillgängliga egenskaper är:

name anger sammanhangets namn. Regler använder namnet för att ange sammanhanget att byta till om regeln matchar.

lineEndContext definierar sammanhanget som färgläggningssystemet byter till om det når ett radslut. Det kan antingen vara namnet på ett annat sammanhang, #stay för att inte byta sammanhang (dvs. göra ingenting) eller #pop som gör att det lämnar sammanhanget. Det är till exempel möjligt att använda #pop#pop#pop för att återgå tre steg, eller till och med #pop#pop!Annat_Sammanhang för att återgå två steg och byta till sammanhanget som heter Annat_Sammanhang. Det är också möjligt att byta till ett sammanhang som hör till en annan språkdefinition, på samma sätt som för reglerna IncludeRules, t.ex. Något_Sammanhang##JavaScript. Observera att det inte går att använda det här sammanhangsbytet tillsammans med #pop, exempelvis är #pop!Något_Sammanhang##JavaScript inte giltigt. Sammanhangsbyten beskrivs också i ”Regler för syntaxdetektering”.

lineEmptyContex definierar sammanhanget om en tom rad påträffas. Terminologin för sammanhangsbyte är samma som tidigare beskrivits i lineEndContext. Förval: #stay.

fallthroughContext anger nästa sammanhang att byta till om ingen regel matchar. Terminologin för sammanhangsbyte är samma som tidigare beskrivits i lineEndContext. Förval: #stay.

fallthrough definierar om färgläggningssystemet byter till sammanhanget som anges i fallthroughContext om ingen regel matchar. Observera att sedan KDE Frameworks™ 5.62 avråds användning av egenskapen, använd istället fallthroughContext, eftersom om egenskapen fallthroughContext finns förstås implicit att värdet på fallthrough är true. Förval: false.

noIndentationBasedFolding inaktiverar indenteringsbaserad vikning i sammanhanget. Om indenteringsbaserad vikning inte är aktiverad är egenskapen meningslös. Det definieras av elementet folding i gruppen general. Förval: false.

Elementet itemData är i gruppen itemDatas. Det definierar teckenstilen och färgerna. Det är alltså möjligt att definiera egna stilar och färger. Dock rekommenderar vi att du håller dig till standardstilarna om möjligt, så att användaren alltid ser samma färger använda i olika språk. Ibland finns det dock inget annat sätt, och det är nödvändigt att ändra färg- och teckenegenskaper. Egenskapens namn och defStyleNum krävs, övriga är valfria. Tillgängliga egenskaper är:

name anger namnet på itemData. Sammanhang och regler använder namnet i egenskapen attribute för att referera till itemData.

defStyleNum definierar vilken standardstil som ska användas. Tillgängliga standardstilar förklaras i detalj senare.

color definierar en färg. Giltiga format är '#rrggbb' eller '#rgb'.

selColor definierar markeringens färg.

italic om true, är texten kursiv.

bold om true, är texten i fetstil.

underline om true, är texten understruken.

strikeout om true, är texten överstruken.

spellChecking om true, stavningskontrolleras texten.

Elementet keywords i gruppen general definierar nyckelordens egenskaper. Tillgängliga egenskaper är:

casesensitive kan vara true eller false. Om det är true, matchas alla nyckelord skiftlägeskänsligt.

weakDeliminator är en lista med tecken som inte fungerar som ordavgränsare. Punkt '.' är till exempel en ordavgränsare. Med antagandet att ett nyckelord i en list innehåller en punkt, matchar det bara om du anger att punkten är en svag avgränsare.

additionalDeliminator definierar ytterligare avgränsare.

wordWrapDeliminator definierar tecken som en radbrytning kan ske efter.

Standardavgränsare och radbrytningsavgränsare är tecknen .():!+,-<=>%&*/;?[]^{|}~\, mellanslag (' ') och tabulator ('\t').

Elementet comment i gruppen comments definierar kommentaregenskaper som används för Verktyg → Kommentera, Verktyg → Avkommentera och Verktyg → Växla kommentar. Tillgängliga egenskaper är:

name är antingen singleLine eller multiLine. Om du väljer multiLine krävs egenskaperna end och region. Om du väljer singleLine kan du lägga till den valfria egenskapen position.

start definierar strängen som används för att inleda en kommentar. I C++ skulle det vara "/*". Egenskapen krävs för typerna multiLine och singleLine.

end definierar strängen som används för att avslutar en kommentar. I C++ skulle det vara "*/". Egenskapen är bara tillgänglig för och krävs för kommentarer av typen multiLine.

region ska vara namnet på den vikbara flerraderskommentaren. Med antagandet att du har beginRegion="Comment" ... endRegion="Comment" i dina regler, ska du använda region="Comment". På så sätt fungerar avkommentering även om du inte markerar all text i en flerraderskommentar. Markören måste bara vara inne i flerraderskommentaren. Egenskapen är bara tillgänglig för typen multiLine.

position definierar var enraderskommentaren infogas. Normalt placeras enraderskommentaren i början av raden på kolumn 0, men om position="afterwhitespace" används infogas kommentaren efter inledande blanktecken, precis före det första tecknet som inte är ett blanktecken. Det är användbart för att placera kommentarer korrekt i språk där indentering är viktig, såsom Python eller YAML. Egenskapen är valfri och det enda möjliga värdet är afterwhitespace. Den är bara tillgänglig för typen singleLine.

Elementet folding i gruppen general definierar kodvikningsegenskaper. Tillgängliga egenskaper är:

indentationsensitive om true läggs kodvikningsmarkörerna till baserat på indentering, som i skriptspråket Python. Oftast behöver du inte ange det, eftersom det har det förvalda värdet false.

Elementet emptyLine i gruppen emptyLines definierar vilka rader som ska behandlas som tomma rader. Det gör det möjligt att ändra beteendet hos egenskapen lineEmptyContext i elementets context. Tillgängliga egenskaper är:

regexpr definierar ett reguljärt uttryck som behandlas som en tom rad. Normalt innehåller tomma rader inte några tecken, därför lägger det här till ytterligare tomma rader, om du exempelvis vill att rader med mellanslag också ska anses vara tomma rader. Dock behöver man inte ange den här egenskapen i de flesta syntaxdefinitioner.

Elementet encoding i gruppenspellchecking definierar en teckenkodning för stavningskontroll. Tillgängliga egenskaper:

charär ett kodat tecken.

string är en teckenföljd som kodas som tecknet char i stavningskontrollen. Exempelvis representerar strängen \"{A} tecknet Ä i språket Latex.

Allmänna standardstilar:

dsNormal, när ingen särskild färgläggning krävs.

dsKeyword, nyckelord för inbyggda språk.

dsFunction, funktionsanrop och definitioner.

dsVariable, om tillämpligt: variabelnamn (t.ex. $enVariabel i PHP eller Perl).

dsControlFlow, nyckelord för kontrollflöde såsom if, else, switch, break, return, yield, ...

dsOperator, operatorer såsom + - * / :: < >

dsBuiltin, inbyggda funktioner, klasser och objekt.

dsExtension, vanliga ändelser såsom Qt™-klasser och funktioner eller makron i C++ och Python.

dsPreprocessor, preprocessorsatser eller makrodefinitioner.

dsAttribute, anmärkningar som @override och __declspec(...).

Strängrelaterade standardstilar:

dsChar, enstaka tecken såsom 'x'.

dsSpecialChar, tecken med speciell betydelse i strängar som undantag, ersättningar eller operatorer i reguljära uttryck.

dsString, strängar såsom "hej allihop".

dsVerbatimString, ordagranna eller obehandlade strängar som 'raw \backlash' i Perl, CoffeeScript och skal, samt r'\raw' i Python.

dsSpecialString, SQL-satser, reguljära uttryck, HERE-dokument, L^AT_EX-matematikläge, ...

dsImport, import, inkludering och require för moduler.

Nummerrelaterade standardstilar:

dsDataType, inbyggda datatyper såsom int, void, u64.

dsDecVal, decimala värden.

dsBaseN, värden med en bas skild från 10.

dsFloat, flyttalsvärden.

dsConstant, inbyggda och användardefinierade konstanter såsom PI.

Kommentar- och dokumentationsrelaterade standardstilar:

dsComment, kommentarer.

dsDocumentation, /** dokumentationskommentarer */ eller """dokumentsträngar""".

dsAnnotation, dokumentationskommandon som @param, @brief.

dsCommentVar, variabelnamnen som används i ovanstående kommandon, som "exempel" i @param exempel.

dsRegionMarker, områdesmarkeringar som //BEGIN, //END i kommentarer.

Andra standardstilar:

dsInformation, anmärkningar och tips som @note i doxygen.

dsWarning, varningar som @warning i doxygen.

dsAlert, specialord som TODO, FIXME, XXXX.

dsError, färgläggning av fel och felaktig syntax.

dsOthers, när ingenting annat passar in.

DetectChar

Detektera ett enda specifikt tecken. Används ofta för att till exempel hitta slutet på strängar inom citationstecken.

<DetectChar char="(tecken)" (gemensamma egenskaper) (dynamisk) />

Egenskapen char definierar tecknet som ska matchas.

Detect2Chars

Detektera två angivna tecken i en definierad ordning.

<Detect2Chars char="(tecken)" char1="(tecken)" (gemensamma egenskaper) />

Egenskapen char definierar det första tecknet som ska matcha, char1 det andra.

AnyChar

Detektera ett tecken i en angiven teckenmängd.

<AnyChar String="(sträng)" (gemensamma egenskaper) />

Egenskapen String definierar teckenmängden.

StringDetect

Detektera en sträng exakt.

<StringDetect String="(sträng)" [insensitive="TRUE|FALSE;"] (gemensamma egenskaper) (dynamisk) />

Egenskapen String definierar strängen som ska matcha. Egenskapen insensitive (okänslig) är normalt FALSE (FALSK) och skickas med till strängjämförelsefunktionen. Om värdet är TRUE (SANT) så används en jämförelse som inte bryr sig om skiftläge.

WordDetect

Detektera en exakt sträng, men kräv dessutom ordgränser som en punkt '.' eller ett blanktecken i början och slutet av ordet. Betrakta \b<string>\b som ett reguljärt uttryck, men snabbare än regeln RegExpr.

<WordDetect String="(sträng)" [insensitive="TRUE|FALSE;"] (gemensamma egenskaper) (lokala avgränsare)/>

Egenskapen String definierar strängen som ska matcha. Egenskapen insensitive (okänslig) är normalt FALSE (FALSK) och skickas med till strängjämförelsefunktionen. Om värdet är TRUE (SANT) så används en jämförelse som inte bryr sig om skiftläge.

Sedan: Kate 3.5 (KDE 4.5)

RegExpr

Matchar med ett reguljärt uttryck.

<RegExpr String="(sträng)" [insensitive="TRUE|FALSE;"] [minimal="TRUE| FALSE"] (gemensamma egenskaper) (dynamisk) />

Egenskapen String definierar det reguljära uttrycket.

Egenskapen insensitive (okänslig) är normalt FALSE (FALSK) och skickas med det reguljära uttrycket.

Egenskapen minimal är normalt FALSE (FALSK) och skickas med det reguljära uttrycket.

Eftersom reglerna alltid matchas mot början av den nuvarande strängen, så anger ett reguljärt uttryck som börjar med en hatt (^) att regeln bara ska matchas mot radens början.

Se Reguljära uttryck för mer information om dem.

keyword

Detektera ett nyckelord från en angiven lista.

<keyword String="(listnamn)" (gemensamma egenskaper) (lokala avgränsare)/>

Egenskapen String identifierar en lista på nyckelord med namn. En lista med det namnet måste finnas.

Färgläggningssystemet behandlar nyckelordsregler på ett mycket optimerat sätt. Det gör det absolut nödvändigt att alla nyckelord som ska matchas måste omges med definierade avgränsare, antingen underförstått (standardavgränsare) eller explicit definierade inne i egenskapen additionalDeliminator i taggen keywords.

Om ett nyckelord som ska matchas måste innehålla ett skiljetecken, måste detta tecken läggas till i egenskapen weakDeliminatori taggen keywords. Detta tecken förlorar då sin avgränsningsegenskap i alla regler med keyword. Det är också möjligt att använda egenskapen weakDeliminator i keyword så att ändringen bara gäller den regeln.

Int

Detektera ett heltal (som det reguljära uttrycket: \b[0-9]+).

<Int (gemensamma egenskaper) (lokala avgränsare) />

Den här regeln har inga specifika egenskaper.

Float

Detektera ett flyttal (som det reguljära uttrycket: (\b[0-9]+\.[0-9]*|\.[0-9]+)([eE][-+]?[0-9]+)?).

<Float (gemensamma egenskaper) (lokala avgränsare) />

Den här regeln har inga specifika egenskaper.

HlCOct

Detektera en oktal talrepresentation (som det reguljära uttrycket: \b0[0-7]+).

<HlCOct (gemensamma egenskaper) (lokala avgränsare) />

Den här regeln har inga specifika egenskaper.

HlCHex

Detektera en hexadecimal talrepresentation (som det reguljära uttrycket: \b0[xX][0-9a-fA-F]+).

<HlCHex (gemensamma egenskaper) (lokala avgränsare) />

Den här regeln har inga specifika egenskaper.

HlCStringChar

Detektera ett undantaget tecken.

<HlCStringChar (gemensamma egenskaper) />

Den här regeln har inga specifika egenskaper.

Det matchar bokstavsrepresentationer av osynliga tecken som ofta används i programkod, till exempel \n (nyrad) eller \t (tabulator).

Följande tecken matchar om de följer ett bakstreck (\): abefnrtv"'?. Dessutom matchar undantagna hexadecimala tal, som till exempel \xff och undantagna oktala tal, till exempel \033.

HlCChar

Detektera ett C-tecken.

<HlCChar (gemensamma egenskaper) />

Den här regeln har inga specifika egenskaper.

Det matchar C-tecken omgivna av apostrofer (till exempel 'c'). Apostroferna kan innehålla ett enkelt tecken eller en teckenföljd. Se HlCStringChar för matchade teckenföljder.

RangeDetect

Detektera en sträng med definierade start- och sluttecken.

<RangeDetect char="(tecken)"  char1="(tecken)" (gemensamma egenskaper) />

char definierar tecknet som inleder intervallet, och char1 tecknet som avslutar intervallet.

Användbar för att till exempel detektera små strängar inom citationstecken och liknande, men observera att eftersom färgläggningen arbetar med en rad i taget, så hittar det inte strängar som fortsätter på nästa rad.

LineContinue

Matchar ett angivet tecken vid radens slut.

<LineContinue (gemensamma egenskaper) [char="\"] />

Egenskapen char definierar valfritt tecken som ska matchas, förval är bakstreck ('\'). Ny sedan KDE 4.13.

Regeln är användbar för att byta sammanhang vid radslut. Det behövs till exempel i C/C++ för att fortsätta makron eller strängar.

IncludeRules

Inkludera regler från ett annat sammanhang eller språk/fil.

<IncludeRules context="sammanhangslänk" [includeAttrib="true|false"] />

Egenskapen context definierar vilket sammanhang som ska inkluderas.

Om den är en enkelt sträng innehåller den alla definierade regler i det nuvarande sammanhanget, till exempel:

<IncludeRules context="annat-sammanhang" />

Om strängen innehåller ## letar färgläggningssystemet efter ett sammanhang från en annan språkdefinition med angivet namn, exempelvis skulle

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

inkludera sammanhanget String från färgläggningsdefinitionen av C++.

Om egenskapen includeAttrib är true, ändras målegenskapen till källans egenskap. Det krävs till exempel för att kommentarer ska fungera om text som matchas av det inkluderade sammanhanget har en annan färgläggning än värdsammanhanget.

DetectSpaces

Detektera blanktecken.

<DetectSpaces (gemensamma egenskaper) />

Den här regeln har inga specifika egenskaper.

Använd den här regeln om du vet att det kan finnas flera blanktecken framför, till exempel i början av indenterade rader. Regeln hoppar över alla blanktecken på en gång, istället för att prova flera regler och hoppa över en åt gången eftersom den inte matchar.

DetectIdentifier

Detektera strängar för identifierare (som det reguljära uttrycket: [a-zA-Z_][a-zA-Z0-9_]*).

<DetectIdentifier (gemensamma egenskaper) />

Den här regeln har inga specifika egenskaper.

Använd den här regeln för att hoppa över en sträng med ordtecken på en gång, istället för att testa den med flera regler och hoppa ett steg i taget beroende på att ingenting matchar.