# Ampliando o &katepart;

## Introdução

Como em qualquer componente de editor de texto avançado, o &katepart; oferece uma grande variedade de formas para ampliar suas funcionalidades. Você pode criar scripts simples para adicionar funcionalidades com o JavaScript Finalmente, assim que tiver ampliado as funcionalidades do &katepart;, sinta-se a vontade para se juntar a nós e compartilhar as suas melhorias com o mundo!

## Trabalhando com Realce de Sintaxe

### Introdução

O Realce de Sintaxe é o que faz com que o editor exiba automaticamente o texto em diferentes cores/estilos, dependendo da função da string em questão para o propósito do arquivo. No código-fonte do programa, por exemplo, declarações de controle pode ser renderizadas em negrito, enquanto tipos de dados e comentários ficam com cores diferentes do restante do texto. Isto aumenta consideravelmente a legibilidade do texto e assim, o autor pode ser mais eficiente e produtivo.

Uma função Perl, representada com realce de sintaxe.

Uma função Perl, representada com realce de sintaxe.

A mesma função Perl, sem realce de sintaxe.

A mesma função Perl, sem realce de sintaxe.

Dos dois exemplos, qual é o mais fácil de ler?

O &kappname; vem com um sistema flexível, configurável e capaz de fazer realce de sintaxe; a distribuição padrão oferece definições para um vasto conjunto de linguagens de programação, de manipulação e de 'scripting', bem como para outros formatos de texto. Além disso, você pode criar as suas próprias definições em arquivos &XML; simples.

O &kappname; detectará automaticamente regras de realce de sintaxe quando você abrir um arquivo, baseado no tipo &MIME; do arquivo, determinado pela extensão ou, se não existir, pelo conteúdo. Se você não conseguir, ajuste manualmente a sintaxe para o uso no menu Ferramentas Realçar.

Os estilos e cores usados por cada definição de realce de sintaxe podem ser configurados usando a página de Estilos de Realce de Texto da Janela de Configuração; por outro lado, os tipos &MIME; e as extensões de arquivos para os quais deve ser usada, podem ser configurados usando a página de Modos & Tipos de Arquivo.

O realce de sintaxe existe para aumentar a legibilidade do texto correto, mas não se pode confiar nisto para validar seu texto. Marcar o texto para sintaxe é difícil, dependendo do formato que você está usando e, em alguns casos, os autores das regras de sintaxe ficarão orgulhosos se 98% do texto é renderizado corretamente, embora muito frequentemente você precise de um estilo raro para ver os 2% incorretos.

Você pode baixar as definições de sintaxe adicionais ou atualizadas na página Web do &kappname; clicando no botão Baixar Arquivos de Sintaxe... na página Modos & Tipos de Arquivo da Janela de Configuração.

### O Sistema de Realce de Sintaxe do &kappname;

Esta seção irá discutir o realce de sintaxe do &kappname; em detalhes. É para você, caso deseje saber mais sobre esta funcionalidade ou se quiser criar ou alterar as definições de sintaxe.

#### Como funciona

Sempre que você abrir um arquivo, uma das primeiras coisas que o editor &kappname; faz é detectar qual definição de sintaxe deve ser usada para o arquivo. Ao ler o texto do arquivo, e enquanto você digita no arquivo, o sistema de realce de sintaxe analisará o texto usando as regras definidas pela definição de sintaxe, e marcará no texto onde contexto e estilos diferentes iniciarem e finalizarem.

Quando você escrever no documento, o novo texto será analisado e marcado na hora, pois se você remover um caractere que está marcado como início ou fim de um contexto, o estilo em volta do texto modifica de acordo com ele.

As definições de sintaxe usadas pelo sistema de realce de sintaxe do &kappname; são arquivos &XML; que contém

- Regras para a detecção do texto inteiro, organizado em blocos de contexto

- Listas de palavras-chave

- Definições de Item de Estilo

Ao analisar o texto, as regras de detecção serão avaliadas na ordem em que foram definidas, e se o início da string atual coincidir com uma regra, o contexto relacionado será usado. O ponto de partida no texto é movido para o ponto final no local onde aquela regra coincide, e um novo loop de regras inicia, começando no contexto configurado pela regra relacionada.

#### Regras

As regras de detecção são o "coração" do sistema de detecção de sintaxe. Uma regra é uma string, um caractere ou uma expressão regular com a qual se faz a correspondência do texto a analisar. Contém informações sobre o estilo a ser usado na parte correspondente do texto. Pode mudar do contexto atual do sistema para outro contexto explícito ou para o contexto anterior usado pelo texto.

As regras são organizadas em grupos de contexto, sendo que este é usado pelos conceitos principais do texto dentro de um formato, como por exemplo strings dentro de aspas ou blocos de comentário do código-fonte de um programa. Isto garante que o sistema de realce não precisa ficar procurando todas as regras quando não for necessário, e também que sequências de algum caractere no texto podem ser tratadas de modo diferente, dependendo do contexto atual.

As regras são organizadas em grupos de contexto, sendo que este é usado pelos conceitos principais do texto dentro de um formato, como por exemplo strings dentro de aspas ou blocos de comentário do código-fonte de um programa. Isto garante que o sistema de realce não precisa ficar procurando todas as regras quando não for necessário, e também que sequências de algum caractere no texto podem ser tratadas de modo diferente, dependendo do contexto atual.

#### Estilos de Contexto e Palavras-Chave

Em algumas linguagens de programação, os números inteiros são tratados diferentemente dos números de ponto flutuante pelo compilador (o programa que converte o código-fonte para um binário executável), e podem existir caracteres que possuem significado especial dentro de uma string. Em tais casos, faz sentido renderizá-los de modo diferente dos outros, assim, são mais fáceis de identificar durante a leitura do texto. Mesmo que eles não sejam representados em contextos especiais, pode ser vistos no sistema de realce de sintaxe, e assim, podem ser marcados com uma renderização diferente.

Uma definição de sintaxe pode conter tantos estilos quanto forem necessários para cobrir os conceitos do formato no qual serão usados.

Em muitos formatos, existem listas de palavras, que representam um conceito específico; por exemplo, em linguagens de programação, as declaração de controle são um conceito, nomes de tipos de dados outro conceito, e funções pré-integradas na linguagem um terceiro conceito. O Sistema de Realce de Sintaxe do &kappname; pode usar estas listas para detectar e marcar palavras no texto para enfatizar os conceitos dos formatos.

#### Estilos Padrão

Se você abrir um arquivo de código em C++, um arquivo de &Java; e um documento em HTML no &kappname;, irá ver que, ainda que os formatos sejam diferentes e, por isso, sejam selecionadas palavras diferentes para um tratamento especial, as cores usadas são as mesmas. Isto deve-se ao fato do &kappname; ter uma lista pré-definida de Estilos Padrão, os quais são usados pelas definições de sintaxe individuais.

