# Melhorar o &katepart;

## Introdução

Como em qualquer editor de texto avançado, o &katepart; oferece uma grande diversidade de formas para ampliar a sua funcionalidade. Poderá criar programa simples para adicionar funcionalidades com o JavaScript. Finalmente, assim que tiver melhorado o &kate;, está à vontade para se juntar a nós e partilhar as suas melhorias com o mundo!

## Trabalhar com o Realce de Sintaxe

### Introdução

O Realce de Sintaxe é o que faz o editor mostrar automaticamente o texto em diferentes estilos/cores, dependendo da função do texto em relação ao propósito do ficheiro. No código-fonte de um programa, por exemplo, as instruções de controlo podem ser representadas a negrito, enquanto os tipos de dados e os comentários têm cores diferentes do resto do texto. Isto aumenta em larga medida a legibilidade do texto, e por isso ajuda o autor a ser mais eficiente e produtivo.

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

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

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

A mesma função de 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 normal oferece definições para um conjunto vasto de linguagens de programação, de manipulação e de 'scripting', bem como para outros formatos de texto. Para além disso, pode criar as suas próprias definições em ficheiros &XML; simples.

O &kappname; irá detectar automaticamente as regras de sintaxe correctas quando abrir um ficheiro, baseando-se no tipo &MIME; do ficheiro, pela sua extensão, ou se não tiver nenhuma, pelo seu conteúdo. Se a escolha for errada, pode definir manualmente a sintaxe a usar no menu Documentos Realce.

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

O realce de sintaxe existe para melhorar a legibilidade do texto correcto, mas não pode esperar que ela valide o seu texto. A marcação do texto para a sintaxe é complicada, dependendo do formato que está a usar e, em muitos dos casos, os autores das regras de sintaxe sentir-se-ão orgulhosos se 98% do texto for correctamente apresentado, ainda que na maior parte das vezes precisa de um estilo raro para ver os 2% incorrectos.

Pode obter as definições de sintaxe adicionais ou actualizadas na página Web do &kappname; se carregar no botão Obter Ficheiros de Realce... na página de Modos & Tipos de Ficheiros da Janela de Configuração.

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

Esta secção irá discutir o realce de sintaxe do &kappname; com mais detalhe. É para si, se quiser saber acerca dele ou se quiser criar ou alterar as definições de sintaxe.

#### Como Funciona

Sempre que o utilizador abrir um ficheiro, uma das primeiras coisas que o editor do &kappname; faz é detectar qual a definição de sintaxe a usar para o ficheiro. Enquanto vai lendo o texto do ficheiro, e enquanto você vai escrevendo nele, o sistema de realce de sintaxe irá analisar o texto usando as regras definidas pela definição da sintaxe e marcá-la onde os diferentes contextos e estilos começam e acabam.

Quando escrever no documento, o novo texto é analisado e marcado na altura, por isso, se apagar um carácter que está marcado como o início ou o fim de um contexto, o estilo do texto circundante muda de acordo com esse facto.

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

- As regras para detectar o papel do texto, organizado em blocos de contextos

- Listas de palavras-chave

- Definições de Itens de Estilo

Ao analisar o texto, as regras de detecção são avaliadas na ordem em que são definidas, e se o início do texto actual corresponder a uma regra, o contexto relacionado será usado. O ponto inicial do texto é movido para o ponto final a partir do qual essa regra correspondeu, dando-se início a mais um ciclo das regras, o qual dá início no conjunto de contextos definido pela regra correspondente.

#### Regras

As regras de detecção são o 'coração' do sistema de detecção de sintaxe. Uma regra é uma cadeia de caracteres, um carácter 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 usar para a parte correspondente do texto. Pode mudar do contexto actual do sistema para um outro contexto explícito ou para o contexto anterior usado pelo texto.

As regras são organizadas em grupos de contextos. Um grupo de contextos é usado para os conceitos principais do formato como, por exemplo, as cadeias de caracteres entre aspas ou os blocos de comentários no código-fonte do programa. Isto garante que o sistema de realce de sintaxe não precisa de circular por todas as regras quando não é necessário, e que algumas sequências de caracteres no texto podem ser tratadas de modo diferente, dependendo do contexto actual.

