&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 &kate; 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

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

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

    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-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 &kate; 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-modenome

  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 o 'cstyle', 'csands', 'xml', 'python', 'varindent' e 'none'.

    set-highlightrealce

  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.

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

    replacepadrãosubstituiçã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.

    dateformato

  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 milisegundos sem um zero inicial (0..999).
  `zzz` | Os milisegundos 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".

    charidentificador

  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.

#### Comandos de navegação

    gotoINT linha

  Este comando vai para a linha indicada.

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

    ifindpadrã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 &kate;, 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 Ver 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á espandí-la.

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

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.

## Extender o &kate; com Programas

Desde o &kate; 3.4, no KDE 4.4, o componente de edição do &kate; é facilmente extensível, através da criação de scripts. A linguagem de programação é o ECMAScript (vulgarmente conhecido como JavaScript). O &kate; 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
     *
     * 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 &kate; irá ignorar o programa.

- `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 &kate; necessária.

- `type` [obrigatório]: O tipo deverá ser `indentation`, caso contrário, o &kate; 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.

O &kate; 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 &kate; com vários módulos de recuo. O código fonte correspondente em JavaScript poderá ser encontrado em `$KDRDIR/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 &kate;, contactando para isso a lista de correio.

### Programas da Linha de Comando

Como é difícil satisfazer as necessidades de todos, o &kate; 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 extendem o &kate; 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
     *
     * 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 &kate; irá ignorar o programa.

- `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 &kate; necessária.

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

- `functions` [obrigatório]: Uma lista, separada por vírgulas, dos comandos do programa.

O &kate; 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 &kate; 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 "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 &kate; irá assim apresentar o texto devolvido como documentação ao usuário.

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 &kate;, 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 &kate; 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 &kate; controla a ordem de execução da API. I.e., o arquivo chamado `05_cursor.js` é invocado antes do arquivo `10_range.js`. (Isto é semelhante à ordem de inicialização do sistema 'init' do Linux).

Para extender a API-padrão de programação 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 &kate; 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 &kate; é 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

    void debug(String texto);

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

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

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

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