Seções principais dos arquivos de Definições de Realce do KatePart

Um arquivo de realce contém um cabeçalho que define a versão do XML:

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

A raiz do arquivo de definição é o elemento language. Os atributos disponíveis são:

Atributos necessários:

O name define o nome da linguagem. Ele aparece nos respectivos menus e janelas.

O section indica a categoria.

O extensions define as extensões dos arquivos, como por exemplo, "*.cpp;*.h"

O version especifica a revisão atual do arquivo de definição em termos de um número inteiro. Sempre que você alterar um arquivo de definição de realce, certifique-se de aumentar esse número.

O kateversion indica a última versão suportada pelo KatePart.

Atributos opcionais:

O mimetype associa os arquivos do tipo MIME.

O casesensitive define se as palavras-chave fazem distinção entre maiúsculas e minúsculas.

O priority é necessário se outro arquivo de definições de realce usar as mesmas extensões. Ganhará o que tiver maior prioridade.

O author contém o nome do autor e o seu endereço de e-mail.

O license contém a licença, que é normalmente a licença MIT para novos arquivos de realce de sintaxe.

O style contém a linguagem fornecida e é usado pelos sistemas de recuo para o atributo required-syntax-style.

O indenter define qual indentador será usado por padrão. Os indentadores disponíveis são: ada, normal, cstyle, cmake, haskell, latex, lilypond, lisp, lua, pascal, python, replicode, ruby e xml.

O hidden define se o nome deverá aparecer nos menus do KatePart.

Assim, a próxima linha se parece com o seguinte:

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

A seguir vem o elemento highlighting, que contém o elemento opcional list e os elementos obrigatórios contexts e itemDatas.

O elemento list contém uma lista de palavras-chave. Neste caso, as palavras-chave são a class e a const.Você poderá adicionar tantas listas quanto desejar.

Desde o KDE Frameworks™ 5.53, uma lista pode incluir palavras-chave de outra lista ou linguagem/arquivo, usando o elemento include. O ## é usado para separar o nome da lista e o nome da definição da linguagem, da mesma forma que na regra IncludeRules. Isso é útil para evitar a duplicação de listas de palavras-chave, caso você precise incluir as palavras-chave de outra linguagem/arquivo. Por exemplo, a lista othername contém a palavra-chave str e todas as palavras-chave da lista types, que pertence à linguagem ISO C++.

O elemento contexts contém todos os contextos. O primeiro contexto é, por padrão, o início do realce. Existem duas regras no contexto Normal Text (Texto Normal), que correspondem à lista de palavras-chave com o nome um_nome e uma regra que detecta aspas e muda o contexto para string (cadeia de caracteres). Para aprender mais sobre as regras, leia o próximo capítulo.

A terceira parte é o elemento itemDatas. Contém todas as cores e estilos de fonte necessários pelos contextos e regras. Neste exemplo, são usados o itemData de Normal Text (Texto Normal), String (Cadeia de Caracteres) e Keyword (Palavra-Chave).

<highlighting>
    <list name="somename">
      <item>class</item>
      <item>const</item>
    </list>
    <list name="othername">
      <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="somename" />
        <keyword attribute="Keyword" context="#stay" String="othername" />
        <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>

A última parte de uma definição de realce é a seção opcional general. Ela poderá conter informações sobre as palavras-chave, expansão/recolhimento de código, comentários, recuo, linhas vazias e verificação ortográfica.

A seção comment define com que texto é introduzido um comentário para uma única linha. Você poderá também definir comentários multilinha, usando o multiLine com o atributo adicional end. Isto é usado se o usuário pressionar o atalho correspondente para comentar/descomentar.

A seção keywords define se as listas de palavras-chave fazem distinção entre maiúsculas e minúsculas ou não. Os outros atributos serão explicados mais tarde.

As outras seções, folding, emptyLines e spellchecking, geralmente não são necessárias e serão explicadas posteriormente.

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

O elemento context pertence ao grupo contexts. Um contexto, por si só, define as regras específicas do contexto, como o que deve acontecer se o sistema de realce chegar ao fim de uma linha. Os atributos disponíveis são:

O name declara o nome do contexto. As regras irão usar esse nome para indicar o contexto para onde mudar, se a regra corresponder.