Os contextos poderão ser gerados dinamicamente, para permitir a utilização de dados específicos das instâncias nas regras.

#### Estilos de Contexto e Palavras-Chave

Em algumas linguagens de programação, os números inteiros são tratados de forma diferente dos números de vírgula flutuante pelo compilador (o programa que converte o código-fonte num executável binário), assim como podem existir caracteres com um significado especial dentro de uma cadeia de caracteres entre aspas. Em ambos os casos, faz sentido mostrá-los de forma diferente dos seus vizinhos, de modo a que sejam fáceis de identificar enquanto o utilizador lê o texto. Por isso, mesmo que não representem contextos especiais, podem ser vistos como tal pelo sistema de realce de sintaxe, de modo que possam ser marcados para ser desenhados de diferente forma.

Uma definição de sintaxe pode conter tantos estilos quantos necessários para cobrir os conceitos do formato no qual é usado.

Em vários formatos, existem listas de palavras que representam um conceito específico. Como exemplo nas linguagens de programação, as instruções de controlo são um conceito, os tipos de dados são outro e as funções intrínsecas à linguagem são um terceiro conceito. O Sistema de Realce de Sintaxe do &kappname; pode usar essas listas para detectar e marcar as palavras no texto de modo a realçar os conceitos dos formatos de texto.

#### Estilos por Omissão

Se abrir um ficheiro de código em C++, um ficheiro de &Java; e um documento em HTML no &kappname;, irá ver que, ainda que os formatos sejam diferentes e, por isso, sejam seleccionadas palavras diferentes para um tratamento especial, as cores usadas são as mesmas. Isto deve-se ao facto do &kappname; ter uma lista predefinida de Estilos Predefinidos, os quais são empregues pelas definições de sintaxe individuais.

Isto facilita o reconhecimento de conceitos similares nos diferentes formatos de texto. Por exemplo, os comentários estão presentes em quase todas as linguagens de programação, 'scripting' ou de marcação, e quando são representados com o mesmo estilo em todas as linguagens, você não terá de parar e pensar para os identificar no texto.

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

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

#### Introdução

O &kappname; usa a plataforma de realce de sintaxe das &kde-frameworks;. Os ficheiros XML predefinidos do realce de sintaxe que vêm com o &kappname; são compilados na biblioteca de Realce de Sintaxe por omissão.

Esta secção é uma introdução ao formato &XML; da Definição de Realce. Irá descrever as componentes principais, bem como o seu significado e utilização, indo em mais detalhes com as regras de detecção.

A definição formal, também conhecida como XSD, poderá ser encontrada no repositório de Realces de Sintaxe, no ficheiro `language.xsd`

Os ficheiros `.xml` de definições personalizadas de realce localizam-se em `org.kde.syntax-highlighting/syntax/`, na sua pasta de utilizador, podendo consultar o valor com ``qtpaths``--paths GenericDataLocation``, que normalmente corresponde a ``$HOME`/.local`

No &Windows;, estes ficheiros localizam-se em `%USERPROFILE%/AppData/Local/org.kde.syntax-highlighting/syntax`. O `%USERPROFILE%` normalmente corresponde a `C:\\Users\\`utilizador``.

#### Componentes principais das Definições de Realce do &kappname;

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

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

A raiz do ficheiro 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 menus e nas janelas respectivas.

  O `section` indica a categoria.

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

  O `version` define a versão actual do ficheiro de definições como um número inteiro. Sempre que mudar um ficheiro de definições de realce, certifique-se que incrementa este número.

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

  Atributos opcionais:

  O `mimetype` associa os ficheiros com base no Tipo &MIME;.

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

  O `priority` é necessário se outro ficheiro 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, entre outras.

  O `style` contém a linguagem oferecida e é usado pelos sistemas de indentação para o atributo `required-syntax-style`.

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

  Como tal, a próxima linha parece-se 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. Poderá adicionar tantas listas quanto desejar.

  O elemento `contexts` contém todos os contextos. O primeiro contexto é, por omissã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 letra 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 secção opcional `general`. Poderá conter informações acerca das palavras-chave, expansão/recolhimento de código, comentários e indentação.