Isto faz com que fique mais fácil reconhecer conceitos similares em diferentes formatos. Por exemplo, os comentários estão presentes na maioria das linguagens de programação, script e marcação, e quando são renderizados utilizando-se o mesmo estilo em todas as linguagens, você não precisa parar e pensar para identificá-los dentro do texto.

Todos os estilos de uma definição de sintaxe usam um dos estilos padrão. Algumas definições de sintaxe usam mais estilos além dos pré-definidos, por isso se você usar um formato frequentemente, pode ser útil abrir a janela de configuração para ver se alguns conceitos usam o mesmo estilo. Por exemplo, só existe um estilo padrão para as cadeias de caracteres, mas como a linguagem de programação Perl lida com dois tipos de cadeias de caracteres, você pode melhorar o realce se configurar esses dois tipos de uma forma ligeiramente diferente. Todos os estilos padrão disponíveis serão explicados mais tarde.

### O Formato &XML; de Definição de Realce

#### Introdução

Esta seção é uma introdução ao formato &XML; de Definição de Realce. Baseado em um pequeno exemplo, ele irá descrever as componentes principais, bem como o seu significado e utilização. A próxima seção colocará em detalhes as regras de detecção.

A definição formal, também conhecida como XSD, é armazenada no arquivo `language.xsd`, o qual deve estar instalado na pasta `$`XDG_DATA_DIRS`/katepart5/syntax` do seu sistema. Nesse sentido, a variável de ambiente `XDG_DATA_DIRS` normalmente se expande para `/usr/share`.

#### Seções principais dos arquivos de Definições de Realce do &kappname;

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"

  Atributos opcionais:

  O `mimetype` associa os arquivos do tipo &MIME;.

  O `version` indica a versão atual do arquivo de definição.

  O `kateversion` indica a última versão suportada pelo &kappname;.

  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 LGPL, a Artistic, a GPL ou outras.

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

  O `hidden` define se o nome deverá aparecer nos menus do &kappname;.

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

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

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

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 e recuo.

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

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

#### As Seções em Detalhe

Esta parte irá descrever todos os atributos disponíveis para o 'contexts', o 'itemDatas', o 'keywords', o 'comments', a expansão de código e o recuo.

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:

- `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 `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 (⪚, 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`.

  O `lineEmptyContext` define o contexto, se for encontrada uma linha em branco. Padrão: #stay.

  O `fallthrough` define se o sistema de realce salta para o contexto indicado em 'fallthroughContext' se não corresponder nenhuma regra. Padrão: false.

  O `fallthroughContext` define o próximo contexto, se nenhuma regra corresponder.

  O `dynamic`, se for true (verdadeiro), fará com que o contexto recorde os textos/sequências de substituição gravados pelas regras dinâmicas. Isto é necessário, por exemplo, para os documentos do HERE. 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 as propriedades dos comentários que são usadas nas opções Ferramentas Comentar e Ferramentas Descomentar. 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.

  O `start` define o texto usado para iniciar um comentário. No C++, este será o "/*".

  O `end` define o texto usado para fechar um comentário. No C++, será o "*/".

  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.

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 `indentation`, no grupo `general`, define qual o sistema de recuo será usado. Contudo, recomenda-se omitir esse elemento, uma vez que o sistema de recuo será normalmente definido a partir de um Tipo de Arquivo ou através da adição da linha de modo no arquivo de texto. Se você indicar um sistema de recuo, todavia, irá obrigar o usuário a usar um sistema de recuo específico, o que poderá não ser o que ele quer. Os atributos disponíveis são:

- O `mode` é o nome do sistema de recuo. Os sistemas disponíveis atualmente são: normal, cstyle, haskell, lilypond, lisp, python, ruby e xml.

#### Estilos Padrão Disponíveis

Os estilos padrão já foram explicados, em resumo: Os estilos padrão são os estilos de cores e fontes pré-definidos.

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 LaTeX, ...

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

### Regras de Detecção de Realce

Esta seção descreve as regras de detecção de sintaxe.

Cada regra pode corresponder a zero ou mais caracteres no início do texto que é testado. Se a regra corresponder, é atribuído o estilo ou atributo definido pela regra aos caracteres correspondentes; uma regra poderá perguntar se o contexto atual será alterado.

As regras se parecem com isto:

    <NomeRegra attribute="(identificador)" context="(identifier)" [atributos específicos da regra] />

O attribute identifica o estilo a usar para os caracteres correspondentes pelo nome ou índice; o context identifica, como esperado, o contexto a usar a partir daqui.

O context pode ser identificado por:

- Um identificador, que é o nome do outro contexto.

- Uma ordem diz ao mecanismo para ficar no contexto atual (`#stay`), ou voltar a usar um contexto usado anteriormente na string (`#pop`).

  Para voltar mais passos, a palavra-chave #pop pode ser repetida: `#pop#pop#pop`

- Uma ordem seguida de um ponto de exclamação (!) e um identificador, que fará com que o mecanismo siga primeiro a ordem e depois mude para o outro contexto, por exemplo, `#pop#pop!OtherContext`.

Algumas regras podem ter regras-filhas, as quais podem ser avaliadas se e só se a regra-mãe foi verificada. O texto inteiro verificado terá o atributo definido pela regra-mãe. Uma regra com regras-filhas se pareceria com a seguinte:

    <NomedaRegra (atributos)>
      <NomedaRegraFilha (atributos) />
      ...
    </NomedaRegra>

Os atributos específicos da regra variam e estão descritos nas seções a seguir.

### Atributos comuns

Todas as regras possuem os seguintes atributos em comum e estão disponíveis sempre que os `(atributos comuns)` aparecerem. O attribute e o context são atributos obrigatórios, enquanto os outros são opcionais.

- attribute: Um atributo mapeia-se para um itemData definido.

- context: Indica o contexto para onde muda o sistema de realce, se a regra corresponder.

- beginRegion: Inicia um bloco de dobragem de código. Padrão: não definido.

- endRegion: Fecha uma região de dobragem de código. Padrão: não definido.

- lookAhead: Se for true (verdadeiro), o sistema de realce não irá processar o tamanho da correspondência. Padrão: false.

- firstNonSpace: Corresponder apenas se o texto for o primeiro não-espaço em branco da linha. Padrão: false.

- column: Corresponder apenas se a coluna corresponder. Padrão: não definido.

### Regras dinâmicas

Algumas regras permitem o atributo opcional `dynamic`, do tipo booleano, cujo valor padrão é false. Se o 'dynamic' for true, uma regra poderá usar sequências de substituição que representam o texto correspondente a uma expressão regular que mudou para o contexto atual, nos seus atributos `string` ou `char`. Num `string`, o texto de substituição `%N` (em que o N é um número) será substituído pela captura correspondente a `N` na expressão regular de chamada. Num `char`, a sequência de substituição deverá ser um número `N` que será substituído pelo primeiro caractere da captura `N` da expressão regular de chamada. Sempre que uma regra permitir este atributo, irá conter um (dinâmico).

- dynamic: poderá ser (true|false).

#### As Regras em Detalhes

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) (dinâmico) />

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

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

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

  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.