O attribute identifica o estilo a ser usado para um caractere quando nenhuma regra corresponde ou quando uma regra não especifica um atributo. Neste último caso, o attribute do contexto especificado no context da regra será usado.

O lineEndContext define o contexto para onde o sistema de realce salta, se atingir o fim de uma linha. Poderá ser o nome de outro contexto, o #stay para não mudar de contexto (por exemplo, não fazer nada) ou o #pop que fará com que saia deste contexto. É possível usar, por exemplo, #pop#pop#pop para sair de dentro de três contextos, ou ainda #pop#pop!OutroContexto para sair duas vezes e mudar para o contexto OutroContexto. Também é possível alternar para um contexto que pertence a outra definição de linguagem, da mesma forma que nas regras IncludeRules, por exemplo, AlgumContexto##JavaScript. As mudanças de contexto também são descritas em “Regras de Detecção de Realce”. Padrão: #stay.

O lineEmptyContext define o contexto, se for encontrada uma linha em branco. A nomenclatura das mudanças de contexto é a mesma que a descrita anteriormente em lineEndContext. Padrão: #stay.

O fallthroughContext especifica o próximo contexto para o qual alternar caso nenhuma regra corresponda. A nomenclatura das mudanças de contexto é a mesma descrita anteriormente em lineEndContext. Padrão: #stay.

O fallthrough define se o sistema de realce alterna para o contexto especificado em fallthroughContext caso nenhuma regra corresponda. Observe que, desde o KDE Frameworks™ 5.62, este atributo está obsoleto em favor de fallthroughContext, pois, se o atributo fallthroughContext estiver presente, subentende-se implicitamente que o valor de fallthrough é true. Padrão: false.

O noIndentationBasedFolding desativa o recolhimento baseado em indentação no contexto. Se o recolhimento baseado em indentação não estiver ativado, este atributo é inútil. Ele é definido no elemento folding do grupo general. Padrão: false.

O elemento itemData está no grupo itemDatas. Define o estilo e as cores da fonte. Assim, é possível definir os seus próprios estilos e cores. Contudo, recomenda-se que usar os estilos predefinidos, para que o usuário veja sempre as mesmas cores usadas em várias linguagens. Todavia, existem casos em que não existe outra forma e, assim, é necessário mudar os atributos de cores e tipos de fonte. Os atributos 'name' e 'defStyleNum' são obrigatórios, enquanto os outros são opcionais. Os atributos disponíveis são:

O name define o nome do 'itemData'. Os contextos e regras irão usar este nome no seu atributo attribute, para referenciar um 'itemData'.

O defStyleNum define qual o estilo padrão usar. Os estilos pré-definidos disponíveis são explicados mais tarde em detalhes.

O color define uma cor. Os formatos válidos são o '#rrggbb' ou '#rgb'.

O selColor define a cor da seleção.

O italic, se for true (verdadeiro), irá colocar o texto em itálico.

O bold, se for true (verdadeiro), irá colocar o texto em negrito.

O underline, se for true (verdadeiro), irá colocar o texto sublinhado.

O strikeOut, se for true (verdadeiro), o texto ficará traçado.

O spellChecking, se for true (verdadeiro), será verificada a ortografia do texto.

O elemento keywords, no grupo general, define as propriedades das palavras-chave. Os atributos disponíveis são:

O casesensitive poderá ser true (verdadeiro) ou false (falso). Se for true, todas as palavras-chave farão distinção entre maiúsculas e minúsculas.

O weakDeliminator é uma lista de caracteres que não irão atuar como separadores de palavras. Por exemplo, o ponto '.' é um separador de palavras. Assuma que uma palavra-chave num list contém um ponto; nesse caso, só irá corresponder se indicar que o ponto é um delimitador fraco.

O additionalDeliminator define os delimitadores ou separadores adicionais.

O wordWrapDeliminator define os caracteres após os quais poderá ocorrer uma mudança de linha.

Os delimitadores pré-definidos e de mudança de linha são os caracteres .():!+,-<=>%&*/;?[]^{|}~\, o espaço (' ') e a tabulação ('\t').

O elemento comment no grupo comments define propriedades de comentário que são usadas para: Ferramentas → Comentar, Ferramentas → Descomentar e Ferramentas → Alternar comentário. Os atributos disponíveis são:

O name tanto poderá ser singleLine como multiLine. Se escolher o multiLine, serão necessários os atributos end e region. Se escolher singleLine, poderá adicionar o atributo opcional position.

O start define o texto usado para iniciar um comentário. No C++, este será o "/*" em comentários de várias linhas. Este atributo é obrigatório para os tipos multiLine e singleLine.

O end define o texto usado para fechar um comentário. No C++, será o "*/". Este atributo está disponível apenas e é obrigatório para comentários do tipo multiLine.

O region deverá ser o nome do comentário multi-linhas que poderá expandir ou recolher. Assuma que tem o beginRegion="Comment" ... endRegion="Comment" nas suas regras; nesse caso, deverá usar o region="Comment". Desta forma, a remoção de comentários funciona, mesmo que não tenha selecionado todo o texto do comentário multi-linhas. O cursor só precisa estar dentro deste comentário. Este atributo está disponível apenas para o tipo multiLine.

O position define onde o comentário de linha única é inserido. Por padrão, o comentário de linha única é colocado no início da linha na coluna 0, mas se você usar position="afterwhitespace" o comentário é inserido após os espaços em branco iniciais à direita, antes do primeiro caractere que não seja um espaço em branco. Isso é útil para colocar comentários corretamente em linguagens onde a indentação é importante, como Python ou YAML. Este atributo é opcional e o único valor possível é afterwhitespace. Isso só está disponível para o tipo singleLine.

O elemento folding, no grupo general, define as propriedades de dobragem/desdobramento do código. Os atributos disponíveis são:

O indentationsensitive, se for true, aplicará os marcadores de dobragem de código com base no recuo, como acontece na linguagem de programação Python. Normalmente você não terá que definir isto, uma vez que o valor padrão é false.

O elemento emptyLine no grupo emptyLines define quais linhas devem ser tratadas como linhas vazias. Isso permite modificar o comportamento do atributo lineEmptyContext nos elementos context. Os atributos disponíveis são:

O regexpr define uma expressão regular que será tratada como uma linha em branco. Por padrão, linhas em branco não contêm nenhum caractere; portanto, isso adiciona linhas em branco adicionais, por exemplo, se você quiser que linhas com espaços também sejam consideradas linhas em branco. No entanto, na maioria das definições de sintaxe, você não precisa definir esse atributo.

O elemento encoding no grupo spellchecking define uma codificação de caracteres para a verificação ortográfica. Atributos disponíveis:

O char é um caractere codificado.

O string é uma sequência de caracteres que será codificada como o caractere char na verificação ortográfica. Por exemplo, na linguagem LaTeX, a string \"{A} representa o caractere Ä.

Estilos padrão gerais:

dsNormal, quando não é necessário nenhum realce em especial.

dsKeyword, para as palavras-chave do idioma incorporadas.

dsFunction, nas chamadas e definições de funções.

dsVariable, se aplicável: nomes das variáveis (por exemplo $algumaVariavel em PHP/Perl).

dsControlFlow, palavras-chave de controle de fluxo, como o 'if', 'else', 'switch', 'break', 'return', 'yield', ...

dsOperator, operadores como o + - * / :: < >

dsBuiltIn, nas funções, classes e objetos incorporados.

dsExtension, extensões comuns, como as classes e funções/macros do Qt™ em C++ e Python.

dsPreprocessor, para as instruções do pré-processador ou para as definições de macros.

dsAttribute, anotações como o @override e o __declspec(...).

Estilos padrão relacionados com as strings:

dsChar, para caracteres únicos, como o 'x'.

dsSpecialChar, caracteres com significados especiais nas strings, como as sequências de escape, substituições ou operadores de expressões regulares.

dsString, para strings do tipo "olá mundo".

dsVerbatimString, strings literais como o 'raw \backlash' do Perl, CoffeeScript e das linhas de comando, assim como o r'\raw' do Python.

dsSpecialString, SQL, expressões regulares, documentação, modo matemático do L^AT_EX, ...

dsImport, importação, inclusão ou requisição de módulos.

Estilos padrão relacionados com números:

dsDataType, para os tipos de dados incorporados, como o 'int', 'void', 'u64'.