- A secção `comment` define com que texto é introduzido um comentário para uma única linha. Poderá também definir comentários multi-linha, usando o multiLine com o atributo adicional end. Isto aplica-se se o utilizador carregar no atalho correspondente para comentar/descomentar.

  A secçã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 Secçõ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 a indentação.

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` o nome do contexto. As regras irão usar este 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 vazia. Por omissão: #stay.

  O `fallthrough` define se o sistema de realce salta para o contexto indicado em 'fallthroughContext' se não corresponder nenhuma regra. Por omissã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. Por omissão: false.

O elemento `itemData` está no grupo `itemDatas`. Define o estilo e as cores do tipo de letra. Como tal, é possível definir os seus próprios estilos e cores, contudo recomenda-se que use os estilos predefinidos, para que o utilizador veja sempre as mesmas cores que são usadas nas várias linguagens. Todavia, existem casos em que não existe outra forma e, como tal, é necessário mudar os atributos de cores e tipos de letra. 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 predefinido a usar. Os estilos predefinidos disponíveis são explicados mais tarde em detalhe.

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

  O `selColor` define a cor da selecçã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), irá colocar o texto traçado.

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

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 actuar 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 predefinidos 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 seleccionado todo o texto do comentário multi-linhas. O cursor só necessita de 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 na indentação, como acontece na linguagem de programação Python. Normalmente não terá de definir isto, dado que é por omissão false.

O elemento `indentation`, no grupo `general`, define qual o sistema de indentação a usar; contudo, recomenda-se que omita este elemento, dado que o sistema de indentação será normalmente definido a partir de um Tipo de Ficheiro ou através da adição da linha de modo no ficheiro de texto. Se indicar um sistema de indentação, todavia, irá obrigar o utilizador a usar um sistema de indentação específico, o que poderá não ser do agrado dele. Os atributos disponíveis são:

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

#### Estilos Predefinidos Disponíveis

Os estilos por omissão já foram explicados, em resumo: Os estilos predefinidos são os estilos de cores e tipos de letra predefinidos.

Estilos predefinidos gerais:

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

  `dsKeyword`, para as palavras-chave incorporadas.

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

  `dsVariable`, se aplicável: nomes das variáveis (p.ex. $umaVariavel em PHP/Perl).

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

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

  `dsBuiltIn`, usado nas funções, classes e objectos predefinidos.

  `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 predefinidos relacionados com os textos:

- `dsChar`, usado para caracteres únicos, como o 'x'.

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

  `dsString`, para os textos do tipo "olá mundo".

  `dsVerbatimString`, textos 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`, para a importação ou inclusão de módulos.

Estilos predefinidos relacionados com números:

- `dsDataType`, para os tipos de dados predefinidos, como o 'int', 'void', 'u64'.

  `dsDecVal`, para os valores decimais.

  `dsBaseN`, para os valores com uma base diferente de 10.

  `dsFloat`, para os valores de vírgula flutuante.

  `dsConstant`, para as constantes predefinidas e definidas pelo utilizador, como o PI.

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

- `dsComment`, para os comentários.

  `dsDocumentation`, para os /** Comentários de documentação */ ou os """Comentários 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 "xpto" no @param xpto.

  `dsRegionMarker`, para os marcadores de regiões, como o //BEGIN, //END dos comentários.

Outros estilos predefinidos:

- `dsInformation`, notas e dicas do tipo @note no Doxygen.

  `dsWarning`, para os avisos do tipo @warning no Doxygen.

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

  `dsError`, para o realce dos erros e sintaxes inválidas.

  `dsOthers`, quando nada mais se aplica.

### Regras de Detecção do Realce

Esta secção descreve as regras de detecção da 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 actual será alterado.

Uma regra parece-se com o seguinte:

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

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

O context pode ser identificado por:

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

- Uma ordem que indica ao motor para permanecer no contexto actual (`#stay`) ou para voltar a um contexto anterior usado no texto (`#pop`).

  Para recuar mais vezes, a palavra '#pop' pode ser repetida: `#pop#pop#pop`

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

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 será algo do género:

    <NomeRegra (atributos)>
      <NomeRegraFilho (atributos) />
      ...
    </NomeRegra>