Int

- Detecta um número inteiro.

      <Int (atributos comuns) (dinâmico) />

  Esta regra não tem atributos específicos. As regras-filho são tipicamente usadas para detectar as combinações de `L` e `U` depois do número, o que indica o tipo inteiro no código do programa. De fato, todas as regras são permitidas como regras-filhas, contudo, o DTD só permite a regra-filha `StringDetect`.

  O exemplo a seguir faz correspondência com os números inteiros, seguidos do caractere 'L'.

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

Float

- Detecta um número de ponto flutuante.

      <Float (atributos comuns) />

  Esta regra não tem atributos específicos. O `AnyChar` é permitido como regra-filha e é tipicamente usada para detectar combinações; veja a regra `Int` para mais referências.

HlCOct

- Detecta uma representação de um número octal.

      <HlCOct (atributos comuns) />

  Esta regra não possui atributos específicos.

HlCHex

- Detecta uma representação de um número hexadecimal.

      <HlCHex (atributos comuns) />

  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 acontece na 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.

#### Dicas & Truques

Logo que tenha compreendido como funciona a mudança de contexto, será fácil de criar definições de realce. Ainda que você deva verificar com cuidado a regra que escolher, dependendo da situação, as expressões regulares são muito poderosas, só que são lentas em comparação com as outras regras. Assim, você poderá considerar útil as seguintes dicas.

- Se você só corresponder com 2 caracteres, use o `Detect2Chars` em vez do `StringDetect`. O mesmo aplica-se ao `DetectChar`.

- As expressões regulares são fáceis de usar mas, normalmente, existe outra forma muito mais rápida de obter o mesmo resultado. Assuma que só deseja corresponder com o caractere `'#'` se for o primeiro caractere da linha. Uma solução baseada em expressões regulares seria semelhante à seguinte:

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

  Você poderá obter o mesmo se usar:

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

  Se quiser corresponder à expressão regular `'^#'`, poderá usar ainda o `DetectChar` com o atributo `column="0"`. O atributo `column` conta como caracteres; assim, uma tabulação conta como se fosse apenas um caractere.

- Você poderá mudar de contextos sem processar os caracteres. Assuma que deseja mudar de contexto quando encontrar o texto `*/`, mas necessita de processar essa sequência no próximo contexto. A regra abaixo irá corresponder e o atributo `lookAhead` fará com que o sistema de realce mantenha o texto correspondente no próximo contexto.

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

- Use o `DetectSpaces` se você souber que irão ocorrer vários espaços em branco.

- Use o `DetectIdentifier` em vez da expressão regular `'[a-zA-Z_]\w*'`.

- Use os estilos padrão sempre que puder. Desta forma, o usuário irá encontrar um ambiente familiar.

- Procure em outros arquivos XML para ver como as outras pessoas implementam as regras mais complicadas.

- Você poderá validar todos os arquivos XML se usar o comando `xmllint --schema language.xsd MinhaSintaxe.xml`.

- Se repetir algumas expressões regulares complexas com frequência, você poderá usar as ENTIDADES. Por exemplo:

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

  Agora, você poderá usar o &referencia; em vez da expressão regular.

## Criação de scripts com JavaScript

O componente de edição do &kappname; é facilmente extensível, através da criação de scripts. A linguagem de programação é o ECMAScript (popularmente conhecido como JavaScript). O &kappname; suporta dois tipos de scripts: os de recuo e os de linha de comando.

### Scripts de recuo

Scripts de recuo - também conhecidos por recuadores - formatam automaticamente o código-fonte enquanto você digita o texto. Por exemplo, depois de pressionar a tecla Return, o nível de recuo costuma aumentar.

As seções a seguir descrevem, passo-a-passo, como criar o esqueleto de um módulo de recuo simples. Como primeiro passo, crie um novo arquivo `*.js`, chamado de, ⪚, `javascript.js` na pasta pessoal local `$`XDG_DATA_HOME`/katepart5/script/indentation`. Nesse sentido, a variável de ambiente `XDG_DATA_HOME` normalmente se expande para qualquer `~/.local` ou `~/.local/share`.

#### O cabeçalho do script de recuo

O cabeçalho do arquivo `javascript.js` está incorporado como JSON no início do documento no seguinte formato:

    var katescript = {
        "name": "JavaScript",
        "author": "Nome de Exemplo <nome.exemplo@endereco.org>",
        "license": "BSD License",
        "revision": 1,
        "kate-version": "5.1",
        "required-syntax-style": "javascript",
        "indent-languages": ["javascript"],
        "priority": 0,
    }; // kate-script-header, deve estar no início do arquivo, sem comentários

Cada item será agora explicado em detalhes:

- `name` [obrigatório]: Este é o nome do modo de recuo que aparece no menu Ferramentas Recuar e na janela de configuração.

- `author` [opcional]: O nome e a informação de contato do autor.

- `license` [opcional]: Forma curta da licença, como por exemplo, BSD License ou LGPLv3.

- `revision` [obrigatório]: A versão do programa. Este número deverá ser aumentado sempre que o programa for modificado.

- `kate-version` [obrigatório]: A versão mínima do &kappname; necessária.

- `required-syntax-style` [opcional]: O estilo do sintaxe necessário, que corresponde ao `style` indicado no sintaxe dos arquivos realçados. Isto é importante para recuadores que se baseiam em informações de realce no documento. Se uma determinada realce de sintaxe dor especificada, o recuador estará disponível somente quando a realce de sintaxe apropriada estiver ativa. Isto evite um comportamento inesperado causado pelo uso do recuador sem o esquema de realce esperado. Por exemplo, o recuado do Ruby faz uso dos arquivos `ruby.js` e `ruby.xml`.

- `indent-languages` [opcional]: Uma lista JSON de estilos de sintaxe que este módulo consegue recuar corretamente, ⪚: `["c++", "java"]`.

- `priority` [opcional]: Se existirem vários módulos de recuo adequados para um determinado arquivo de realce, este campo decide qual deverá ser usado por padrão.

#### O código-fonte do recuador

Tendo definido o cabeçalho, esta seção explica como funciona a programação de recuadores em si. O esqueleto básico do código parece-se com o seguinte:

    // Necessário para as bibliotecas js do katepart, p.ex., range.js se você usar Range
    require ("range.js");

    caracteresAtivacao = "{}/:;";
    function indent(linha, larguraRecuo, caractere)
    {
        // invocado para cada linha nova (caractere == '\n') e todos os caracteres indicados na
        // variável global 'caracteresAtivacao'. Ao invocar o FerramentasAlinhar
        // a variável 'caractere' está em branco, isto é, caractere == ''.
        //
        // ver também: API de Programação
        return -2;
    }