dsDecVal, nos valores decimais.

dsBaseN, nos valores com uma base diferente de 10.

dsFloat, nos valores de ponto flutuante.

dsConstant, nas constantes incorporadas e definidas pelo usuário, como o PI.

Estilos padrão de comentários e relacionados com a documentação:

dsComment, para comentários.

dsDocumentation, para /** Comentários de documentação */ ou """strings de documentação""".

dsAnnotation, para os comandos de documentação como o @param, @brief.

dsCommentVar, os nomes das variáveis usadas nos comandos acima, como o "foobar" no @param foobar.

dsRegionMarker, para marcadores de região, como o //BEGIN, //END nos comentários.

Outros estilos padrão:

dsInformation, notas e dicas do tipo @note no doxygen.

dsWarning, para os avisos do tipo @warning no doxygen.

dsAlert, para palavras especiais como o TODO, FIXME, XXXX.

dsError, para realçar erros e sintaxes inválidas.

dsOthers, quando nada mais se aplica.

DetectChar

Detecta um caractere específico. Comumente usado, por exemplo, para encontrar o final das strings citadas.

<DetectChar char="(caractere)" (atributos comuns) (dinâmico) />

O atributo char define o caractere a ser procurado.

Detect2Chars

Detecta dois caracteres específicos, em uma ordem definida.

<Detect2Chars char="(caractere)" char1="(caractere)" (atributos comuns) />

O atributo char define o primeiro caractere a ser procurado, e o atributo char1 o segundo.

Esta regra existe por razões históricas e, para facilitar a leitura, é preferível usar StringDetect.

AnyChar

Detecta um caractere de um conjunto de caracteres especificados.

<AnyChar String="(string)" (atributos comuns) />

O atributo String define o conjunto de caracteres.

StringDetect

Detecta uma string exata.

<StringDetect String="(string)" [insensitive="true|false;"] (atributos comuns) (dinâmico) />

O atributo String define a sequência a encontrar. O atributo insensitive é por padrão false e é passado à função de comparação de cadeias de caracteres. Se o valor for true a comparação não faz distinção entre maiúsculas e minúsculas.

WordDetect

Detecta um texto exato, mas obriga adicionalmente a que esteja rodeado por limites de palavras, como um ponto '.' ou um espaço em branco no início e no fim da palavra. Pense em \b<texto>\b em termos de uma expressão regular, só que é mais rápido que a regra Exp Reg.

<WordDetect String="(string)" [insensitive="true|false;"] (atributos comuns) (delimitadores locais) />

O atributo String define a sequência a encontrar. O atributo insensitive é por padrão false e é passado à função de comparação de cadeias de caracteres. Se o valor for true a comparação não faz distinção entre maiúsculas e minúsculas.

Desde: Kate 3.5 (KDE 4.5)

RegExpr

Procura por uma expressão regular.

<RegExpr String="(texto)" [insensitive="true|false"] [minimal="true|false"] (atributos comuns) (dinâmico) />

O atributo String define a expressão regular.

O insensitive é, por padrão, false e é passado ao motor de expressões regulares.

O minimal é, por padrão, false e é passado ao motor de expressões regulares.

Pelo motivo que as regras estão sempre iniciando a busca no início da string atual, uma expressão regular iniciada com um acento circunflexo (^ ) indica que a regra deve ser coincidente somente no início da linha.

Veja em Expressões Regulares mais informações sobre o assunto.

keyword

Detecta uma palavra-chave de uma lista especificada.

<keyword String="(nome da lista)" (atributos comuns) (delimitadores locais) />

O atributo String identifica a lista de palavras-chave pelo nome. Uma lista com aquele nome, portanto, deve existir.

O sistema de realce processa as regras da palavra-chave de forma muito otimizada. Isto a torna uma necessidade absoluta em que quaisquer palavras-chave a corresponder sejam envolvidas por separadores definidos, sejam eles implícitos (os separadores padrão) ou explícitos, com a propriedade additionalDeliminator da marca keywords.

Se uma palavra-chave a corresponder conter um caractere separador, este caractere respectivo deverá ser adicionado à propriedade weakDeliminator da marca keywords. Este caractere irá então perder a sua propriedade de separador em todas as regras keyword. Também é possível usar o atributo weakDeliminator de keyword para que esta modificação se aplique apenas a esta regra.

