&Anders.Lund; &Anders.Lund.mail;
&Dominik.Haumann; &Dominik.Haumann.mail;
Lisiane
Sztoltz

    lisiane@conectiva.com.br

Tradução

# Ferramentas Avançadas de Edição

## Comentar/Descomentar

Os comandos Comentar e Descomentar, disponíveis no menu Ferramentas permitem-lhe adicionar ou remover marcações de comentários à seleção ou à linha atual, se não existir texto selecionado, se os comentários são suportados pelo formato do texto que você está editando.

As regras de como o comentário é feito são feitas nas definições de sintaxe; assim, se o realce de sintaxe não é usado, as ações de comentar/descomentar não são possíveis.

Alguns formatos definem marcas de comentários para linhas únicas, outros suportam marcas de comentários para várias linhas e alguns suportam ambas. Se não estiverem disponíveis os comentários para várias linhas, o ato de comentar uma seleção que não inclui por completo a sua última linha não é possível.

Se um marcador de linha única estiver disponível, é preferível comentar linhas simples onde for aplicável, pois isto ajuda a evitar problemas com comentários aninhados.

Ao remover marcadores de comentários, textos sem comentários devem ser selecionados; ao remover marcadores de comentários de múltiplas linhas de uma seleção, qualquer espaço em branco fora do marcador é ignorado.

Para colocar marcações de comentários, use a opção do menu Ferramentas Comentar ou o atalho de teclado relacionado, que por padrão é &Ctrl;D.

Para remover marcações de comentários, use a opção do menu Ferramentas Descomentar ou o atalho de teclado relacionado, que por padrão é o &Ctrl;&Shift;D.

## A Linha de Comando do Componente de Edição

O componente de edição do &kappname; possui uma linha de comando interna, que lhe permite efetuar várias ações a partir de uma interface mínima. A linha de comando é um campo de texto no fundo da área de edição onde, para mostrá-la, você poderá selecionar a opção Ver Alternar para Linha de Comando ou usar o atalho (que é, por padrão, o F7). O editor oferece um conjunto de comandos, tal como está documentado abaixo, sendo oferecidos mais comandos através de plugins.

Para executar um comando, pressione a tecla Return. A linha de comando irá indicar se foi bem sucedida e, provavelmente, irá mostrar uma mensagem. Se você inseriu na linha de comando pressionando F7, ele ocultar-se-á automaticamente, ao fim de alguns segundos. Para limpar a mensagem e inserir um comando novo, pressione F7 de novo.

A linha de comando possui um sistema de ajuda embutido, podendo inserir o comando `help` para iniciá-lo. Para ver uma lista com todos os comandos disponíveis, invoque o comando `help list`; para ver a ajuda sobre um determinado comando, faça `help comando`.

A linha de comando possui um histórico embutido, como tal, o usuário poderá reutilizar os comandos já digitados. Para navegar no histórico, use as teclas Cima e Baixo. Ao mostrar os comandos do histórico, a parte do argumento do comando será selecionada, o que lhe permite sobrepor facilmente os argumentos.

### Comandos Padrão da Linha de Comando

#### Tipos de argumento

BOOLEANO

  Isto é usado com os comandos que ativam ou desativam certas coisas. Os valores válidos são o `on`, `off`, `true`, `false`, `1` ou `0`.

INTEIRO

  Um número inteiro.