Os atributos específicos da regra variam e estão descritos nas seguintes secções.

### Atributos comuns

Todas as regras têm 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.

- atributo: Um atributo mapeia-se num 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. Por omissão: não definido.

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

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

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

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

### Regras dinâmicas

Algumas regras permitem o atributo opcional `dynamic`, do tipo booleano, cujo valor por omissã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 actua, 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 carácter 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 Detalhe

DetectChar

- Detecta um único carácter específico. É usado vulgarmente para encontrar, por exemplo, o fim das cadeias de caracteres entre aspas.

      <DetectChar char="(carácter)" (atributos comuns) (dinâmico) />

  O atributo `char` define o carácter a encontrar.

Detect2Chars

- Detecta dois caracteres específicos numa ordem definida.

      <Detect2Chars char="(carácter)" char1="(carácter)" (atributos comuns) (dinâmico) />

  O atributo `char` define o primeiro carácter a encontrar, enquanto `char1` define o segundo.

AnyChar

- Detecta um carácter de um conjunto de caracteres especificados.

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

  O atributo `String` define o conjunto de caracteres.

StringDetect

- Detecta um texto exacto.

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

  O atributo `String` define a sequência a encontrar. O atributo `insensitive` é por omissã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 exacto, 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 omissã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

- Corresponde a 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 omissão, `false` e é passado ao motor de expressões regulares.

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

  Como as regras se aplicam ao início do texto actual, uma expressão regular que comece por um acento circunflexo (`^`) indica que a regra só deve ser verificada se for no início de uma linha.

  Veja as Expressões Regulares para mais informações sobre elas.

keyword

- Detecta uma palavra-chave a partir de uma lista específica.

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

  O atributo `String` identifica a lista de palavras-chave pelo seu nome. Deve existir uma lista com esse nome.

  O sistema de realce processa as regras das palavras-chave de forma muito optimizada. Isto torna-a uma necessidade absoluta em que quaisquer palavras-chave a corresponder sejam envolvidas por separadores definidos, quer implícitos (os separadores predefinidos) quer explícitos com a propriedade additionalDeliminator da marca keywords.

  Se uma palavra-chave a corresponder tiver um carácter separador, este carácter respectivo deverá ser adicionado à propriedade weakDeliminator da marca keywords. Este carácter irá então perder a sua capacidade 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 facto, todas as regras são permitidas como regras-filhas, contudo, o DTD só permite a regra-filha `StringDetect`.

  O exemplo seguinte faz correspondência com os números inteiros, seguidos do carácter 'L'.

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

Real

- Detecta um número de vírgula 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 tem atributos específicos.

HlCHex

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

      <HlCHex (atributos comuns) />

  Esta regra não tem atributos específicos.

HlCStringChar