A função `indent()` tem três parâmetros:

- `linha`: a linha que tem de ser recuada

- `larguraRecuo`: o número de espaços correspondentes a cada recuo

- `caractere`: ou um caractere de mudança de linha (`ch == '\n'`), algum dos caracteres de ativação indicados em `caracteresAtivacao` ou vazio, caso o usuário tenha invocado a ação Ferramentas Alinhar.

O valor devolvido pela função `indent()` define como a linha será recuada. Se o valor devolvido for um número inteiro, é interpretado da seguinte forma:

- valor devolvido `-2`: não fazer nada

- valor devolvido `-1`: mantém o recuo (procura pela linha não-vazia anterior)

- valor devolvido `0`: números >= 0 definem a largura do recuo em espaços

Em alternativa, poderá ser devolvida uma lista com dois elementos:

- `return [ recuo, alinhamento ];`

Nesse caso, o primeiro elemento é a profundidade de recuo, tendo o mesmo significado que os valores especiais. Contudo, o segundo elemento é um valor absoluto que representa uma coluna para o alinhamento. Se este valor for maior que o valor do recuo, a diferença representa um número de espaços a adicionar após o recuo do primeiro parâmetro. Caso contrário, o segundo número será ignorado. A utilização de tabulações e espaços nos recuos é normalmente referida como sendo um modo misto.

Considere o seguinte exemplo: Considerando que são usadas as tabulações para recuar, e que o tamanho da tabulação é de 4. Aqui, o <tab> representa uma tabulação e o '.' representa um espaço:

    1: <tab><tab>xpto("olá",
    2: <tab><tab>......."mundo");

Ao recuar a linha 2, a função `indent()` devolve [8, 15]. Em função disso, são introduzidas duas tabulações para recuar até à coluna 8, e são introduzidos 7 espaços para alinhar o segundo parâmetro com o primeiro, de modo a permanecer alinhado, caso o arquivo seja visto com outro tamanho de tabulação.

Uma instalação padrão do &kde; fornece o &kappname; com vários módulos de recuo. O código-fonte correspondente em JavaScript poderá ser encontrado em `$`XDG_DATA_DIRS`/katepart5/script/indentation`.

A criação de um módulo de recuo necessita do recarregamento dos scripts, de modo a ver se as alterações se comportam de forma adequada. Em vez de reiniciar o aplicativo, basta ir para a linha de comando e executar o comando `reload-scripts`.

Se você criar scripts úteis, considere a hipótese de contribuir com eles para o Projeto &kappname;, contactando para isso a lista de correio.

### Scripts de Linha de Comando

Como é difícil satisfazer as necessidades de todos, o &kappname; tem suporte a algumas ferramentas auxiliares para manipular rapidamente o texto, usando para isso a linha de comando incorporada. Por exemplo, o comando `sort` está implementado como um script. Esta seção explica como criar arquivos `*.js` que estendem o &kappname; com algumas funções auxiliares arbitrárias.

Os scripts de linha de comando estão localizados na mesma pasta que os scripts de recuo. Assim, como primeiro passo, crie um arquivo `*.js` novo, chamado `utilitários.js` na pasta pessoal local, em `$`XDG_DATA_HOME`/katepart5/script/commands`. Nesse sentido, a variável de ambiente `XDG_DATA_HOME` normalmente se expande para `~/.local` ou `~/.local/share`.

#### O Cabeçalho do Script de Linha de Comando

O cabeçalho de cada script de linha de comando é está incorporado como JSON no início do script no seguinte formato:

    var katescript = {
        "author": "Nome de exemplo <nome.exemplo@endereco.org>",
        "license": "LGPLv2+",
        "revision": 1,
        "kate-version": "5.1",
        "functions": ["ordenar", "descerLinhas"],
        "actions": [
            {   "function": "ordenar",
                "name": "Ordena o texto selecionado",
                "category": "Edição",
                "interactive": "false"
            },
            {   "function": "descerLinhas",
                "name": "Desce as linhas",
                "category": "Edição",
                "shortcut": "Ctrl+Shift+Down",
                "interactive": "false"
            }
        ]
    }; // kate-script-header, deve estar no início do arquivo, sem comentários

Cada item será agora explicado em detalhes:

- `author` [opcional]: O nome e a informação de contato do autor.

- `license` [opcional]: Forma curta da licença, como por exemplo, BSD License ou LGPLv2.

- `revision` [obrigatório]: A versão do programa. Este número deverá ser aumentado sempre que o programa for modificado.

- `kate-version` [obrigatório]: A versão mínima do &kappname; necessária.

- `functions` [obrigatório]: Uma lista JSON dos comandos do script.

- `actions` [opcional]: Lista em JSON de objetos JSON que definem as ações que aparecem no menu do aplicativo. São oferecidas informações detalhadas na seção Associar combinações de teclas.

Uma vez que o valor de `functions` é uma lista em JSON, um único script é capaz de conter um número arbitrário de comandos da linha de comando. Cada função está disponível através da linha de comando incorporada do &kappname;.

#### O Código-Fonte do Programa

Todas as funções indicadas no cabeçalho terão de estar implementadas no programa. Por exemplo, o arquivo de programa do exemplo acima tem que implementar as duas funções `ordenar` e `descerLinhas`. Todas as funções têm a seguinte sintaxe:

    // bibliotecas necessárias do katepart js, p.ex., range.js se você usar Range
    function <nome>(arg1, arg2, ...)
    {
        // ... implementação, ver também: API de Programação
    }

Os argumentos na linha de comando são passados à função como `arg1`, `arg2`, etc. Para poder indicar a documentação de cada comando, basta implementar a função '`help`', como demonstrado a seguir:

    function help(cmd)
    {
        if (cmd == "sort") {
            return i18n("Ordena o texto selecionado.");
        } else if (cmd == "...") {
            // ...
        }
    }

Executar `help sort` na linha de comando, irá invocar esta função de ajuda com o argumento `cmd` igual ao comando indicado, como &ie;, `cmd == "sort"`. O &kappname; irá assim apresentar o texto devolvido como documentação ao usuário. Certifique-se de traduzir os textos.

Criar um script para a linha de comando requer o recarregamento dos scripts, de modo a ver se as alterações funcionam apropriadamente. Em vez de reiniciar o aplicativo, basta mudar para a linha de comando e executar o comando `reload-scripts`.

##### Associar combinações de teclas