TEXTO

  Uma string separada por aspas simples (') ou aspas (") quando conter espaços.

#### Comandos para configurar o Editor

Estes comandos são oferecidos pelo componente do editor e permitem-lhe configurar apenas o documento e a janela ativos. Isto poderá ser útil se quiser usar uma configuração diferente da pré-definida como, por exemplo, no recuo.

    set-tab-widthINTEIRO largura

  Configura a largura da tabulação como sendo `largura`.

    set-indent-widthINTEIRO largura

  Configura a largura do recuo como `largura`. Só é usado se o usuário recuar com espaços.

    set-word-wrap-columnINTEIRO largura

  Configura a largura da linha para uma quebra como tendo `largura` colunas. Isto é usado se você tiver o seu texto sendo quebrado automaticamente.

    set-icon-borderBOOLEANO ativar

  Configura a visibilidade da borda dos ícones.

    set-folding-markersBOOLEANO ativar

  Configura a visibilidade da área de marcadores de dobra do código.

    set-line-numbersBOOLEANO ativar

  Configura a visibilidade da área de números de linha.

    set-replace-tabsBOOLEANO ativar

  Se estiver ativo, as tabulações são substituídas por espaços, à medida que você vai digitando.

    set-remove-trailing-spaceBOOLEANO ativar

  Se estiver ativo, os espaços finais serão removidos quando o cursor abandonar uma determinada linha.

    set-show-tabsBOOLEANO ativar

  Se estiver ativo, os caracteres de tabulação e espaços estarão visíveis através de um pequeno ponto.

    set-show-indentBOOLEANO ativar

  Se estiver ativo, o recuo será visualizado por uma linha tracejada vertical.

    set-indent-spacesBOOLEANO ativar

  Se estiver ativo, o editor irá recuar com `largura-recuo` espaços por cada nível de recuo, em vez de usar o caractere TAB.

    set-mixed-indentBOOLEANO ativar

  Se estiver ativo, o &kappname; irá usar uma mistura de TABs e espaços para o recuo. Cada nível de recuo irá ter um tamanho de `largura-recuo`, enquanto os restantes níveis de recuo serão otimizados para usar tantos caracteres TAB quantos possíveis.

  Quando for executado, este comando irá ativar o recuo com espaços e, se a largura de recuo não estiver definida, corresponderá a metade da `largura-tabulação` do documento, no momento da execução.

    set-word-wrapBOOLEANO ativar

  Ativa a quebra de linha dinâmica, de acordo com o parâmetro `ativar`

    set-replace-tabs-saveBOOLEANO ativar

  Quando estiver ativo, as tabulações serão substituídas por espaços em branco, sempre que o documento for salvo.

    set-remove-trailing-space-saveBOOLEANO ativar

  Quando estiver ativo, os espaços finais serão removidos de cada linha, sempre que o documento for salvo.

    set-indent-modeTEXTO nome

  Configura o modo de recuo automático como `nome`. Se o `nome` não for conhecido, o modo é configurado como 'none' (nenhum). Os modos válidos são 'none', 'normal', 'cstyle', 'haskell', 'lilypond', 'lisp', 'python', 'ruby' e 'xml'.

    set-auto-identBOOLEANO script

  Ativa ou desativa o recuo automático.

    set-highlightTEXTO realce

  Configura o sistema de realce de sintaxe para o documento. O argumento deverá ser um nome de realce válido, como pode ser visto no menu Ferramentas Realce. Este comando oferece uma lista de completação automática para o seu argumento.

    reload-scripts

  Recarrega todos os scripts do JavaScript usados pelo Kate, incluindo scripts de indentação e de linha de comando.

    set-modeSTRING modo

  Seleciona o esquema de tipo de arquivo para o documento atual.

    nn[oremap]TEXTO original TEXTO mapeado

  Mapeia a sequência `original` para a `mapeada`.

#### Comandos de edição

Estes comandos modificam o documento atual.

    indent

  Recua as linhas selecionadas ou a linha atual.

    unindent

  Remove um nível de recuo das linhas selecionadas ou da linha atual.

    cleanindent

  Limpa o recuo das linhas selecionadas ou da linha atual, de acordo com a configuração de recuo no documento.

    comment

  Insere marcações de comentários para fazer da seleção, linhas selecionadas ou da linha atual um comentário, de acordo com o formato de texto definido pela definição do realce de sintaxe para o documento.

    uncomment

  Remove os marcadores de comentários da seleção, linhas selecionadas ou da linha atual, de acordo com o formato de texto definido pela definição do realce de sintaxe do documento.

    kill-line

  Remove a linha atual.

    replace TEXTO padrão TEXTO substituição

  Substitui o texto correspondente ao `padrão` por `substituição`. Se você quiser incluir espaços em branco no `padrão`, deverá colocar tanto o `padrão` como a `substituição` entre aspas simples ou duplas. Se os argumentos não estiverem entre estes caracteres, a primeira palavra é usada como `padrão` e o resto como a `substituição`. Se a `substituição` estiver em branco, cada ocorrência do `padrão` será removida.

  Você poderá configurar opções para modificar a procura, adicionando dois pontos (:), seguidos de uma ou mais letras, onde cada uma representa uma configuração, o que corresponderá ao formato `replace:opções padrão substituição`. As opções disponíveis são:

  `b`

    Pesquisar para trás.

  `c`

    Procura a partir da posição do cursor.

  `e`

    Procura apenas na área selecionada.

  `r`

    Faz uma pesquisa por uma determinada expressão regular. Se estiver ativo, você poderá usar o `\N`, onde o N é um número que representa as capturas no texto de substituição.

  `s`

    Faz uma pesquisa com distinção entre maiúsculas e minúsculas.

  `p`

    Pede permissão para substituir a próxima ocorrência.

  `w`

    Faz uma correspondência apenas com palavras inteiras.

    dateTEXTO formato

  Insere um texto de data/hora, tal como está definido pelo `formato` indicado, ou com o formato aaaa-MM-dd hh:mm:ss, se não for indicada qualquer formatação. As traduções a seguir são feitas quando for interpretado o `formato`:

  `d` | O dia, como um número sem um zero inicial (1-31).
  `dd` | O dia, como um número com um zero inicial (01-31).
  `ddd` | O nome do dia abreviado, no formato regional (p.ex. 'Seg'..'Dom').
  `dddd` | O nome do dia completo, no formato regional (p.ex. 'Segunda'..'Domingo').
  `M` | O mês, como um número sem um zero inicial (1-12).
  `MM` | O mês, como um número com um zero inicial (01-12).
  `MMMM` | O nome completo do mês localizado (ex.: 'Janeiro'..'Dezembro').
  `MMM` | O nome do mês abreviado, no formato regional (p.ex. 'Jan'..'Dez').
  `aa` | O ano, como um número de dois algarismos (00-99).
  `aaaa` | O ano, como um número de quatro algarismos (1752-8000).
  `h` | As horas sem um zero inicial (0..23 ou 1..12 no caso do formato AM/PM).
  `hh` | As horas com um zero inicial (00..23 ou 01..12 no caso do formato AM/PM).
  `m` | Os minutos sem um zero inicial (0..59).
  `mm` | Os minutos com um zero inicial (00..59).
  `s` | Os segundos sem um zero inicial (0..59).
  `ss` | Os minutos com um zero inicial (00..59).
  `z` | Os milissegundos sem um zero inicial (0..999).
  `zzz` | Os milissegundos com zeros iniciais (000..999).
  `AP` | Usar o formato de horas AM/PM. O AP será substituído por "AM" ou por "PM".
  `ap` | Usar o formato de horas am/pm. O ap será substituído por "am" ou por "pm".

    charTEXTO identificador

  Este comando permite que você insira caracteres literais através de suas identificações numéricas, em decimal, octal ou hexadecimal. Para usá-lo, abra o diálogo de Edição de Comando e digite `char: [número]` na caixa de entrada e clique em OK.

  ##### exemplos do comando `char`

  Entrada: `char:234`

  Resultado: `ê`

  Entrada: `char:0x1234`

  Resultado: `ሴ`

`s///[ig]` `%s///[ig]`

  Este comando faz um sed como operação de procura/substituição na linha atual, ou em um arquivo inteiro (`%s///`).

  Em resumo, é procurado o texto que combine com o padrão de busca , a expressão regular entre a primeira e a segunda barra, e quando é encontrado, a parte que combina com o texto é substituída pela expressão entre a metade e a última parte da string. Os parênteses no padrão de busca criam referências anteriores, isto é, o comando lembra qual parte procurada combinou no parênteses; estas strings podem ser reutilizadas no padrão de substituição, referidas como `\1` para o primeiro conjunto de parênteses, `\2` para o segundo e assim por diante.

  Para procurar por um caractere literal `(` ou `)`, você precisa usar o caractere de escape, que é o caractere de barra invertida: `\(\)`

  Se você puser um `i` no fim da expressão, a correspondência não fará distinção entre maiúsculas ou minúsculas. Se, por outro lado, puser um `g` no fim, todas as ocorrências do padrão serão substituídas, caso contrário, só será substituída a primeira ocorrência.

  ##### Substituindo texto na linha atual

  Seu compilador parou, dizendo a você que a classe `minhaClasse`, mencionada na linha 3902 do seu arquivo fonte, não está definida.

  "Droga!" você pensa, é claro que é `MinhaClasse`. Você vai para a linha 3902, e em vez de tentar encontrar a palavra no texto, você lança o Diálogo de Edição de Comando, digita `s/minhaclasse/MinhaClasse/i`, clica no botão OK, salva o arquivo e compila – com sucesso, sem erros.

  ##### Substituindo texto no arquivo inteiro

  Imagine que você tem um arquivo, no qual está mencionada a string Senhorita Jensen várias vezes, quando aparece alguém e lhe diz que ela casou com o Senhor Jones. Você quer, é claro, substituir todas as ocorrências de Senhorita Jensen por Senhora Jones.

  Entre na linha de comando e digite o comando `%s/Srª Silva/Srª Braga/`, pressionando RETURN para terminar.

  ##### Um Exemplo Mais Avançado

  Este exemplo tira partido das referências anteriores assim como das classes de palavras (se você não souber o que isso é, baseie-se na documentação referida abaixo).

  Suponha que você possui a seguinte linha:

      void MinhaClasse::DoStringOps( String      &foo, String &bar, String *p, int  &a, int &b )

  Agora, você pode perceber que este não é um código bom, e decidir que deseja usar a palavra-chave `const` para todos os argumentos address of, aqueles caracterizados pelo operador & em frente ao nome do argumento. Você poderia também simplificar o espaço em branco, pois assim existiria somente um caractere de espaço em branco entre cada palavra.

  Abra o Diálogo de Edição de Comando, e digite `s/\s+(\w+)\s+(&)/ const \1 \2/g` e clique no botão OK. O caractere `g` no final da expressão faz com que a expressão regular recompile cada combinação, para recuperar as referências de volta.

  Saída `void MinhaClasse::DoStringOps( const String &foo, const String &bar, String *p, const int &a, const int &b )`

  Missão completa! Agora, o que aconteceu? Bem, procuramos por espaços em branco (`\s+`) seguidos por um ou mais caracteres alfabéticos(`\w+`) seguidos por mais espaços em branco (`\s+`) seguidos por um E comercial, e no processo é salvo o pedaço alfabético e o E comercial para reutilização na operação de substituição. Quando substituímos a parte relacionada da nossa linha, com um espaço em branco, seguido por const, seguido por um espaço em branco, seguido por nosso pedaço alfabético (`\1`) seguido por um espaço em branco, em por fim, seguido por nosso E comercial salvo (`\2`)

  Em alguns casos, a parte alfabética foi String, em alguns int, assim, usar a classe de caractere `\w` e o quantificador `+` provê uma vantagem considerável.

    sort

  Ordena o texto selecionado ou todo o documento.

    natsort

  Ordena as linhas selecionadas ou todo o documento naturalmente.

  ##### `sort` x `natsort`

  `sort(a10, a1, a2)` resulta em `a1, a10, a2`

  `natsort(a10, a1, a2)` resulta em `a1, a2, a10`

    moveLinesDown

  Move as linhas selecionadas para baixo.

    moveLinesUp

  Move as linhas selecionadas para cima.

    uniq

  Remove linhas duplicadas do texto selecionado ou do documento inteiro.

    rtrim

  Remove o espaço à direita do texto selecionado ou do documento inteiro.

    ltrim

  Remove o espaço à esquerda do texto selecionado ou do documento inteiro.

    joinTEXTO separador

  Mescla as linhas selecionadas ou o documento inteiro. Opcionalmente, recebe um parâmetro definindo um separador, por exemplo: ``join` ', '`

    rmblank

  Remove todos os espaços em branco do texto selecionado ou do documento inteiro.

    unwrap

  Remove as quebras de linha do texto selecionado ou do documento inteiro.

    eachTEXTO script

  Fornecida uma função do JavaScript como argumento, chama pela lista de linhas selecionadas e substitui-as com o valor de retorno desta chamada.

  ##### Mescla as linhas selecionadas

  ``each` 'function(lines){return lines.join(", ")}'`

  Ou, de maneira resumida:

  ``each` 'lines.join(", ")'`

    filterTEXTO script

  Fornecida uma função do JavaScript como argumento, chama pela lista de linhas selecionadas e remove-as onde a chamada retorna falso.

  ##### Remover linhas em branco

  ``filter` 'function(1){return 1.length > 0;}'`

  Ou, de maneira resumida:

  ``filter` 'line.length > 0'`

    mapTEXTO script

  Fornecida uma função do JavaScript como argumento, chama pela lista de linhas selecionadas e substitui a linha com o valor de retorno da chamada.

  ##### Remover linhas em branco

  ``map` 'function(line){return line.replace(/^s+/,"");}'`

  Ou, de maneira resumida:

  ``map` 'line.replace(/^s+/,"")'`

    duplicateLinesUp

  Duplica as linhas selecionadas acima da seleção atual.

    duplicateLinesDown

  Duplica as linhas selecionadas abaixo da seleção atual.

#### Comandos de navegação

    gotoINT linha

  Este comando vai para a linha indicada.

    grep TEXTO padrão

  Pesquisa o documento pela expressão regular `padrão`. Para mais informações, veja as

    findTEXTO padrão

  Este comando vai para a primeira ocorrência do `padrão`, de acordo com a configuração. As ocorrências a seguir poderão ser encontradas com a opção Editar Procurar Próximo (o atalho por padrão é o F3).

  O comando de procura poderá ser configurado adicionando dois-pontos, seguidos de uma ou mais opções, sendo o formato `find:opções padrão`. São suportadas as seguintes opções:

  `b`

    Pesquisar para trás.

  `c`

    Procura a partir da posição do cursor.

  `e`

    Procura apenas na área selecionada.

  `r`

    Faz uma pesquisa por uma determinada expressão regular. Se estiver ativo, você poderá usar o `\N`, onde o N é um número que representa as capturas no texto de substituição.

  `s`

    Faz uma pesquisa com distinção entre maiúsculas e minúsculas.

  `w`

    Faz uma correspondência apenas com palavras inteiras.

    ifindTEXTO padrão

  Este comando oferece uma procura à-medida-que-digita. Você poderá configurar o comportamento da procura adicionando dois-pontos (:), seguidos de uma ou mais opções, como se segue: `ifind:opções padrão`. As opções permitidas são

  `b`

    Pesquisar para trás.

  `r`

    Faz uma procura por uma expressão regular.

  `s`

    Faz uma pesquisa com distinção entre maiúsculas e minúsculas.

  `c`

    Procura a partir da posição do cursor.

#### Comandos das funções básicas do editor (dependem do aplicativo em que o componente de edição é usado)

    w

  Salvar o documento atual.

    wa

  Salvar todos os documentos abertos.

    q

  Fechar o documento atual.

    qa

  Fechar todos os documentos abertos.

    wq

  Salvar e fechar o documento atual.

    wqa

  Salvar e fechar todos os documentos abertos.

    x

  Salvar e fechar o documento atual somente se ele foi modificado.

    x

  Salvar e fechar todos os documentos abertos somente se eles foram modificados.

    bp

  Ir para o documento anterior na lista de documentos.

    bn

  Ir para o próximo documento na lista de documentos.

    new

  Abrir um novo documento em uma divisão de visão horizontal.

    vnew

  Abrir um novo documento em uma divisão de visão vertical.

    e

  Recarregar o documento atual se ele tiver sido modificado em disco.

    enew

  Editar um novo documento.

    print

  Abrir a janela de impressão para imprimir o documento atual.

## Usando o Desdobramento de Código

O desdobramento ou dobragem de código permite-lhe ocultar partes de um documento no editor, tornando mais simples analisar globalmente arquivos grandes. No &kappname;, as regiões desdobráveis são calculadas com base nas regras das definições de realce de sintaxe; como tal só está disponível em alguns formatos - tipicamente em código-fonte de programas, código em XML e semelhantes. A maioria das definições de realce que suportam o desdobramento de código também lhe permitem definir manualmente regiões desdobráveis, tipicamente com as palavras-chave `BEGIN` e `END`.

Para usar a funcionalidade de desdobramento de código, ative os marcadores com a opção Exibir Mostrar as Marcações de Dobragem, se não estiverem já visíveis. A área de Marcações de Dobragem, no lado esquerdo da tela, mostra uma visão gráfica sobre as regiões que poderão ser recolhidas ou expandidas, com símbolos triangulares para indicar a operação possível numa determinada região: um triângulo para baixo significa que a região é expandida; clicar sobre ele irá recolher a região, clicar em um triângulo para direita irá expandi-la.

Estão disponíveis onze comandos para manipular o estado das regiões dobradas; para tal, veja a documentação do menu.

As linhas recolhidas serão lembradas quando um arquivo é fechado, assim quando você reabri-lo, os nós que estiverem recolhidos permanecerão dobrados. Isto se aplica a operações de recarregamento também.

Se você não quiser usar a funcionalidade de desdobramento do código, poderá desativar a opção Mostrar as marcações de dobragem (se disponíveis) na página Aparência do editor de configuração.

## Estender o &kappname; com Programas

Desde o &kappname; 3.4, no KDE 4.4, o componente de edição do &kappname; é facilmente extensível, através da criação de scripts. A linguagem de programação é o ECMAScript (vulgarmente 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 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 por exemplo `javascript.js` na pasta pessoal local `$KDEHOME/share/apps/katepart/script/indentation`.

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

O cabeçalho do arquivo `javascript.js` está incorporado num comentário e possui o seguinte formato

    /* kate-script
     * name: JavaScript
     * author: Nome de Exemplo <nome.exemplo@endereco.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * required-syntax-style: javascript
     * indent-languages: javascript
     * priority: 0
     * i18n-catalog: meucatalogo
     *
     * Uma linha sem o símbolo ':' interrompe o processamento do cabeçalho. Isto é, poderá
     * adicionar mais algum texto aqui como, por exemplo, uma licença detalhada.
     */

Cada item será agora explicado em detalhe:

- `kate-script` [obrigatório]: Este texto tem que aparecer na primeira linha do arquivo `*.js`, caso contrário, o &kappname; irá ignorar o script.

- `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 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]: Lista separa por vírgulas dos estilos de realce de sintaxe necessários. 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, separada por vírgulas, de estilos de sintaxe que este módulo consegue recuar corretamente, p.ex.: 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.

- `i18n-catalog` [opcional]: Catálogo de mensagens adicional (arquivo `.po`) carregado para a tradução de endentações de terceiros.

O &kappname; lê todos os pares no formato chave:valor até que não consiga encontrar mais nenhum símbolo de ':'. Isto implica que o cabeçalho poderá conter texto arbitrário, como uma licença, tal como aparece no exemplo.

#### 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, i.e. 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 `$KDEDIR/share/apps/katepart/script/indentation`.

A criação de um módulo de recuo necessita o recarregamento dos 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 comando e invocar o comando `reload-scripts`.

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

### Programas da Linha de Comando

Como é difícil satisfazer as necessidades de todos, o &kappname; suporta 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 programa. Esta seção explica como criar arquivos `*.js` que estendem o &kappname; com algumas funções auxiliares arbitrárias.

Os programas da linha de comando estão localizados na mesma pasta que os programas de recuo. Como tal, como primeiro passo, crie um arquivo `*.js` novo, chamado `utilitários.js` na pasta pessoal local, em `$KDEHOME/share/apps/katepart/script/commands`.

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

O cabeçalho de cada programa da linha de comandos está incorporado como um comentário e encontra-se no seguinte formato

    /* kate-script
     * author: Nome de Exemplo <nome.exemplo@endereco.org>
     * license: BSD
     * revision: 1
     * kate-version: 3.4
     * functions: sort, format-paragraph
     * i18n-catalog: meucatalogo
     *
     * Uma linha sem o símbolo ':' interrompe o processamento do cabeçalho. Isto é, você poderá adicionar
     * algum texto opcional aqui como, por exemplo, uma licença detalhada.
     */

Cada um dos elementos será explicado em detalhe:

- `kate-script` [obrigatório]: Este texto tem que aparecer na primeira linha do arquivo `*.js`, caso contrário, o &kappname; irá ignorar o script.

- `author` [opcional]: O nome e a informação de contato 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, separada por vírgulas, dos comandos do programa.

- `i18n-catalog` [opcional]: Catálogo de mensagens adicional (arquivo `.po`) carregado para a tradução dos programas de terceiros.

O &kappname; lê todos os pares no formato chave:valor, até que não consiga encontrar mais nenhum símbolo de dois-pontos. Isto implica que o cabeçalho possa conter algum texto arbitrário, como a licença que aparece no exemplo.O valor da chave 'functions' é uma lista, separada por vírgulas, de comandos para a linha de comandos. Isto significa que um único programa poderá conter um conjunto arbitrário de comandos. Cada uma das funções está disponível no &kappname; através da linha de comando incorporada.

#### 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 `formatar-paragrafo`. 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, i.e. `cmd == "sort"`. O &kappname; irá assim apresentar o texto devolvido como documentação ao usuário. Certifique-se de traduzir os textos.

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

Para poder atribuir atalhos de teclado, o programa terá que fornecer uma função chamada `action` da seguinte forma:

    function action(comando)
    {
        var a = new Object();
        if (comando == "ordenar") {
            a.text = i18n("Ordenar o Texto Selecionado");
            a.icon = "";
            a.category = "";
            a.interactive = false;
            a.shortcut = "";
        } else if (comando == "descerLinhas") {
            // repetir para a ação seguinte
        }
        return a;
    }

O parâmetro `comando` da função indica qual o comando para o qual se pede o atalho de teclado respectivo. Existem vários campos que você terá que indicar no objeto de JavaScript devolvido:

- `a.text` [obrigatório]: O texto que aparece no menu Ferramentas Programas . Certifique-se de usar o `i18n` para as traduções.

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

- `a.category` [opcional]: Se for indicada uma categoria, o programa aparece num submenu. Certifique-se de usar o `i18n` para as traduções.

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

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

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

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

### API de Programação

A API de programação aqui apresentada está disponível em todos os scripts, p.ex., os scripts de indentação e os comandos do terminal. O `Cursor` e o `Range` são fornecidos por arquivos de bibliotecas no `$KDEDIR/share/apps/katepart/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 funções e protótipos próprios, basta criar um arquivo novo na pasta de configuração local do KDE, em `$KDEHOME/share/apps/katepart/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, 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 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();`

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

    bool 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 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, p.ex. 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 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 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. Em outras palavras, como programador do &kappname;, você não terá que se preocupar com a extração e tradução das mensagens. Contudo, para programas de terceiros, desenvolvidos fora do KDE, você terá que extrair e traduzir você mesmo as mensagens. Juntamente com os seus programas, terá que distribuir também um catálogo de traduções que inclui todos os textos traduzidos. Além disso, o cabeçalho do seu programa terá que indicar explicitamente o catálogo a carregar com a indicação do `i18n-catalog`.

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

    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.

#### A API do Document

Sempre que está sendo executado um programa, existe uma variável global `document` que representa o documento ativo no momento. Segue-se uma lista com 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 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.

    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, p.ex., 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.

    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, i.e., esta chamada pode ser encadeada.

    void document.editEnd();

  Termina um grupo de edição. A última invocação do `editEnd()` (i.e., 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.

    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.

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

  Define o valor da variável do documento solicitada pela chave. Devolve o valor da variável alterada.

  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, i.e., 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).