- Detecta um carácter 'escapado'.

      <HlCStringChar (atributos comuns) />

  Esta regra não tem 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 a seguir a uma barra invertida (`\`): `abefnrtv"'?\`. Para 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 carácter do C.

      <HlCChar (atributos comuns) />

  Esta regra não tem atributos específicos.

  Corresponde aos caracteres em C colocados dentro de plicas (Exemplo: `'c'`). Como tal, dentro das plicas poderá estar um único carácter ou um carácter de escape. Veja o 'HlCStringChar' para ver as sequências de caracteres de escape correspondentes.

RangeDetect

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

      <RangeDetect char="(carácter)"  char1="(carácter)" (atributos comuns) />

  O `char` define o carácter de início e o `char1` o carácter que termina o intervalo.

  Útil para detectar, por exemplo, pequenas cadeias de caracteres entre aspas e semelhantes, mas repare que, dado 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 do que uma linha.

LineContinue

- Corresponde um carácter indicado ao fim de uma linha.

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

  `char` carácter opcional a corresponder; por omissão é a barra invertida (`'\'`). Novo desde o KDE 4.13.

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

IncludeRules

- Inclui as regras de outro contexto ou linguagem/ficheiro.

      <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 actual, como por exemplo:

      <IncludeRules context="outroContexto" />

  Se o texto tiver um `##`, o sistema de realce irá procurar por um contexto de outra definição de linguagens 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 tem 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 indentadas. 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 tem 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 deva verificar com cuidado a regra que escolhe, dependendo da situação, as expressões regulares são muito poderosas, só que são lentas em comparação com as outras regras. Como tal, poderá considerar as seguintes dicas.

- Se 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 carácter `'#'` se for o primeiro carácter da linha. Uma solução baseada em expressões regulares seria semelhante à seguinte:

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

  Poderá obter o mesmo se usar:

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

  Se quiser corresponder à expressão regular `'^#'`, poderá usar à mesma o `DetectChar` com o atributo `column="0"`. O atributo `column` conta com base no número de caracteres; como tal, uma tabulação conta à mesma como se fosse apenas um carácter.

- 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 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 predefinidos sempre que puder. Desta forma, o utilizador irá encontrar um ambiente familiar.

- Procure noutros ficheiros XML para ver como as outras pessoas implementam as regras mais complicadas.

- Poderá validar todos os ficheiros XML se usar o comando `validatehl.sh language.xsd minhaSintaxe.xml`. Os ficheiros `validatehl.sh` e `language.xsd` estão disponíveis no repositório de Realces de Sintaxe.

- Se repetir algumas expressões regulares complexas com frequência, 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, poderá usar o &referencia; em vez da expressão regular.

## Programar em JavaScript

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

### Programas de Indentação

Programas de indentação - também conhecidos por indentadores - formatam automaticamente o código-fonte enquanto escreve o texto. Por exemplo, depois de carregar na tecla Return, o nível de indentação costuma aumentar.

As seguintes secções descrevem, passo-a-passo, como criar o esqueleto de um módulo de indentação simples. Como primeiro passo, crie um novo ficheiro `*.js`, chamado ⪚ `javascript.js` na pasta pessoal local `$`XDG_DATA_HOME`share/apps/katepart5/script/indentation`. Normalmente, a variável de ambiente `XDG_DATA_HOME` expande-se normalmente para `~/.local` ou `~/.local/share`.

No &Windows;, estes ficheiros localizam-se em `%USER%\AppData\Local\katepart5\indentation`. O `%USERPROFILE%` normalmente corresponde a `C:\\Users\\`utilizador``.

#### O Cabeçalho do Programa de Indentação

O cabeçalho do ficheiro `javascript.js` está incorporado como JSON no início do documento, da seguinte forma:

    var katescript = {
        "name": "JavaScript",
        "author": "Nome de Exemplo <nome.exemplo@endereco.org>",
        "license": "Licença BSD",
        "revision": 1,
        "kate-version": "5.1",
        "required-syntax-style": "javascript",
        "indent-languages": ["javascript"],
        "priority": 0,
    }; // kate-script-header, must be at the start of the file without comments

Cada item será explicado em detalhe agora:

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

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

- `license` [opcional]: Forma curta da licença, como por exemplo BSD 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]: Uma lista, separada por vírgulas, dos estilos de realce de sintaxe obrigatórios. Isto é importante para os módulos de indentação que se baseiam em alguma informação específica de realce no documento. Se for indicado um estilo de sintaxe obrigatório, o módulo só ficará disponível quando estiver o realce apropriado seleccionado. Isto evita algum comportamento indefinido causado pela utilização da indentação sem o esquema de realce esperado. Por exemplo, a indentação de Ruby tira partido disto nos ficheiros `ruby.js` e `ruby.xml`.

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

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