Para tornar os scripts acessíveis no menu do aplicativo e atribuir teclas de atalho, o script precisa fornecer um cabeçalho do script apropriado. No exemplo acima, ambas as funções `ordenar` e `descerLinhas` aparecem no menu, graças ao seguinte componente no cabeçalho do script:

    var katescript = {
        ...
        "actions": [
            {   "function": "ordenar",
                "name": "Ordena o texto selecionado",
                "icon": "",
                "category": "Edição",
                "interactive": "false"
            },
            {   "function": "descerLinhas",
                "name": "Desce as linhas",
                "icon": "",
                "category": "Edição",
                "shortcut": "Ctrl+Shift+Down",
                "interactive": "false"
            }
        ]
    };

Os campos de uma ação são os seguintes:

- `function` [obrigatório]: A função que deverá aparecer no menu Ferramentas Scripts.

- `name` [obrigatório]: O texto que aparece no menu do script.

- `icon` [opcional]: O ícone aparece após ao texto no menu. Todos os nomes de ícones do &kde; poderão ser usados aqui.

- `category` [opcional]: Se for indicada uma categoria, o programa aparece num submenu.

- `shortcut` [opcional]: A combinação de teclas indicada aqui é o atalho de teclado padrão. Por exemplo: `Ctrl+Alt+T`. Veja a documentação do Qt para mais detalhes.

- `interactive` [opcional]: Se o script precisa de interação por parte do usuário na linha de comando, configure este valor como `true` (verdadeiro).

Se você criar scripts úteis, considere a hipótese de contribuir com eles para o Projeto &kappname;, contactando para isso a lista de correio.

### API de Programação

A API de criação de scripts aqui apresentada está disponível em todos os scripts, &ie;, os scripts de recuo e os comandos do terminal. As classes `Cursor` e o `Range` são fornecidas por arquivos de bibliotecas em `$`XDG_DATA_DIRS`/katepart5/libraries`. Elas serão necessárias, caso queira usar algumas das funções `Document` ou `View` no seu script. Inclua a biblioteca necessária usando:

    // bibliotecas necessárias do katepart js, p.ex., range.js se você usar Range
    require ("range.js");

Para ampliar a API padrão de scripts com suas funções e protótipos próprios, basta criar um arquivo novo na pasta de configuração local do &kde;, em `$`XDG_DATA_HOME`/katepart5/libraries` e incluí-lo no seu script usando:

    require ("myscriptnamehere.js");

Para estender os protótipos existentes, como o `Cursor` ou o `Range`, a forma recomendada é não modificar os arquivos `*.js` globais. Em vez disso, altere o protótipo do `cursor.js` em JavaScript, após o `cursor.js` que é incluído no seu script através do `require`.

#### Cursores e Intervalos

Como o &kappname; é um editor de texto, sempre que possível, toda a API de criação de scripts é baseada em cursores e intervalos. Um cursor é uma simples dupla `(linha, coluna)` que representa uma posição de texto no documento. Um Range (Intervalo) corresponde a uma área de texto coberta desde uma posição inicial do cursor até outra posição de fim. A API é explicada em detalhes nas seções a seguir.

##### O Protótipo do Cursor

    Cursor();

- Construtor. Devolve um Cursor na posição `(0, 0)`.

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

    Cursor(int linha, int coluna);

- Construtor. Devolve um Cursor na posição (linha, coluna).

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

    Cursor(Cursor outro);

- Construtor de cópia. Devolve uma cópia do cursor `outro`.

  Exemplo: `var copia = new Cursor(outro);`

    Cursor Cursor.clone();

- Devolve uma cópia do cursor.

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

    Cursor.setPosition(int linha, int coluna);

- Configura a posição do cursor em `linha` e `coluna`.

  Desde: &kde; 4.11

    bool Cursor.isValid();

- Verifica se o cursor é válido. O cursor é inválido no caso em que a linha e/ou coluna sejam iguais a `-1`.

  Exemplo: `var valido = cursor.isValid();`

    Cursor Cursor.invalid();

- Devolve um novo cursor inválido, localizado em `(-1, -1)`.

  Exemplo: `var cursorInvalido = cursor.invalid();`

    int Cursor.compareTo(Cursor outro);

- Compara este cursor com o cursor `outro`. Devolve

  - `-1`, se este cursor for localizado antes do cursor `outro`,

  - `0`, se ambos os cursores forem iguais e

  - `+1`, se este cursor se localizar após o cursor `outro`.

    bool Cursor.equals(Cursor outro);

- Devolve `true` (verdadeiro), se este o cursor e o `outro` forem iguais, caso contrário devolve `false` (falso).

    String Cursor.toString();

- Devolve o cursor como um texto no formato `Cursor(linha, coluna)`.

##### O Protótipo do Intervalo

    Range();

- Construtor. A invocação de `new Range()` devolve um intervalo Range de (0, 0) - (0, 0).

    Range(Cursor inicio, Cursor fim);

- Construtor. A invocação de `new Range(`início`, `fim`)` devolve o intervalo (`início`, `fim`).

    Range(int linhaInicial, int colunaInicial, int linhaFinal, int colunaFinal);

- Construtor. A invocação de `new Range(`linhaInicial`, `colunaInicial`, `linhaFinal`, `colunaFinal`)` devolve um intervalo Range de (`linhaInicial`, `colunaInicial`) até (`linhaFinal`, `colunaFinal`).

    Range(Range outro);

- Construtor de cópia. Devolve uma cópia do intervalo Range `outro`.

    Range Range.clone();

- Devolve uma cópia do intervalo.

  Exemplo: `var clone = intervalo.clone();`

    bool Range.isEmpty();

- Devolve `true` (verdadeiro), se o cursor de início e de fim forem iguais.

  Exemplo: `var vazio = intervalo.isEmpty();`

  Desde: &kde; 4.11

    bool Range.isValid();

- Devolve `true` (verdadeiro), se tanto o cursor de início como o de fim forem válidos, caso contrário devolve `false` (falso).

  Exemplo: `var valido = intervalo.isValid();`

    Range Range.invalid();

- Devolve o intervalo Range de (-1, -1) até (-1, -1).

    bool Range.contains(Cursor cursor);

- Devolve `true` (verdadeiro) se este intervalo contiver a posição do cursor, caso contrário, devolve `false` (falso).

    bool Range.contains(Range outro);

- Devolve `true` (verdadeiro) se este intervalo contiver o intervalo Range `outro`, caso contrário, devolve `false` (falso).

    bool Range.containsColumn(int coluna);

- Devolve `true` (verdadeiro) se a `coluna` estiver no intervalo semiaberto `[início.coluna, fim.coluna)`, caso contrário, devolve `false` (falso).

    bool Range.containsLine(int linha);

- Devolve `true` (verdadeiro) se a `linha` estiver no intervalo semiaberto `[início.linha, fim.linha)`, caso contrário, devolve `false` (falso).

    bool Range.overlaps(Range outro);

- Devolve `true` (verdadeiro) se este intervalo e o intervalo `outro` compartilharem uma região em comum, caso contrário devolve `false` (falso).

    bool Range.overlapsLine(int linha);