Int

Detecta um número inteiro (como a expressão regular: \b[0-9]+).

<Int (atributos comuns) (delimitadores locais) />

Esta regra não possui atributos específicos.

Float

Detecta um número de ponto flutuante (como a expressão regular: (\b[0-9]+\.[0-9]*|\.[0-9]+)([eE][-+]?[0-9]+)?).

<Float (atributos comuns) (delimitadores locais) />

Esta regra não possui atributos específicos.

HlCOct

Detecta uma representação de número de ponto octal (como a expressão regular: \b0[0-7]+).

<HlCOct (atributos comuns) (delimitadores locais) />

Esta regra não possui atributos específicos.

HlCHex

Detecta uma representação numérica hexadecimal (como uma expressão regular: \b0[xX][0-9a-fA-F]+).

<HlCHex (atributos comuns) (delimitadores locais) />

Esta regra não possui atributos específicos.

HlCStringChar

Detecta um caractere de escape.

<HlCStringChar (atributos comuns) />

Esta regra não possui atributos específicos.

Corresponde a representações literais dos caracteres usados normalmente no código do programa como, por exemplo, o \n (nova linha) ou o \t (TAB).

Os seguintes caracteres irão corresponder se estiverem após uma barra invertida (\): abefnrtv"'?\. Além disso, os números escapados em hexadecimal como, por exemplo, o \xff e os números octais escapados, como o \033, irão corresponder.

HlCChar

Detecta um caractere do C.

<HlCChar (atributos comuns) />

Esta regra não possui atributos específicos.

Corresponde aos caracteres em C colocados dentro de um tique (Exemplo: 'c'). Os tiques podem ser um único caractere ou um caractere de escape. Veja o 'HlCStringChar' para ver as sequências de caracteres de escape correspondentes.

RangeDetect

Detecta uma string com os caracteres de início e fim definidos.

<RangeDetect char="(caractere)"  char1="(caractere)" (atributos comuns) />

O char define o caractere de início e o char1 o caractere que termina o intervalo.

Útil para detectar, por exemplo, pequenas cadeias de caracteres entre aspas e semelhantes, mas repare que, uma vez que o motor de realce de sintaxe funciona com uma linha de cada vez, isto não irá encontrar as cadeias de caracteres que se prolonguem por mais de uma linha.

LineContinue

Corresponde um caractere específico indicado no fim de uma linha.

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

O atributo char define o caractere opcional a ser encontrado, sendo a barra invertida ('\'). o padrão. Novidade da versão 4.13 do KDE.

Esta regra é útil para mudar de contexto no fim da linha. Isso é necessário no C/C++, por exemplo, para continuar as macros ou cadeias de caracteres.

IncludeRules

Inclui as regras de outro contexto ou linguagem/arquivo.

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

O atributo context define o contexto a incluir.

Se for texto simples, inclui todas as regras definidas no contexto atual, como por exemplo:

<IncludeRules context="outroContexto" />

Se o texto conter um ##, o sistema de realce irá procurar por um contexto de outra definição de linguagem com o nome indicado, por exemplo,

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

iria incluir o contexto String da definição de realce C++.

Se o atributo includeAttrib for true, muda o atributo de destino para o da origem. Isto é necessário para fazer, por exemplo, funcionar os comentários, se o texto correspondente ao contexto incluído for de um realce diferente do contexto-anfitrião.

DetectSpaces

Detecta espaços em branco.

<DetectSpaces (atributos comuns) />

Esta regra não possui atributos específicos.

Use esta regra se souber que poderão existir vários espaços em branco à frente como, por exemplo, no início das linhas recuadas. Esta regra irá ignorar todos os espaços em branco, em vez de testar várias regras e ignorar uma de cada vez, devido a uma falta de correspondência.

DetectIdentifier

Detecta os textos dos identificadores (como a expressão regular: [a-zA-Z_][a-zA-Z0-9_]*).

<DetectIdentifier (atributos comuns) />

Esta regra não possui atributos específicos.

Use esta regra para ignorar uma sequência de caracteres de palavras de uma vez, em vez de testar com várias regras e ignorar uma de cada vez, por falta de correspondência.