#### O Código-Fonte da Indentação

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

    require("range.js");
    caracteresActivacao = "{}/:;";
    function indent(linha, larguraIndentacao, carácter)
    {
        // invocado para cada linha nova (carácter == '\n') e todos os caracteres indicados na
        // variável global 'caracteresActivacao'. Ao invocar o FerramentasAlinhar
        // a variável 'carácter' está em branco, i.e. carácter == ''.
        //
        // 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 indentada

- `larguraIndentacao`: o número de espaços correspondentes a cada indentação

- `carácter`: ou um carácter de mudança de linha (`ch == '\n'`), algum dos caracteres de activação indicados em `caracteresActivacao` ou vazio, caso o utilizador tenha invocado a acção Ferramentas Alinhar.

O valor devolvido pela função `indent()` define como é que a linha será indentada. 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 a indentação (procura pela linha não-vazia anterior)

- valor devolvido `0`: números >= 0 definem a largura de indentação em espaços

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

- `return [ indentação, alinhamento ];`

Nesse caso, o primeiro elemento é a profundidade de indentação, 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 de indentação, a diferença representa um número de espaços a adicionar após a indentação do primeiro parâmetro. Caso contrário, o segundo número será ignorado. A utilização de tabulações e espaços na indentação é normalmente referida como sendo um modo misto.

Considere o seguinte exemplo: Assuma que usa as tabulações para indentar, 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 indentar a linha 2, a função `indent()` devolve [8, 15]. Em função disso, são introduzidas duas tabulações para indentar 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 ficheiro seja visto com outro tamanho de tabulação.

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

No &Windows;, estes ficheiros localizam-se em `%USER%\AppData\Local\katepart5\indentation`. O `%USER%` normalmente corresponde a `C:\\Users\\`utilizador``.

A criação de um módulo de indentação necessita que actualize os programas, de modo a ver se as alterações se comportam de forma adequada. Em vez de reiniciar a aplicação, basta ir para a linha de comandos e invocar o comando `reload-scripts`.

Se criar programas úteis, por favor considere a hipótese de contribuir com eles para o Projecto do &kappname;, contactando para tal a lista de correio.

### Programas da Linha de Comandos

Como é difícil satisfazer as necessidades de todos, o &kappname; suporta algumas ferramentas auxiliares para manipular rapidamente o texto, usando para tal a linha de comandos incorporada. Por exemplo, o comando `sort` está implementado como um programa. Esta secção explica como criar ficheiros `*.js` que melhoram o &kappname; com algumas funções auxiliares arbitrárias.

Os programas da linha de comandos estão localizados na mesma pasta que os programas de indentação. Como tal, como primeiro passo, crie um ficheiro `*.js` novo, chamado `utilitários.js` na pasta pessoal local, em `$`XDG_DATA_HOME`/katepart5/script/commands`. Normalmente, a variável de ambiente `XDG_DATA_HOME` expande-se tipicamente para `~/.local` ou `~/.local/share`.

No &Windows;, estes ficheiros localizam-se em `%USER%\AppData\Local\katepart5\commands`. O `%USER%` normalmente corresponde a `C:\\Users\\`utilizador``.

#### O Cabeçalho do Programa da Linha de Comandos

O cabeçalho de cada programa da linha de comandos está incorporado como JSON no início do programa, da seguinte forma:

    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": "Ordenar o Texto Seleccionado",
                "category": "Edição",
                "interactive": "false"
            },
            {   "function": "descerLinhas",
                "name": "Descer as Linhas",
                "category": "Edição",
                "shortcut": "Ctrl+Shift+Down",
                "interactive": "false"
            }
        ]
    }; // kate-script-header, must be at the start of the file without comments

Cada item será explicado em detalhe agora:

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

- `license` [opcional]: Forma curta da licença, como por exemplo BSD 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.

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

- `actions` [opcional]: Lista em JSON de objectos JSON que definem as acções que aparecem no menu da aplicação. É oferecida alguma informação detalhada na secção Associar Atalhos.

Dado que o valor de `functions` é uma lista em JSON, um único programa é capaz de conter um número arbitrário de comandos da consola. Cada função está disponível através da linha de comandos 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 ficheiro de programa do exemplo acima tem de implementar as duas funções `ordenar` e `descerLinhas`. Todas as funções têm a seguinte sintaxe:

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

    function <nome>(arg1, arg2, ...)
    {
        // ... implementação, ver também: API de Programação
    }