- Devolve `true` (verdadeiro) se a `linha` estiver no intervalo `[início.linha, fim.linha]`, caso contrário devolve `false` (falso).

    bool Range.overlapsColumn(int coluna);

- Devolve `true` (verdadeiro) se a `coluna` estiver no intervalo `[início.coluna, fim.coluna]`, caso contrário devolve `false` (falso).

    bool Range.onSingleLine();

- Devolve `true` (verdadeiro) se o intervalo inicia e termina na mesma linha, &ie;, se `Range.start.line == Range.end.line`.

  Desde: &kde; 4.9

    bool Range.equals(Range outro);

- Devolve `true` (verdadeiro) se este intervalo e o intervalo `outro` forem iguais, caso contrário devolve `false` (falso).

    String Range.toString();

- Devolve o intervalo como uma string no formato `Range(Cursor(linha, coluna), Cursor(linha, coluna))`.

#### Funções globais

Esta seção apresenta todas as funções globais.

##### Arquivos de leitura e inclusão

    String read(String arquivo);

- Irá procurar pelo `arquivo` indicado em relação à pasta `katepart/script/files` e irá devolver o seu conteúdo como texto.

    void require(String Arquivo);

- Irá procurar pelo `arquivo` indicado em relação à pasta `katepart/script/libraries` e avaliá-lo. O `require` está protegido internamente contra inclusões múltiplas do mesmo `arquivos`.

  Desde: &kde; 4.10

##### Depuração

    void debug(String texto);

- Imprime o `texto` no `stdout`, mais precisamente no console que lança a aplicação.

##### Tradução

Para um suporte regional completo, existem diversas funções para traduzir os textos nos programas, nomeadamente o `i18n`, o `i18nc`, o `i18np` e o `i18ncp`. Estas funções comportam-se exatamente como as funções de tradução do &kde;.

As funções de tradução convertem os textos indicados ao sistema de traduções do &kde; para o idioma usado no aplicativo. Os textos nos scripts que são desenvolvidos no âmbito do código oficial do &kappname; são automaticamente extraídos e preparados para tradução. Em outras palavras, como desenvolvedor do &kappname;, você não precisa que se preocupar com a extração e tradução. Contudo, a tradução só funciona dentro da infraestrutura do &kde;, &ie;, novos textos em scripts de terceiros, desenvolvidos fora do &kde;, não são traduzidos. Dessa forma, considere contribuir com seus scripts para o &kate;, para que seja possível obter uma tradução adequada.

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

- Traduz o `texto` na língua usada pela aplicação. Os argumentos `arg1`, ..., são opcionais e usados para substituir os itens `%1`, `%2`, etc.

    void i18nc(String contexto, String texto, arg1, ...);

- Traduz o `texto` na língua usada pela aplicação. Além disso, o texto do `contexto` fica visível aos tradutores para que possam dar uma tradução mais adequada. Os argumentos `arg1`, ..., são opcionais e são usados para substituir os itens de substituição `%1`, `%2`, etc.

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

- Traduz tanto o texto `singular` como o `plural` para a língua usada pela aplicação, dependendo do `número` indicado. Os argumentos `arg1`, ..., são opcionais e usados para substituir os itens de substituição `%1`, `%2`, etc.

    void i18ncp(String contexto, String singular, String plural, intnúmero, arg1, ...);

- Traduz tanto o texto `singular` como o `plural` para a língua usada pela aplicação, dependendo do `número` indicado. Adicionalmente, o texto do `contexto` é visível para as tradutores, para que possam fornecer uma tradução mais adequada. Os argumentos `arg1`, ..., são opcionais e são usados para substituir os itens `%1`, `%2`, etc.

#### A API do View

Sempre que um programa está sendo executado, existe uma variável global `view` que representa a área de edição ativa no momento. Segue-se uma lista com todas as funções disponíveis para o View.

    Cursor view.cursorPosition()

- Devolve a posição atual do cursor na janela.

    void view.setCursorPosition(int linha, int coluna);
    void view.setCursorPosition(Cursor cursor);

- Altera a posição atual do cursor para uma (linha, coluna) qualquer ou para o cursor indicado.

    Cursor view.virtualCursorPosition();

- Devolve a posição virtual do cursor com cada tabulação a corresponder ao número indicado de espaços, dependente da largura de tabulação atual.

    void view.setVirtualCursorPosition(int linha, int coluna);
    void view.setVirtualCursorPosition(Cursor cursor);

- Altera a posição atual do cursor virtual para uma (linha, coluna) qualquer ou para o cursor indicado.

    String view.selectedText();

- Devolve o texto selecionado. Se não tiver nenhum texto selecionado, o texto devolvido vem vazio.

    bool view.hasSelection();

- Devolve `true` (verdadeiro) se a janela contiver algum texto selecionado, caso contrário, devolve `false` (falso).

    Range view.selection();

- Devolve o intervalo de texto selecionado. O intervalo devolvido é inválido, caso não esteja selecionado nenhum texto.

    void view.setSelection(Range intervalo);

- Altera o texto selecionado para o intervalo indicado.

    void view.removeSelectedText();

- Remove o texto selecionado. Se a janela não tiver nenhuma seleção feita, isto não faz nada.

    void view.selectAll();

- Seleciona todo o texto no documento.

    void view.clearSelection();

- Limpa a seleção de texto atual, sem remover o texto.

#### API do Document

Sempre que um script estiver em execução, existe um objeto global (variável) `document` representando o documento ativo atual. A seguir é apresentada uma lista de todas as funções disponíveis para o Document.

    String document.fileName();

- Devolve o nome do arquivo do documento, ou então um texto vazio para as janelas de texto ainda por salvar.

    String document.url();

- Devolve o URL completo do documento, ou então um texto vazio para as janelas de texto ainda por salvar.

    String document.mimeType();

- Devolve o tipo MIME do documento, ou então o tipo `application/octet-stream` se não for encontrado qualquer tipo MIME apropriado.

    String document.encoding();

- Devolve a codificação usada atualmente para salvar o arquivo.

    String document.highlightingMode();

- Devolve o modo de realce global usado para todo o documento.

    String document.highlightingModeAt(Cursor pos);

- Devolve o modo de realce usado na posição do cursor indicada do documento.

    Array document.embeddedHighlightingModes();

- Devolve uma lista com os modos de realce incorporados neste documento.

    bool document.isModified();

- Devolve `true` (verdadeiro) se o documento tiver alguma alteração por salvar, caso contrário devolve `false`.

    String document.text();

- Devolve o conteúdo inteiro do documento numa única sequência de texto. As mudanças de linha estão marcadas com o caractere de mudança de linha `\n`.

    String document.text(int daLinha, int daColuna, int paraLinha, int paraColuna);
    String document.text(Cursor de, Cursor para);
    String document.text(Range intervalo);

