# 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 plug-ins.

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 coisa. Os valores válidos são o `on`, `off`, `true`, `false`, `1` ou `0`

INTEIRO

- Um número inteiro

TEXTO

- Um texto

#### Comandos para as funções básicas do Editor

    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.

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

- 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-wrap-cursorBOOLEANO ativar

- Ativa ou desativa Quebra de linha.

    set-modeBOOLEANO ativar

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

    replaceTEXTO padrãoTEXTO 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).
  `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, onde está mencionado a string Senhorita Jensen várias vezes, quando alguém vem e lhe diz que ela casou com o Senhor Jones. Você quer, é claro, substituir toda ocorrência 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 regular-expressions

    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.

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

#### 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
     * type: indentation
     * 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.

- `type` [obrigatório]: O tipo deverá ser `indentation`, caso contrário, o &kappname; irá ignorar este script.

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

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

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

#### 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
     * type: commands
     * 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.

- `type` [obrigatório]: O tipo deverá ser `commands`, caso contrário, o &kappname; irá ignorar este programa.

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

    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 programas, i.e. tanto os de recuo como os da linha de comando. Antes de carregar o conteúdo de um programa, o &kappname; adiciona primeiro vários protótipos e funções ao contexto do programa. Esta API de conveniência contém protótipos para alguns itens, como os cursores e intervalos de texto, estando localizada na pasta `$KDEDIR/share/apps/katepart/api`. Aí, os nomes de cada um dos arquivos de JavaScript estão em conformidade com a seguinte nomenclatura:

    <número>_<nome>.js

O número tem dois algarismos e o nome pode ser arbitrário, como por exemplo `utilitários`. Através do número, o &kappname; controla a ordem de execução da API. Por exemplo, o arquivo chamado `05_cursor.js` é carregado antes do arquivo `10_range.js`. (Isto é semelhante à ordem de inicialização do sistema 'init' do Linux).

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/api` e garantir que tem um número (ordem de execução) maior que os outros arquivos `*.js` da pasta global em `$KDEDIR/share/apps/katepart/api`. O &kappname; procura automaticamente em ambas as pastas por arquivos `*.js` e executa-os na ordem correta.

Para extender os protótipos existentes, como o `Cursor` ou o `Range`, a forma recomendada é não modificar os arquivos `*.js` globais. Em vez disso, crie um arquivo `*.js` na pasta local que seja executado após o `05_cursor.js` e altere depois o protótipo `Cursor` no JavaScript.

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

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

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

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

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

    String document.firstChar(int linha);

- Devolve o primeiro caracter da `linha` indicada que não seja um espaço em branco. O primeiro caracter 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 caracter da `linha` indicada que não seja um espaço em branco. O primeiro caracter 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 caracter 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, int linha, 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, int linha, 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.

    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 caracter, 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 caracter, int atributo);

- Devolve `true` (verdadeiro) se o `caracter` 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 caracter 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 caracter 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 caracter);
    Cursor document.anchor(Cursor cursor, Char caracter);

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