Os argumentos na linha de comandos são passados à função como `arg1`, `arg2`, etc. Para poder fornecer a documentação para cada comando, basta implementar a função '`help`' da seguinte forma:

    function help(comando)
    {
        if (comando == "ordenar") {
            return i18n("Ordena o texto seleccionado.");
        } else if (cmd == "...") {
            // ...
        }
    }

Se executar `help ordenar` na linha de comandos, irá invocar esta função 'help' com o argumento `comando` configurado com o comando indicado, &ie; `comando == "ordenar"`. O &kappname; irá então apresentar o texto devolvido como documentação para o utilizador. Certifique-se que traduz os textos.

Criar um programa para a linha de comandos obriga a actualizar os programas, de modo a ver se as alterações funcionam apropriadamente. Em vez de reiniciar a aplicação, basta mudar para a linha de comandos e invocar o comando `reload-scripts`.

##### Associar Combinações de Teclas

Para tornar os programas acessíveis no menu da aplicação e para atribuir combinações de teclas de atalho, o programa terá de fornecer um cabeçalho do programa apropriado. No exemplo acima, ambas as funções In `ordenar` e `descerLinhas` aparecem no menu, graças à seguinte componente no cabeçalho do programa:

    var katescript = {
        ...
        "actions": [
            {   "function": "ordenar",
                "name": "Ordenar o Texto Seleccionado",
                "icon": "",
                "category": "Edição",
                "interactive": "false"
            },
            {   "function": "descerLinhas",
                "name": "Descer as Linhas",
                "icon": "",
                "category": "Edição",
                "shortcut": "Ctrl+Shift+Down",
                "interactive": "false"
            }
        ]
    };

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

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

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

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