- Devolve o texto no intervalo indicado. Recomenda-se que use a versão baseada nos cursores e nos intervalos, de modo a ter uma melhor visibilidade do código-fonte.

    String document.line(int linha);

- Devolve a linha de texto indicada como uma sequência de texto. O texto devolvido fica em branco, caso a linha pedida esteja fora do intervalo.

    String document.wordAt(int linha, int coluna);
    String document.wordAt(Cursor cursor);

- Devolve a palavra na posição do cursor indicada.

    Range document.wordRangeAt(int linha, int coluna);
    Range document.wordRangeAt(Cursor cursor);

- Devolve o intervalo da palavra na posição indicada do cursor. O intervalo devolvido é inválido (ver Range.isValid()), caso a posição do texto esteja após o fim de uma linha. Se não existir nenhuma palavra no cursor indicado, é devolvido um intervalo vazio.

  Desde: &kde; 4.9

    String document.charAt(int linha, int coluna);
    String document.charAt(Cursor cursor);

- Devolve o caractere na posição do cursor indicada.

    String document.firstChar(int linha);

- Devolve o primeiro caractere na `linha` que não seja um espaço em branco. O primeiro caractere encontra-se na coluna 0. Se a linha estiver em branco ou conter apenas espaços, a string devolvida será vazia.

    String document.lastChar(int linha);

- Devolve o último caractere da `linha` indicada que não seja um espaço em branco. O primeiro caractere encontra-se na coluna 0. Se a linha estiver em branco ou só tiver espaços em branco, o texto devolvido vem vazio.

    bool document.isSpace(int linha, int coluna);
    bool document.isSpace(Cursor cursor);

- Devolve `true` (verdadeiro), se o caractere na posição indicada do cursor for um espaço em branco, caso contrário, devolve `false` (falso).

    bool document.matchesAt(int linha, int coluna, String texto);
    bool document.matchesAt(Cursor cursor, String texto);

- Devolve `true` (verdadeiro) se o `texto` indicado corresponder à posição indicada do cursor, caso contrário, devolve `false` (falso).

    bool document.startsWith(int linha, String texto, bool ignorarEspacos);

- Devolve `true` (verdadeiro) se a linha começar por `texto`, caso contrário, devolve `false` (falso). O argumento `ignorarEspacos` controla se os espaços envolventes são ignorados ou não.

    bool document.endsWith(int linha, String texto, bool ignorarEspacos);

- Devolve `true` (verdadeiro), caso a linha termine em `texto`, caso contrário devolve `false` (falso). O argumento `ignorarEspacos` controla se os espaços envolventes são ignorados.

    bool document.setText(String texto);

- Altera o texto do documento por inteiro.

    bool document.clear();

- Limpa o texto no documento por inteiro.

    bool document.truncate(int linha, int coluna);
    bool document.truncate(Cursor cursor);

- Trunca a linha indicada, na coluna ou posição do cursor indicadas. Devolve `true` (verdadeiro) em caso de sucesso ou `false` (falso) se a linha não estiver dentro do intervalo do documento.

    bool document.insertText(int linha, int coluna, String texto);
    bool document.insertText(Cursor cursor, String texto);

- Insere o `texto` na posição do cursor indicada. Devolve `true`, em caso de sucesso, ou `false` (falso), se o documento estiver apenas para leitura.

    bool document.removeText(int daLinha, int daColuna, int paraLinha, int paraColuna);
    bool document.removeText(Cursor de, Cursor para);
    bool document.removeText(Range intervalo);

- Remove o texto no intervalo indicado. Devolve `true` (verdadeiro), em caso de sucesso, ou `false` (falso), se o documento estiver no modo apenas para leitura.

    bool document.insertLine(int linha, String texto);

- Insere o texto na linha indicada. Devolve `true` (verdadeiro), em caso de sucesso, ou `false` (falso), caso o documento esteja apenas para leitura ou se a linha não estiver no intervalo do documento.

    bool document.removeLine(int linha);

- Remove a linha de texto indicada. Devolve `true` (verdadeiro), em caso de sucesso, ou `false` (falso), caso o documento esteja no modo apenas para leitura ou se a linha não estiver no intervalo do documento.

    bool document.wrapLine(int linha, int coluna);
    bool document.wrapLine(Cursor cursor);

- Reparte a linha na posição indicada pelo cursor. Devolve `true` (verdadeiro) em caso de sucesso ou `false` (falso) se, ⪚, a linha < 0.

  Desde: &kde; 4.9

    void document.joinLines(int linhaInicial, int linhaFinal);

- Junta as linhas de `linhaInicial` até `linhaFinal`. Duas linhas de texto sucessivas estão sempre separadas por um espaço em branco.

    int document.lines();

- Devolve o número de linhas do documento.

    bool document.isLineModified(int linha);

- Devolve `true` (verdadeiro), se a `linha` contém dados que não foram salvos.

  Desde: &kde; 5.0

    bool document.isLineSaved(int linha);

- Devolve `true` (verdadeiro), se a `linha` foi alterada, mas o documento foi salvo. Assim, a linha não contém dados não salvos.

  Desde: &kde; 5.0

    bool document.isLineTouched(int linha);

- Devolve `true` (verdadeiro), se a `linha` contém dados que não foram salvos ou foi anteriormente alterado.

  Desde: &kde; 5.0

    bool document.findTouchedLine(int linhaInicial, bool abaixo);

- Procura pela próxima linha tocada que comece na `linha`. A pesquisa é efetuada tanto para cima como para baixo, dependendo da direção de pesquisa indicada em `baixo`.

  Desde: &kde; 5.0

    int document.length();

- Devolve o número de caracteres do documento.

    int document.lineLength(int linha);

- Devolve o comprimento da `linha`.

    void document.editBegin();

- Inicia um grupo de edição para agrupar operações a desfazer/refazer. Certifique-se de invocar sempre o `editEnd()` tantas vezes quanto invoca o `editBegin()`. A invocação do `editBegin()` usa um contador de referências interno, &ie;, esta chamada pode ser encadeada.

    void document.editEnd();

- Termina um grupo de edição. A última invocação do `editEnd()` (&ie;, a correspondente à primeira chamada do `editBegin()`) termina o passo de edição.

    int document.firstColumn(int linha);

- Devolve a primeira coluna não em branco para a `linha` indicada. Se só existirem espaços em branco na linha, o valor devolvido é `-1`.

    int document.lastColumn(int linha);

- Devolve a última coluna que não esteja em branco para a `linha` indicada. Se só existirem espaços em branco na linha, o valor devolvido é `-1`.

    int document.prevNonSpaceColumn(int linha, int coluna);
    int document.prevNonSpaceColumn(Cursor cursor);

- Devolve a coluna com caracteres não-brancos que começa na posição de cursor indicada e pesquisa para trás.

    int document.nextNonSpaceColumn(int linha, int coluna);
    int document.nextNonSpaceColumn(Cursor cursor);