- `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 predefinido. Por exemplo: Ctrl+Alt+T. Veja a documentação do Qt para mais detalhes.

- `interactive` [opcional]: Se o programa precisa de interacção por parte do utilizador, configure este valor como `true` (verdadeiro).

Se criar programas úteis, por favor considere a hipótese de contribuir com eles para o Projecto do &kappname;, contactando para tal a lista de correio.

### API de Programação

A API de programação aqui apresentada está disponível em todos os programas, &ie; os programas de indentação e os comandos da consola. O `Cursor` e o `Range` são fornecidos através de ficheiros de bibliotecas no `$`XDG_DATA_DIRS`/katepart5/libraries`. Se quiser usá-los no seu programa, o que será necessário para usar algumas das funções do `Document` ou do `View`, inclua por favor a biblioteca necessária, usando:

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

Para extender a API-padrão de programação com funções e protótipos próprio, basta criar um ficheiro novo na pasta de configuração local do &kde;, em `$`XDG_DATA_HOME`/katepart5/libraries` e inclua-a no seu programa, usando:

    require ("nome-do-meu-programa.js");

No &Windows;, estes ficheiros localizam-se em `%USER%\AppData\Local\katepart5\libraries`. O `%USER%` normalmente corresponde a `C:\\Users\\`utilizador``.

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

#### Cursores e Intervalos

Como o &kappname; é um editor de texto, toda a API de programação é baseada em cursores e intervalos, sempre que possível. Um cursor é um simples tuplo `(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 detalhe nas secções seguintes.

##### 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 a seguir ao 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 tanto o cursor de início como o 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`.

    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 semi-aberto `[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 semi-aberto `[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` partilharem 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 começar e acabar 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 um texto no formato `Range(Cursor(linha, coluna), Cursor(linha, coluna))`.

#### Funções Globais

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

##### Ler & Incluir os Ficheiros

    String read(String ficheiro);

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

    void require(String ficheiro);

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

  Desde: &kde; 4.10

##### Depuração

    void debug(String texto);

- Imprime o `texto` no `stdout`, mais precisamente na consola 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 exactamente 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 a língua usada na aplicação. Os textos nos programas que são desenvolvidos no âmbito do código oficial do &kappname; são automaticamente extraídos e preparados para traduções. Por outras palavras, como programador do &kappname;, não terá de se preocupar com a extracção e tradução das mensagens. Contudo, a tradução só funciona dentro da infra-estrutura do &kde;, &ie; novos textos em programas de terceiros, desenvolvidos fora do &kde;, não são traduzidos. Como tal, pense em contribuir com os seus programas para o &kate;, para que uma tradução adequada seja possível.

    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. Para ale´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, 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. 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á a ser executado, existe uma variável global `view` que representa a área de edição activa no momento. Segue-se uma lista com todas as funções disponíveis para o View.

    Cursor view.cursorPosition()

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

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

- Altera a posição actual 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 actual.

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

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

    String view.selectedText();

- Devolve o texto seleccionado. Se não estiver nenhum texto seleccionado, o texto devolvido vem vazio.

    bool view.hasSelection();

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

    Range view.selection();

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

    void view.setSelection(Range intervalo);

- Altera o texto seleccionado para o intervalo indicado.

    void view.removeSelectedText();

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

    void view.selectAll();

- Selecciona o texto por inteiro no documento.

    void view.clearSelection();

- Limpa a selecção de texto actual, sem remover o texto.

#### A API do Document

Sempre que está a executar um programa, existe uma variável global `document` que representa o documento activo no momento. Segue-se uma lista com todas as funções disponíveis para o Document.

    String document.fileName();

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

    String document.url();

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

    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 actualmente para gravar o ficheiro.

    String document.highlightingMode();

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

    String document.highlightingModeAt(Cursor posição);

- 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 algumas alterações por gravar, 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 carácter de mudança de linha `\n`.

    String document.text(int daLinha, int daColuna, int ateLinha, int ateColuna);
    String document.text(Cursor de, Cursor ate);
    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 com 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 carácter na posição do cursor indicada.

    String document.firstChar(int linha);

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

    String document.lastChar(int linha);

- Devolve o último carácter da `linha` indicada que não seja um espaço em branco. O primeiro carácter 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 carácter 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 ateLinha, int ateColuna);
    bool document.removeText(Cursor de, Cursor ate);
    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` tiver neste momento dados por gravar.

  Desde: &kde; 5.0

    bool document.isLineSaved(int linha);

- Devolve `true` (verdadeiro), se a `linha` tiver sido alterada, mas o documento tiver sido gravado. Como tal, neste momento a linha não deverá conter dados por gravar.

  Desde: &kde; 5.0

    bool document.isLineTouched(int linha);

- Devolve `true` (verdadeiro), se a `linha` tiver neste momento dados por gravar ou tiver sido alterada anteriormente.

  Desde: &kde; 5.0

    bool document.findTouchedLine(int linhaInicio, bool baixo);

- Procurar pela próxima linha tocada que comece em `linhaInicio`. A pesquisa é efectuada tanto para cima como para baixo, dependendo da direcçã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 que invoca sempre o `editEnd()` tantas vezes como 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 carácter, int atributo);

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

    bool document.canBreakAt(String carácter, int atributo);

- Devolve `true` (verdadeiro) se o `carácter` 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 contém 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 actual do cursor estiver numa posição de texto válida. Uma posição de texto é válida apenas se se localizar no início, no meio ou no fim de uma linha válida. Para além disso, uma posição de texto é inválida se estiver localizada num item de referência de 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 ficheiros 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);

- Altera o valor da variável do documento identificada pela `chave`.

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

  Desde: &kde; 4.8

    int document.firstVirtualColumn(int linha);

- Devolve a coluna virtual do primeiro carácter 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 carácter 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, devolvendo um objecto inteiro ou um 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, devolvendo um objecto inteiro ou um Cursor.

    Cursor document.anchor(int linha, int coluna, Char carácter);
    Cursor document.anchor(Cursor cursor, Char carácter);

- Pesquisa para trás pelo carácter indicado, começando na posição do cursor indicada. Por exemplo, se for passado o '(', como carácter, esta função irá devolve 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 predefinido 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 carácter 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 carácter 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 carácter 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 carácter 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 carácter na posição do cursor for `dsOthers`, caso contrário devolve `false` (falso).