- Devolve a coluna com caracteres não-brancos que começa na posição de cursor indicada e pesquisa para a frente.

    int document.prevNonEmptyLine(int linha);

- Devolve a primeira linha não-vazia que contém caracteres não-nulos, pesquisando depois para trás.

    int document.nextNonEmptyLine(int linha);

- Devolve a primeira linha não-vazia que contém caracteres não-nulos, pesquisando depois para a frente.

    bool document.isInWord(String caractere, int atributo);

- Devolve `true` (verdadeiro), caso o `caractere` e `atributo` indicados possam fazer parte de uma palavra, caso contrário devolve `false` (falso).

    bool document.canBreakAt(String caractere, int atributo);

- Devolve `true` (verdadeiro) se o `caractere` indicado com o `atributo` indicado for adequado para mudar de linha, caso contrário devolve `false`.

    bool document.canComment(int atributoInicial, int atributoFinal);

- Devolve `true` (falso), caso um intervalo que começa e termina com os atributos indicados possa ser comentado; caso contrário, devolve `false` (falso).

    String document.commentMarker(int atributo);

- Devolve o marcador de comentários, usado em linhas únicas, para um determinado `atributo`.

    String document.commentStart(int atributo);

- Devolve o marcador de início de comentários, usado em linhas múltiplas, para um determinado `atributo`.

    String document.commentEnd(int atributo);

- Devolve o marcador de fim de comentários, usado em linhas múltiplas, para um determinado `atributo`.

    Range document.documentRange();

- Devolve um intervalo que engloba todo o documento.

    Cursor documentEnd();

- Devolve um cursor posicionado na última coluna da última linha do documento.

    bool isValidTextPosition(int linha, int coluna);
    bool isValidTextPosition(Cursor cursor);

- Devolve `true` (verdadeiro), se a posição atual do cursor estiver em uma posição de texto válida. Uma posição de texto é válida apenas se estiver localizada no início, no meio ou no fim de uma linha válida. Além disso, uma posição de texto é inválida se estiver localizada em um substituto Unicode.

  Desde: &kde; 5.0

    int document.attribute(int linha, int coluna);
    int document.attribute(Cursor cursor);

- Devolve o atributo na posição do cursor indicada.

    bool document.isAttribute(int linha, int coluna, int atributo);
    bool document.isAttribute(Cursor cursor, int atributo);

- Devolve `true` (verdadeiro), se o atributo na posição do cursor indicada for igual a `atributo`, caso contrário devolve `false` (falso).

    String document.attributeName(int linha, int coluna);
    String document.attributeName(Cursor cursor);

- Devolve o nome do atributo como um texto legível. Isto é igual ao nome `itemData` dos arquivos de realce de sintaxe.

    bool document.isAttributeName(int linha, int coluna, String nome);
    bool document.isAttributeName(Cursor cursor, String nome);

- Devolve `true` (verdadeiro), se o nome do atributo, numa dada posição do cursor, corresponder ao `nome` indicado, caso contrário devolve `false` (falso).

    String document.variable(String chave);

- Devolve o valor da variável do documento identificada pela `chave`. Se a variável do documento não existir, o valor devolvido é um texto em branco.

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

- Define o valor da variável do documento solicitada pela `chave`.

  Veja também: Variáveis de documento do Kate

  Desde: &kde; 4.8

    int document.firstVirtualColumn(int linha);

- Devolve a coluna virtual do primeiro caractere não-nulo na linha indicada, ou então `-1` se a linha estiver em branco ou só tiver caracteres de espaços em branco.

    int document.lastVirtualColumn(int linha);

- Devolve a coluna virtual do último caractere não-nulo na linha indicada, ou então `-1` se a linha estiver em branco ou só tiver caracteres de espaços em branco.

    int document.toVirtualColumn(int linha, int coluna);
    int document.toVirtualColumn(Cursor cursor);
    Cursor document.toVirtualCursor(Cursor cursor);

- Converte a posição do cursor real para uma posição virtual, retornando um int ou um objeto Cursor.

    int document.fromVirtualColumn(int linha, int colunaVirtual);
    int document.fromVirtualColumn(Cursor cursorVirtual);
    Cursor document.fromVirtualCursor(Cursor cursorVirtual);

- Converte a posição virtual do cursor para uma posição do cursor real, retornando um int ou um objeto Cursor.

    Cursor document.anchor(int linha, int coluna, Char caractere);
    Cursor document.anchor(Cursor cursor, Char caractere);

- Pesquisa para trás pelo caractere indicado, começando na posição do cursor indicada. Por exemplo, se for passado o '(', como caractere, esta função irá devolver a posição do '(' de abertura. Isto implica uma contagem das referências, &ie;, os outros '(...)' são ignorados.

    Cursor document.rfind(int linha, int coluna, String texto, int atributo = -1);
    Cursor document.rfind(Cursor cursor, String texto, int atributo = -1);

- Pesquisa para trás pelo texto indicado, com o `atributo` apropriado. O argumento `atributo` é ignorado se for igual a `-1`. O cursor devolvido é inválido, caso o texto não tenha sido encontrado.

    int document.defStyleNum(int linha, int coluna);
    int document.defStyleNum(Cursor cursor);

- Devolve o estilo padrão que é usado na posição do cursor indicada.

    bool document.isCode(int linha, int coluna);
    bool document.isCode(Cursor cursor);

- Devolve `true` (verdadeiro) se o atributo na posição do cursor indicada não for igual a todos os seguintes estilos: `dsComment`, `dsString`, `dsRegionMarker`, `dsChar`, `dsOthers`.

    bool document.isComment(int linha, int coluna);
    bool document.isComment(Cursor cursor);

- Devolve `true` se o atributo do caractere na posição do cursor for `dsComment`, caso contrário, devolve `false`.

    bool document.isString(int linha, int coluna);
    bool document.isString(Cursor cursor);

- Devolve `true` (verdadeiro) se o atributo do caractere na posição do cursor for `dsString`, caso contrário, devolve `false` (falso).

    bool document.isRegionMarker(int linha, int coluna);
    bool document.isRegionMarker(Cursor cursor);

- Devolve `true` (verdadeiro) se o atributo do caractere na posição do cursor for `dsRegionMarker`, caso contrário, devolve `false` (falso).

    bool document.isChar(int linha, int coluna);
    bool document.isChar(Cursor cursor);

- Devolve `true` (verdadeiro) se o atributo do caractere na posição do cursor for `dsChar`, caso contrário, devolve `false` (falso).

    bool document.isOthers(int linha, int coluna);
    bool document.isOthers(Cursor cursor);

- Devolve `true` (verdadeiro) se o atributo do caractere na posição do cursor for `dsOthers`, caso contrário, devolve `false` (falso).