# Trabalhando com plugins

Você poderá ativar os plugins individualmente na caixa de diálogo de configuração, a qual também oferece acesso às opções de configuração adicionais dos plugins que necessitem delas.

## Plugins do aplicativo &kate;

Os plugins do &kate; são funções adicionais para o editor &kate;. Eles poderão adicionar menus e atalhos extra, assim como estender as funcionalidades do &kate;. Você poderá instalar ou desinstalar os que quiser, dentro do &kate;. Abra a janela de configuração do &kate; com a opção Configurações Configurar o &kate;.... Selecione o Aplicativo Plugins para escolher os plugins desejados.

Os plugins do aplicativo disponíveis são:

- Ferramentas externas - Executa ferramentas e aplicativos externos

- Navegador Backtrace - exibição da ferramenta de navegação Backtrace C/C++

- Plugin de compilação- Compila e mostra as mensagens de erro

- Fechamento com exclusão/inclusão - Fecha um grupo de documentos com base em uma extensão ou caminho comuns

- Seletor de cor - Exibe uma pré-visualização para nomes de cor conhecidos

- Colchetes coloridos - Colchetes coloridos para facilitar a leitura

- CTags - Procurar definições/declarações com CTags

- Visualização do documento -Visualize o documento no formato de destino.

- Seletor de documento - Troca rápida de documentos &Alt;

- Navegador do sistema de arquivos - Ferramenta de navegação no sistema de arquivos

- Exibição da árvore de documentos - Exibe os arquivos abertos em uma árvore de arquivos

- &gdb; - Oferece uma interface simples para o &gdb;

- Plugin do projeto - Integração com &git; e outros sistemas de controle de versão

- Replicode - linguagem construtivista AI em tempo real

- Cliente LSP - cliente LSP que fornece navegação e conclusão de código para vários idiomas

- Pesquisar e substituir - Pesquisa e substitui nos documentos, pastas ou projetos

- Ferramenta de visualização de Scripts & Snippets - Cria ou baixa snippets de código e scripts do editor

- Macros de teclado - Grava e reproduz macros de teclado (ou seja, sequências de ações do teclado)

- Plugin do SQL - Executa pesquisas em bancos de dados SQL

- Visualizador de símbolos - Extrair e mostrar os símbolos de referência do código

- Visualização das ferramentas do Terminal - Tenha um terminal pronto, usando o widget do &konsole; do &kde;

- Navegador do sistema de arquivos - Ferramenta de navegação no sistema de arquivos

- Completamento de &XML; - Apresenta os elementos de &XML;, os seus atributos, valores e entidades permitidas pela DTD

- Validação do &XML; -Valida arquivos &XML; usando xmllint

- Explorador do compilador - Interface para a ferramenta exploradora de compiladores

- Formatação - Plugin de formatação de código

## Ferramentas externas

O plugin Ferramentas externas permite invocar aplicativos externos com dados relacionados ao documento atual, por exemplo, seu URL, diretório, texto ou seleção. Uma vez ativado, uma página de configuração é exibida, como mostrado abaixo, permitindo alterar ou remover ferramentas existentes. Da mesma forma, novas ferramentas podem ser adicionadas conforme sua preferência. As ferramentas aparecerão então no submenu Ferramentas externas do menu Ferramentas do aplicativo.

A página de configuração permite adicionar novas ferramentas externas clicando no botão Adicionar. Nesse caso, um menu pop-up aparece onde é possível adicionar uma nova ferramenta externa, adicionar uma ferramenta existente de uma lista predefinida ou adicionar uma nova categoria para organizar as ferramentas externas em categorias. Da mesma forma, as ferramentas existentes podem ser modificadas com um clique duplo ou invocando Editar..., e Remover remove as ferramentas selecionadas.

### Configurando ferramentas externas

Editar uma ferramenta abre uma caixa de diálogo de configuração que permite uma configuração detalhada da ferramenta.

Como se pode ver, muitos detalhes podem ser definidos, nomeadamente:

- `Nome`, o nome da ferramenta, que aparecerá posteriormente no menu.

  `Ícone`, ícone opcional que fica visível no menu.

  `Executável`, executável incluindo um caminho completo, ou seu executável deve estar na variável de ambiente `PATH`.

  `Argumentos`, argumentos opcionais que são passados ​​para o executável.

  `Entrada`, entrada opcional que é passada para o processo via stdin.

  `Pasta de trabalho`, o diretório de trabalho no qual a ferramenta será iniciada. Se estiver vazio, o diretório de trabalho será definido como o caminho do documento atual.

  `Tipos MIME`, se definido, a ferramenta fica ativa somente se o tipo MIME do documento atual corresponder.

  `Salvar`, quando invocado, não salva nada, salva o documento atual ou todos os documentos.

  `Gatilho`, um gatilho para executar esta ferramenta. Um gatilhoafetará apenas o documento atualmente ativo e só será executado se o tipo MIME do documento atualmente ativo corresponder ao tipo MIME da ferramenta externa.

  Os seguintes gatilhos estão disponíveis:

- `Nenhum`, este é o padrão, significa que a ferramenta não tem nenhum gatilho.

  `Antes de salvar`, este gatilho será executado imediatamente antes de salvar o documento.

  `Após salvar`, este gatilho executará a ferramenta depois que o documento for salvo.

`Recarregar o documento atual após a execução`, útil quando o arquivo atual é modificado no disco.

`Saída`, a saída define o destino do stdout. Ela pode ser definida como `Ignorada`, `Inserir na posição do cursor`, `Substituir texto selecionado`, `Substituir documento atual`, `Anexar ao documento atual`, `Inserir em novo documento`, `Copiar para a área de transferência` ou `Mostrar no painel`.

`Comando do editor`, comando opcional que pode ser usado para invocar a ferramenta externa através da linha de comando embutida.

O botão Padrões só é visível para ferramentas que são disponibilizadas com o Kate. Ao clicar nele, todas as configurações da ferramenta são revertidas para os valores padrão (ou seja, de fábrica).

### Expansão de variável

Alguns campos de edição, como o Executável, os Argumentos, a Entrada e a Pasta de trabalho, suportam variáveis ​​que são expandidas ao invocar a ferramenta. Isso é indicado pelo ícone {} que aparece quando um desses campos de entrada de texto recebe o foco (veja o círculo vermelho):

Ao passar o cursor sobre um desses campos de entrada de texto, também é exibida uma dica de ferramenta com o texto expandido atual. Além disso, clicar na ação {} abrirá uma caixa de diálogo que lista todas as variáveis ​​disponíveis:

Esta funcionalidade oferece muita flexibilidade ao definir uma ferramenta externa, já que todas as variáveis ​​do formato `%{...}` são expandidas quando a ferramenta é invocada. Há dois tipos de variáveis ​​suportadas:

- `%{nome-variável}`

- `%{nome-variável:<valor>}`

O primeiro formato, `%{nome-variável}`, simplesmente substitui a variável pelo seu conteúdo. Por exemplo, a variável `%{Document:FileName}` é substituída pelo nome do arquivo do documento atual, sem o seu caminho. O segundo formato `%{nome-variável:<valor>}` obtém o conteúdo `<valor>`. Por exemplo, isso pode ser usado para expandir uma variável de ambiente com `%{ENV:HOME}`, ou pode-se obter a data atual no formato desejado, como `%{Date:yyyy-MM-dd}`.

Variáveis suportadas incluem:

- `Document:FileBaseName`: Nome base do arquivo sem o caminho e sufixo do documento atual.

  `Document:FileExtension`: Extensão do arquivo do documento atual.

  `Document:FileName`: Nome do arquivo sem o caminho do documento atual.

  `Document:FilePath`: Caminho completo do documento atual incluindo o nome do arquivo.

  `Document:Text`: Conteúdo do documento atual.

  `Document:Path`: Caminho completo do documento atual excluindo o nome do arquivo.

  `Document:NativeFilePath`: Caminho completo do documento, incluindo o nome do arquivo, com o separador de caminho nativo (barra invertida no Windows).

  `Document:NativePath`: Caminho completo do documento, excluindo o nome do arquivo, com o separador de caminho nativo (barra invertida no Windows).

  `Document:Cursor:Line`: Número da linha da posição do cursor de texto posição no documento atual (começa com 0).

  `Document:Cursor:Column`: Número da coluna da posição do cursor de texto no documento atual (começa com 0).

  `Document:Cursor:XPos`: Componente X das coordenadas da posição do cursor na tela global.

  `Document:Cursor:YPos`: Componente X das coordenadas da posição do cursor na tela global.

  `Document:Selection:Text`: Seleção de texto do documento atual.

  `Document:Selection:StartLine`: Linha inicial do texto selecionado no documento atual.

  `Document:Selection:StartColumn`: Coluna inicial do texto selecionado no documento atual.

  `Document:Selection:EndLine`: Linha final do texto selecionado no documento atual.

  `Document:Selection:EndColumn`: Coluna final do texto selecionado no documento atual.

  `Document:RowCount`: Número de linhas do documento atual.

  `Document:Variable:<variável>`: Expande variáveis do documento arbitrárias.

  `Date:Locale`: A data atual no formato local atual.

  `Date:ISO`: A data atual (ISO).

  `Date:<valor>`: A data atual (formato do QDate).

  `Time:Locale`: A hora atual no formato local atual.

  `Time:ISO`: A hora atual (ISO).

  `Time:<valor>`: A hora atual (formato do QTime).

  `ENV:<valor>`: Acessa variáveis do ambiente.

  `JS:<expressão>`: Avalia instruções JavaScript simples.

  `PercentEncoded:<texto>`: Texto codificado como porcentagem.

  `UUID`: Gera uma nova UUID.

### Lista de ferramentas padrão

Diversas ferramentas são fornecidas por padrão. No entanto, se você tiver ferramentas mais úteis, contribua com elas para nosso projeto no GitLab para que possamos adicioná-las a esta lista. Todas as ferramentas padrão são visíveis na lista por padrão. No entanto, todas as ferramentas podem ser alteradas ao seu gosto, incluindo a categoria ou até mesmo excluindo ferramentas. As ferramentas excluídas podem ser adicionadas novamente clicando no botão Adicionar na página de configuração, conforme descrito acima.

### git-cola

O git-cola é um cliente gráfico do Git que permite preparar e enviar alterações com facilidade. Se instalado, ele também estará disponível pela linha de comando digitando `git-cola`

- `Nome`: git-cola

  `Ícone`: git-cola

  `Executável`: git-cola

  `Argumentos`: -r %{Document:Path}

  `Comando do editor`: git-cola

### gitk

O gitk também é um cliente git que permite visualizar o histórico do git de forma organizada.

- `Nome`: gitk

  `Ícone`: git-gui

  `Executável`: gitk

  `Pasta de trabalho`: %{Document:Path}

  `Comando do editor`: gitk

### git blame

Inicia o comando `git blame` para acompanhar facilmente as alterações do Git no arquivo atual.

- `Nome`: git blame

  `Executável`: git

  `Argumentos`: gui blame %{Document:FileName}

  `Salvar`: Documento atual

  `Pasta de trabalho`: %{Document:Path}

  `Comando do editor`: git-blame

### Executar Shell Script

Inicia um konsole externo no qual o documento atual é executado. O script precisa declarar o interpretador na primeira linha por meio de um shebang `#!/path/interpreter`.

- `Nome`: Executar Shell Script

  `Ícone`: system-run

  `Executável`: konsole

  `Argumentos`: -e sh -c "cd %{Document:Path} && pwd && chmod -vc a+x %{Document:FileName} && ./%{Document:FileName} ; echo Press any key to continue. && read -n 1"

  `Salvar`: Documento atual

  `Pasta de trabalho`: %{Document:Path}

  `Comando do editor`: run-script

### Texto selecionado no Google

Pesquisa o texto selecionado no Google.

- `Nome`: Texto selecionado no Google

  `Ícone`: globe

  `Executável`: xdg-open

  `Argumentos`: "https://www.google.com/search?q=%{Document:Selection:Text}"

  `Comando do editor`: google

### Inserir UUID

Insere uma nova UUID cada vez que esta ação é invocada.

- `Nome`: Inserir UUID

  `Executável`: echo

  `Argumentos`: %{UUID}

  `Saída`: Insere na posição do cursor

  `Comando do editor`: uuid

### Arquivo completo do formato Clang

Executa o clang-format no arquivo atual no disco. O documento é recarregado em seguida.

- `Nome`: Arquivo completo do formato Clang

  `Executável`: clang-format

  `Argumentos`: -i %{Document:FileName}

  `Pasta de trabalho`: %{Document:Path}

  `Salvar`: Documento atual

  `Recarregar`: Sim

  `Comando do editor`: clang-format-file

### Texto selecionado no formato Clang

Executa o clang-format apenas no texto selecionado no documento atual.

- `Nome`: Texto selecionado no formato Clang

  `Executável`: clang-format

  `Argumentos`: -assume-fileName: %{Document:FileName}

  `Pasta de trabalho`: %{Document:Path}

  `Entrada`: %{Document:Selection:Text}

  `Saída`: Substitui o texto selecionado

  `Comando do editor`: clang-format-selection

### Visualização do Qt Quick 2 (qmlscene)

Exibe uma prévia do arquivo qml atual em qmlscene.

- `Nome`: Visualização do Qt Quick 2 (qmlscene)

  `Executável`: qmlscene

  `Argumentos`: %{Document:FileName}

  `Salvar`: Documento atual

  `Pasta de trabalho`: %{Document:Path}

  `Comando do editor`: qml-preview

### Arquivo completo do formato JSON

Formata todo o arquivo JSON.

- `Nome`: Arquivo completo do formato JSON

  `Ícone`: application-json

  `Executável`: jq

  `Argumentos`: %{Document:FileName}

  `Salvar`: Documento atual

  `Pasta de trabalho`: %{Document:Path}

  `Saída`: Substitui o documento atual

  `Comando do editor`: json-format-file

### Arquivo completo do formato XML

Formata todo o arquivo XML.

- `Nome`: Arquivo completo do formato XML

  `Ícone`: application-xml

  `Executável`: xmllint

  `Argumentos`: --format %{Document:FileName}

  `Salvar`: Documento atual

  `Pasta de trabalho`: %{Document:Path}

  `Saída`: Substitui o documento atual

  `Comando do editor`: xml-format-file

## Plugin do navegador Backtrace

### Usando o plugin do navegador backtrace

Este plugin é destinado a desenvolvedores e provavelmente de pouca utilidade para os usuários. Isto mostra um backtrace entregue pelo gdb em uma lista de exibição na janela de visualização do &kate; Clicar em um item abre o arquivo selecionado e salta para o número da linha correta. Ele funciona para rastreamentos gerados em sua própria máquina, mas também funciona para backtraces de outras pessoas, &ie; com `/home/dummy/qt-copy/…/qwidget.cpp` encontrados em outras máquinas. Para que funcione, você deve indexar os diretórios onde o código-fonte está localizado.

Às vezes, existem vários arquivos com o mesmo nome, ⪚

- `kdegraphics/okular/generators/dvi/config.h`
- `kdepim-runtime/resources/gmail/saslplugin/config.h`

Para escolher a opção certa, o plugin seleciona as duas últimas partes da &URL;, neste caso, isso seria

- `dvi/config.h`
- `saslplugin/config.h`

Geralmente, o plugin correto é encontrado.

A indexação da ramificação master e outra ramificação, é claro, gerará um conflito.

### Configuração

Na página de configuração, adicionar os diretórios contendo o código-fonte.

Navegador backtrace
Configurar caminhos na exibição da ferramenta do navegador Backtrace

Clicar em OK iniciará a indexação. Quando a indexação for finalizada, abra a ferramenta de visualização do navegador backtrace.

Agora você pode carregar um backtrace da área de transferência (⪚, quando clicar em Copie para a área de transferência no &drkonqi;) ou de um arquivo.

## Plugin de compilação

### Introdução

O plugin de compilação permite executar ações como build, clean e compile em um projeto. Você também pode executar automaticamente os aplicativos gerados. O plugin basicamente oferece uma maneira de configurar conjuntos de comandos para serem executados e pode analisar a saída em busca de links para arquivos e linhas e colunas específicas nesses arquivos. Portanto, mesmo que o plugin tenha sido originalmente criado para compilar C/C++ e testado principalmente com essa linguagem, ele também pode ser útil para outros fins e linguagens.

### Usando o plugin de compilação

O plugin de compilação adiciona uma área de ferramentas Compilar na parte inferior e um menu Compilar no menu principal. A área de ferramentas pode ser usada para selecionar e configurar alvos de compilação, enquanto o menu e seus atalhos podem ser usados ​​para selecionar e executar os comandos de shell configurados.

Criar saída

A visualização da ferramenta Compilar possui duas abas:

- Configurações do alvo

- Saída

#### Aba das configurações do alvo

A aba de configurações de alvo pode ser usada para configurar vários alvos e definir conjuntos de alvos.

Um conjunto de alvos é um grupo de comandos que podem ser executados em uma pasta de trabalho específica. Os conjuntos de alvos podem ser adicionados em Projetos ou Sessão. Os conjuntos de alvos personalizados adicionados em Projetos são armazenados em um arquivo .kateproject.build na pasta raiz do projeto e são restaurados quando o projeto é reaberto. Os conjuntos de alvos adicionados em Sessão são armazenados na configuração atual da sessão Kate.

A primeira linha, em um conjunto de alvos, contém um nome para o conjunto na primeira coluna, e na segunda coluna temos a pasta onde os comandos devem ser executados. Em cada linha seguinte, temos um nome para o comando na primeira coluna, um comando de compilação na segunda coluna e um comando de execução na terceira coluna. Para editar um deles, clique duas vezes na entrada ou use o atalho de edição (geralmente F2).

Pasta de trabalho

- A segunda coluna da primeira linha em um conjunto de alvos é usada para configurar a pasta de trabalho usada para compilar e executar comandos. Se o plugin de projeto estiver habilitado, a string da pasta de trabalho também pode conter marcadores para o caminho da pasta base do projeto: %B e para o nome: %b

Comando de compilação

- A segunda coluna nas "linhas não iniciais" contém o comando do shell a ser executado na pasta de trabalho. Observe a palavra "shell". Quase qualquer comando do shell servirá. O comando de compilação pode conter marcadores. %f para o arquivo atual, %d para a pasta do arquivo atual e %n para o nome base do arquivo atual (nome do arquivo sem sufixo).

Comando de execução

- A terceira coluna nas "linhas não iniciais" pode conter um comando shell para execução em um terminal real no diretório de trabalho definido. O terminal é aberto como uma aba. O plugin tentará reutilizar a aba do terminal se o mesmo comando for executado e o aplicativo anterior tiver sido encerrado.

Na parte superior da aba Configurações do alvo, temos uma barra de ferramentas com um filtro de alvo e os seguintes botões:

- Compilar o alvo selecionado
- Compilar e executar o alvo selecionado
- Adicionar um novo alvo de compilação
- Criar um novo conjunto de alvos
- Copiar um comando ou conjunto de alvos
- Excluir o comando atual ou conjunto de alvos

#### Aba de saída

A aba Saída mostra a saída do console gerada pelo comando (de compilação) em execução. Se uma linha contiver o caminho de um arquivo, essa linha será clicável. Se a linha na saída também mostrar um erro ou aviso, a linha terá uma cor diferente.

Se a opção Adicionar erros e avisos ao diagnóstico estiver ativada na página de configurações do plugin nas configurações do Kate, os erros e avisos também serão adicionados à visualização de diagnóstico. Para navegar até o erro anterior na visualização de diagnóstico, pressione &Alt;&Shift;&Left;. Para navegar até o próximo erro, pressione &Alt;&Shift;&Right;.

### Estrutura do menu

Compilar Selecionar alvo...

- O filtro de seleção de alvos está focado na aba de configurações de alvo. Digitar um nome filtrará os alvos que não correspondem à string digitada. Também é possível usar as teclas de seta para navegar na árvore de alvos. Quando o alvo desejado for selecionado, pressionar Enter executará o alvo selecionado.

Compilar Compilar alvo selecionado

- Compila o último alvo selecionado. Se nenhum tiver sido selecionado, funciona como Selecionar alvo...

Compilar Compilar e executar alvo selecionado

- Compila o último alvo selecionado e executa o comando de execução após a compilação. O comando de compilação terminou com sucesso.

Compilar Compilar arquivo atual

- Tente compilar o arquivo atual procurando um comando em um possível arquivo compile_commands.json.

Compilar Parar

- Parar a compilação de um alvo.

Compilar Focar próxima aba à esquerda

- Foque na próxima aba do plugin de compilação à esquerda. Ou abre a visualização da ferramenta do plugin de compilação, se estiver oculta.

Compilar Focar próxima aba à direita

- Foque na próxima aba do plugin de compilação à direita. Ou abre a visualização da ferramenta do plugin de compilação, se estiver oculta.

Compilar Carregar alvos da pasta de compilação do CMake

- Abre a janela de arquivo e permite que o usuário selecione um CMakeCache.txt. Quando um arquivo é selecionado, o plugin gera comandos de compilação do CMake que podem ser executados na pasta de compilação para o projeto baseado em CMake.

### Agradecimentos e reconhecimento

O plugin Compilação do &kate; foi criado por Kåre Särs.

Agradecimento especial a Salma Sultana, participante do Google Code-In 2011, por escrever grande parte desta seção.

## Plugin de fechamento com exclusão/inclusão

### Introdução

Este plugin permite fechar um grupo de documentos com base em suas extensão e caminhos.

### Usando o plugin de fechamento com exclusão/inclusão

Supondo que você tenha esses documentos abertos no &kate;:

- /tmp/subfolder/test.h
- /tmp/test.cpp
- /tmp/test.txt

Em seguida, você tem as seguintes opções para fechar documentos, conforme exibido na captura de tela:

Fechar com exceção de

Use a caixa de seleção no último item da lista para ativar ou desativar uma caixa de diálogo de confirmação. A opção selecionada será aplicada para fechar ações.

### Estrutura do menu

Arquivo Fechar com exceção de

- Fecha todos os documentos abertos, exceto aqueles que correspondem ao caminho ou extensão de arquivo selecionado no submenu.

Arquivo Fechar os seguintes

- Fechar todos os documentos abertos que correspondem ao caminho ou extensão de arquivo selecionado no submenu.

## Plugin do seletor de cor

### Introdução

Este plugin adiciona uma pré-visualização/seletor de cor embutido no texto (por exemplo, `#FFFFFF`, `branco`).

Para carregar este plugin, abra a janela de configuração do &kate; em Configurações Configurar &kate;.... Em seguida, selecione Seletor de cor e feche a janela.

### Configuração

Na página de configurações do seletor de cor na configuração do &kate;, você pode configurar as seguintes opções de comportamento do plugin.

Mostrar prévia para nomes de cores conhecidos

- Se deve mostrar o seletor de cor para nomes de cor conhecidos (por exemplo, `azul-celeste`). Consulte esta página para obter a lista de cores.

Colocar a prévia após o texto da cor

- Indica se a pré-visualização embutida deve ser colocada após a cor do texto.

Correspondência de cor hexadecimal

- Aqui, você pode escolher a opção que melhor corresponde às cores usadas no seu código.

## Colchetes coloridos

### Introdução

O plugin de colchetes coloridos colore pares de colchetes correspondentes com cores diferentes para melhorar a legibilidade. No entanto, nem todos os colchetes são coloridos. Um colchete cujo parêntese de abertura ou fechamento correspondente não estiver visível será ignorado. Da mesma forma, um par de colchetes que for o único par de colchetes em uma linha não será colorido.

### Configuração

O plugin não oferece nenhuma opção de configuração.

## Plugin do CTags

### Introdução

CTags gera um arquivo de índice (ou tag) de objetos de idioma encontrado nos arquivos de origem que permite que esses itens sejam localizados rápida e facilmente usando esse plugin do &kate;.

Uma tag significa um objeto de idioma para o qual uma entrada de índice está disponível (ou, alternativamente, a entrada de índice criada para esse objeto).

A geração de tags é suportada para estas Linguagens de programação.

### Configuração

O plugin CTags usa dois arquivos de banco de dados diferentes para o índice.

Na página de configurações do CTags na configuração do &kate;, você pode adicionar ou remover diretórios contendo o código-fonte e regenerar os CTags comuns do banco de dados.

#### Index comum

Configurações do CTags
Configuração do banco de dados do CTags

Na parte inferior da página de configurações, você pode adaptar os Comandos do CTags.

Para mais informações sobre todas as opções disponíveis, leia o manual do CTags. Esta página de manual está disponível no &khelpcenter; e você também pode inserir a &URL; man:/ctags diretamente no &konqueror;

Clicar em Atualizar iniciará a indexação. Quando a indexação terminar, a caixa de diálogo será fechada.

#### Índice da sessão

Para configurar o índice da sessão, abra a visualização do CTags.

Alvo do index

- Nesta aba você pode adicionar ou remover diretórios que contêm o código-fonte gerar novamente, de forma manual, o banco de dados do CTags específico da sessão.

Banco de dados

- Configurações do banco de dados
  Configuração da sessão do banco de dados do CTags

  Seleciona outro arquivo do banco de dados do CTags, configura os comandos do CTags ou reverte para os comandos padrão.

### Usando o plugin do CTags

Você coloca o cursor do mouse sobre o objeto de linguagem de programação de seu interesse, como uma função, símbolo &etc; , em seguida, selecione uma das ações do CTags para pular para a linha e o arquivo em que o objeto é definido ou declarado.

Por padrão, as ações no menu CTags não possuem atalhos atribuídos. Use o Editor de atalhos de teclado para configurar seus próprios atalhos.

Como alternativa, use o campo de pesquisa na guia Pesquisa doCTags.

A inserção de caracteres no campo de pesquisa iniciará a pesquisa e exibiránomes correspondentes de objetos da linguagem, como funções, classes, símbolos &etc;junto com o tipo e o nome do arquivo.

Selecione um item na lista para saltar para a linha correspondente no arquivo fonte.

### Estrutura do menu

CTags pula um passo atrás

- Navegue para trás no histórico até a última tag visitada.

CTags Pesquisa Texto Atual

- Abre a guia Pesquisa na aba de visualização do CTags e mostra todos os objetos da linguagem que correspondem à seleção de texto atual na lista.

CTags Ir para declaração

- Se o cursor estiver em um objeto, isso abrirá o documento contendo a declaração correspondente, se necessário, ative sua visualização e coloque o cursor no início da declaração.

CTags Ir para definição

- Se o cursor estiver em um objeto, isso abrirá o documento contendo a declaração correspondente, se necessário, ative sua visualização e coloque o cursor no início da declaração.

## Plugin de prévia de documentos

### Introdução

O plugin permite uma prévia em tempo real do documento de texto atualmente editado e no formato final na barra lateral. Então, ao editar por ⪚ um texto em &Markdown; ou uma imagem &SVG;, o resultado é visível instantaneamente ao lado do texto de origem.

Para a exibição, o plugin usa o plugin do &kparts;, atualmente selecionado como o preferido para o tipo &MIME; do documento. Se lá não existir um plugin do &kparts; para esse tipo, nenhuma visualização é possível.

Para alterar o plugin preferido, abra o menu Associações de arquivos nas &systemsettings; e edite a Ordem de preferência dos serviços na aba Incorporação.

### Alguns plugins do &kparts; estão disponíveis

Tipo &MIME; | Plugin do &kparts;
Texto &Markdown; | KMarkdownWebViewPart ou OkularPart
Imagem &SVG; | SVGPart
Arquivos de interface do &Qt; | KUIViewerPart
Arquivos de grafos &DOT; | KGraphviewerPart

### Estrutura do menu

Exibir Áreas de ferramentas Exibir prévia

- Alterne a exibição da visualização prévia de documentos do &kate; em uma barra lateral.

### Interface

Os botões na parte superior da janela de visualização prévia fornecem estas ações:

- Bloqueie a visualização em um determinado documento. A seleção desta opção garante que, se mudar o foco para a visualização de outro documento na mesma janela do &kate;, a visualização não seguirá para esse documento, mas continue visualizando esse documento.

- Ativar ou desativar atualizações da visualização do conteúdo atual do documento.

- Atualizar manualmente a visualização do conteúdo do documento atual

- Um menu suspenso com ações do plugin do &kparts;

## Plugin seletor de documentos

### Estrutura do menu

&Ctrl; Visualizar Última visualização usada

&Ctrl;&Shift; Visualização Última visualização usada (Reverso)

- Abre uma lista com os últimos documentos visualizados:

  Últimos documentos visualizados

  Mantenha a tecla &Ctrl; pressionada e use a tecla para avançar a lista. Além disso, pressione a tecla &Shift; para inverter a direção.

  Mantenha o atalho &Ctrl; pressionado e pode usar as teclas &Up;, &Down;, Home ou End para navegar na lista. Pressionar teclas consecutivamente e percorrerá todos os itens. Alternando entre os documentos da lista. Se você soltar as teclas, a tela escolhida será exibida.

## Navegador do sistema de arquivos

O navegador do sistema de arquivos é um visualizador de pastas, permitindo abrir arquivos de uma pasta exibida no quadro atual.

### Estrutura do menu

Exibir Áreas de Ferramentas Mostrar o Navegador no sistema de arquivos

- Liga e desliga o navegador do sistema de arquivos do &kate;.

### Interface

De cima para baixo, o navegador do sistema de arquivos consiste nos seguintes elementos:

Uma barra de ferramentas

- Contém os botões de navegação padrão da ferramenta:

  Voltar

- Faz com que a visão de pastas, com o comando `cd`, vá para a pasta exibida anteriormente no histórico. Este botão ficará desligado, se não existir o item anterior.

Avançar

- Faz com que a visão de pastas, com o `cd`, mostre o próxima pasta do histórico. O botão é desabilitado, caso não exista a próxima pasta.

Favoritos

- Abre um submenu para editar ou adicionar favoritos e para adicionar uma nova pasta de favoritos.

Pasta de documento atual

- Este botão fará com que a visão de pastas, com o comando `cd` , vá para a pasta do documento atualmente ativo, se possível. Este botão é desabilitado se o documento ativo é um arquivo novo ou ainda não salvo, ou se a pasta no qual ele reside não pode ser definida.

Opções

- Visão abreviada

- Mostra apenas os nomes dos arquivos.

Visão detalhada

- Mostra o Nome, Data, Tamanho e Tipo dos arquivos.

Visão em árvore

- Como a visão abreviada, mas as pastas podem ser expandidas para ver seu conteúdo.

Visão em árvore detalhada

- Isto também permite que as pastas sejam expandidas, mas exibe as colunas adicionais disponíveis na visão detalhada.

Mostrar arquivos ocultos

- Mostra os arquivos normalmente ocultos pelo seu &OS;.

Sincronizar automaticamente com o documento atual

- Quando esta opções estiver ativa, o navegador do sistema de arquivos fará um `cd` automaticamente para a pasta do documento atualmente aberto na área de edição toda vez que ele mudar.

Um entrada de localização

- Isto exibe uma navegação no estilo 'trilha de pão' para a pasta atualmente aberta, como no &dolphin;. Você pode clicar em qualquer pasta para navegar nela, ou clicar em uma das setas à esquerda de uma pasta para selecionar qualquer pasta a partir dela. Você pode também selecionar a partir de sua lista de locais clicando no ícone mais à esquerda na navegação em 'trilha de pão', que exibe um ícone que representa seu Local atual.

  Você pode também clicar na trilha de pão para mudar para uma caixa de texto de onde pode digitar a localização de uma pasta para navegar. O campo da &URL; mantém uma lista dos campos introduzidos anteriormente. Para escolher um, utilize o botão da seta à direita do campo.

  O campo da &URL; tem o completamento automático das pastas. O método de completamento pode ser definido usando o menu do &RMB; do campo.

Uma visão de pastas

- Esta é uma janela de pastas padrão do &kde;.

Uma entrada de filtro

- A entrada de Filtro permite a você digitar um filtro para arquivos exibidos na visão de pastas. O filtro está usando padrões, que devem estar separados por espaço em branco. Exemplo: `*.cpp *.h *.moc`

  Para exibir todos os arquivos, digite um único asterisco - `*`.

  O campo do filtro salva os últimos 10 filtros inseridos entre sessões. Para usar um, clique no botão de setas à direita do campo e selecione o filtro desejado. Você poderá desativar o filtro se clicar no botão Limpar o texto à esquerda do botão de autocompletamento.

### Configuração

Este plugin pode ser configurado na página do Navegador do sistema de arquivos da configuração do &kate;.

Barra de ferramentas

- Configure os botões no navegador do sistema de arquivos, movendo os que deseja ativar para a lista de Ações selecionadas e ordenando-os com as setas ao lado da lista.

## A lista de documentos

### Introdução

A lista de documentos exibe todos os documentos atualmente abertos no &kate;. Os arquivos modificados terão um pequeno ícone disquete à esquerda para indicar esse estado.

Na parte superior da lista de documentos existe uma barra de ferramentas com os seguintes botões:

- Criar novo documento
- Abre um documento existente
- Documento anterior
- Próximo documento
- Salva o documento atual
- Salva o documento atual com outro nome

Por padrão, a lista de documentos é exibida no Modo árvore, que exibe a estrutura de pastas em torno de todos osdocumentos abertos. Também está disponível Modo lista, que mostra em uma lista simples todos os documentos abertos. Você pode alternar os modos clicando com o botão direito do mouse na lista e selecionar no menu Modo de exibição.

Se dois ou mais arquivos com o mesmo nome (localizados em pastas diferentes) são abertos no Modo lista, o nome do segundo aparecerá com o número (2). A dica de ferramenta para o arquivo será exibir seu nome completo, incluindo o caminho, permitindo que você escolha uma.

Para exibir um documento no quadro atualmente ativo, clique no nome do documento na lista.

O menu de contexto possui algumas ações comuns do menu Arquivo.

Além disso, existem ações do gerenciador de arquivos para renomear ou excluir o arquivo.Com Copiar localização, você pode copiar o caminho completo do documento para a área de transferência.

Você pode classificar a lista de algumas maneiras diferentes clicando com o botão direito do mouse na lista eselecionando no menu Classificar por. As opções são:

Nome do documento

- Lista os documentos em ordem alfabética por nome.

Caminho do documento

- Lista os documentos em ordem alfabética por seus caminhos.

Ordem de abertura

- Lista os documentos no ordem de abertura

A lista de documentos, por padrão, visualiza seu histórico sombreando asentradas para os documentos mais recentes com uma cor de fundo. Se odocumento foi editado, uma cor extra é misturada. O documento mais recentetem a cor mais forte, para que você possa encontrar facilmente os documentos em que estátrabalhando. Esse recurso pode ser desativado na configuração Documentos configuração da caixa de diálogo.

A localização padrão da lista de documentos no &kate; está àesquerda da área de edição.

### Estrutura do menu

&Alt;&Up; Exibir Documento anterior

- Abre o arquivo da lista de documentos exibido acima do aberto atualmente aberto.

&Alt;&Down; Exibir Próximo documento

- Abre o arquivo da lista de documentos exibido abaixo do aberto atualmente aberto.

Exibir Mostrar ativo

- Exibe o documento atualmente aberto na lista de documentos.

### Configuração

Sombreamento de fundo

- Essa sessão permite habilitar ou desabilitar o sombreamento de fundo da sua atividade recente, e escolher quais cores utilizar caso habilitado.

Organizar por

- Define como você quer organizar a lista de documentos. Isso também pode ser definido pelo menu &RMB; na lista de documentos.

Modo de visualização

- Isso fornece duas opções que afetam a exibição da ferramenta visão do documento.A opção Visão em árvore irá mostrar os documentosem uma árvore abaixo das pastas em que estão, enquanto a Visualização de lista exibirá uma lista simples de documentos.

Mostrar caminho completo

- Quando a visualização em árvore e esta opção estão ativadas, as entradas de pasta exibidas na visualização da ferramenta de documentos mostrarão o caminho completo do sistema de arquivos para a pasta, além do nome da pasta. Isso não tem efeito na visualização em lista.

Mostrar barra de ferramentas

- Quando a visualização em árvore e esta opção estão ativadas, uma barra de ferramentas com ações como Salvar é exibida acima da lista de documentos. Desmarque esta opção se a barra de ferramentas deve ser ocultada.

Mostrar botão de fechar

- Quando esta opção estiver ativada, o &kate; exibirá um botão de fechar para documentos abertos ao passar o cursor sobre eles.

## Plugin do &gdb;

### Introdução

O plugin &gdb; do &kate; fornece uma interface simples para qualquer depurador que suporte o Protocolo de Adaptador de Depurador. Em particular, isso inclui o GNU Project Debugger, também conhecido como GDB, conforme descrito aqui.

Recomenda-se alguma experiência anterior com o &gdb;. Para mais informações sobre a utilização do &gdb;, visite o site do &gdb;.

Você poderá ativar o plugin do &gdb; na seção plugins da configuração do &kate;.

Se você compilar com o &gcc;/`g++`, poderá querer usar o argumento da linha de comando ``-ggdb``.

Depois de efetuar estas preparações, abra o arquivo de código no &kate;, selecione o "perfil de depuração", insira a localização do executável na aba Configurações da área de Depuração e selecione a opção do menu Depuração Iniciar depuração para começar.

O "perfil de depuração" seleciona o servidor DAP a ser usado (por exemplo, GDB) e a forma de iniciar esse servidor. Um caso típico é o servidor iniciar um processo conforme especificado acima, mas ele também pode se conectar a um processo em execução (nesse caso, um PID deverá ser especificado em vez de um executável). Também podem existir outros modos específicos para a linguagem e o servidor DAP. Veja mais adiante para obter informações adicionais sobre o contexto e a configuração.

### Estrutura do menu e da barra de ferramentas

Todas estas opções estão disponíveis nos menus do &kate;, estando também muitas disponíveis na barra de Depuração.

Exibir Áreas de ferramentas Mostrar a área de depuração

- Mostra uma área de ferramentas que contém o resultado do &gdb;, a linha de comando usada pelo &gdb; e outras opções.

Exibir Áreas de ferramentas Mostrar locais e a pilha

- Mostra uma lista com todas as variáveis carregadas no momento, os seus valores e o backtrace do &gdb;.

Depurar Alvos

- Um submenu que contém uma lista de alvos (executáveis).

Depurar Iniciar depuração

- Inicia o &gdb; com um determinado alvo.

Depurar Matar / Parar depuração

- Para o &gdb;.

Depurar Reiniciar depuração

- Reinicia o &gdb;.

Depurar Comutar o ponto de parada

- Define um ponto de parada na posição atual do cursor.

Depurar Avançar para

- Executa a instrução atual (a chamada à função será depurada).

Depurar Avançar sobre

- Executa a instrução atual (a chamada à função não será depurada).

Depurar Sair de

- Prossegue a execução até que o programa em execução termine.

Depurar Mover o PC

- Move o contador do programa (execução seguinte).

Depurar Executar até ao cursor

- Executa o programa até que atinja a posição atual do cursor.

Depurar Continuar

- Ignora os pontos de parada e executa o programa até que termine (com sucesso ou não).

Depurar Imprimir o valor

- Imprime o valor da variável para onde aponta o cursor no momento.

Configurações Barras de ferramentas visíveis plugin do &gdb;

- Mostra a barra de depuração.

### Área de Depuração

A Área de Depuração consiste em várias páginas:

Resultado do &gdb;

- Contém o resultado do &gdb; e uma linha de comando também do &gdb;.

  A Página do Resultado A página do Resultado.

  A página do Resultado mostra o resultado de uma sessão de depuração.

Configurações

- Executável

- Localização do alvo (executável) para depuração.

Pasta de trabalho

- A pasta de trabalho conferida ao alvo.

Argumentos

- Os argumentos passados ao programa.

Manter o foco

- Mantém a linha de comando do &gdb; em primeiro plano.

Direcionar a E/S

- Abre uma nova página de E/S na Janela de Depuração, onde poderá ver os resultados e inserir dados no programa em execução.

O diálogo de configurações O diálogo de configurações

A janela de Configurações mostra as definições de uma sessão de depuração.

E/S

- Contém uma área que mostra os resultados do programa em execução e uma linha de comando onde pode inserir dados para ele.

  A Página de E/S A página de E/S.

  A página do E/S mostra o resultado de um programa de testes simples.

### Pilha de chamadas e variáveis locais

A área da Pilha de chamadas contém uma lista dos registros de chamadas que são devolvidos pelo &gdb;.

A Área de Registros de Chamadas do &gdb; A área de ferramentas para o registro de chamadas.

A área da Pilha de chamadas do plugin do &gdb;.

A área de Locais contém uma lista com todas as variáveis do programa carregadas no momento, bem como os seus valores correspondentes.

A Área de Variáveis Locais do &gdb; A área de ferramentas de Variáveis Locais.

A área de Variáveis locais do plugin do &gdb;.

### Agradecimentos e reconhecimento

Agradecimentos especiais ao participante Martin Gergov do Google Code-In 2011 pela escrita de grande parte desta seção.

### Configuração

A página de configuração do plugin define os "perfis de depuração" que podem ser selecionados. A configuração padrão (JSON) é exibida lá e pode ser "sobreposta" por uma configuração semelhante fornecida pelo usuário. Um exemplo de trecho é o seguinte:

    {
        "dap": {
            "debugpy": {
                "url": "https://github.com/microsoft/debugpy",
                "run": {
                    "command": ["python", "-m", "debugpy", "--listen", "${#run.port}", "--wait-for-client"],
                    "port": 0,
                    "supportsSourceRequest": false
                },
                "configurations": {
                    "launch": {
                        "commandArgs": ["${file}", "${args|list}"],
                        "request": {
                            "command": "attach",
                            "stopOnEntry": true,
                            "redirectOutput": true
                        }
                    },
                    "attach": {
                        "commandArgs": ["--pid", "${pid}"],
                        "request": {
                            "command": "attach",
                            "stopOnEntry": true,
                            "redirectOutput": true
                        }
                    },
            },
            "gdb": {
                "url": "gdb",
                "run": {
                    "command": [
                        "gdb",
                        "-i",
                        "dap"
                    ],
                    "redirectStderr": true,
                    "redirectStdout": true,
                    "supportsSourceRequest": true
                },
                "configurations": {
                    "launch (debug)": {
                        "request": {
                            "command": "launch",
                            "mode": "debug",
                            "program": "${file}",
                            "args": "${args|list}",
                            "cwd": "${workdir}"
                        }
                    }
                }
            }
        }
    }

Cada uma das entradas em `configurations` é combinada com os dados de `run` e forma um "perfil". Isso especifica o servidor DAP a ser iniciado, juntamente com seus argumentos, sendo estes específicos para o perfil (`commandArgs`). As outras partes especificam a solicitação do protocolo DAP (`launch` ou `attach`), juntamente com extensões específicas do DAP.

É claro que o servidor especificado deve estar instalado (e normalmente também estar no `PATH` para execução adequada).

Várias etapas de sobreposição/fusão são aplicadas; a configuração do usuário (carregada de um arquivo) sobrepõe a configuração padrão (interna), e a entrada "dap" na configuração do projeto `.kateproject`, por sua vez, sobrepõe as demais.

#### Configuração do ambiente de execução

Mais informações e detalhes podem ser encontrados na seção Ambiente de execução do cliente LSP abaixo. Mas basta dizer aqui que pode ser necessário executar o processo depurado (e o servidor DAP) em um "ambiente especial", seja definido por variáveis ​​de ambiente ou por algum contêiner (que forneça as dependências e circunstâncias necessárias para a execução adequada).

Semelhante ao exemplo na seção referenciada, a seguinte configuração pode ser fornecida em um `.kateproject`.

    {
        // isto pode também ser uma array de objetos
        "exec": {
            "hostname": "foobar"
            // o comando pode também ser uma array de string
            "prefix": "podman exec -i foobarcontainer",
            "mapRemoteRoot": true,
            "pathMappings": [
                // ambas as formas a seguir são possíveis
                // uma alternativa mais automágica também existe, veja a seção de referência
                [ "/dir/on/host", "/mounted/in/container" ]
                { "localRoot": "/local/dir", "remoteRoot": "/remote/dir" }
            ]
        },
        "dap": {
            "debugpy": {
                "run": {
                    // nesta seção, aplica a todas as configurações
                    // isto irá corresponder/juntar com o objeto acima
                    "exec": { "hostname": "foobar" },
                    // se o servidor está conectado,
                    // opcionalmente especificar explicitamente a porta (que é adequada parapublicação/encaminhamento)
                    "port": 5678,
                    // o servidor pode então também ter que aceitar mais do que o localhost
                    "host": "0.0.0.0"
                }
            }
        }
    }

A seção referenciada deve ser consultada para obter detalhes, mas, em essência, o `prefixo` será adicionado antes da linha de comando do servidor DAP especificada em outro local. O efeito é que o servidor é executado dentro do contêiner especificado e, por sua vez, também o processo iniciado. O `pathMapping` organiza a transformação de caminhos de arquivo entre a visualização do editor e a visualização do servidor DAP (contêiner), por exemplo, ao lidar com a definição de pontos de interrupção ou o tratamento de rastreamentos de pilha relatados. Observe que esse mapeamento é opcional e pode ou não ser útil. Ao lidar com código C/C++ compilado no "host", as informações do símbolo fazem referência a arquivos de origem no host que não existem no outro ambiente. No entanto, em outras circunstâncias de script (por exemplo, Python), os arquivos de tempo de execução reais são referenciados (no outro ambiente).

É evidente que o seguinte deve ser levado em consideração.

- O servidor DAP deve estar presente no ambiente/container, que deve ser configurado para suportar a operação adequada do depurador (portanto, se necessário, com privilégios e capacidades).

- A comunicação entre o editor e o DAP deve ser possível. No caso de um contêiner, este último deve usar a rede do host ou fornecer uma porta mapeada/publicada adequada, juntamente com o trecho de configuração correspondente, como no exemplo acima (já que uma porta selecionada automaticamente, no caso da porta 0, não funcionaria).

- Um executável/PID específico deve estar na perspectiva de "contêiner", assim como quaisquer argumentos (executável depurado).

Além disso, como no caso do LSP, algumas variáveis ​​de ambiente são definidas; `KATE_EXEC_PLUGIN` é definida como `dap`, `KATE_EXEC_SERVER` é definida como o tipo de depurador/linguagem (por exemplo, `python`) e `KATE_EXEC_PROFILE` é definida como a entrada de configuração (por exemplo, `launch`).

## Plugin de projeto

### Introdução

A ideia básica do plugin de projeto é ter uma lista estruturada de arquivos pertencentes ao projeto com as seguintes propriedades:

1. Fornecer uma visualização estruturada dos arquivos

2. Tornar fácil e rápido abrir e mudar projetos

3. Suporte a busca e substituição para um projeto

4. Oferecer um autocompletar simples

5. Tornar simples de abrir rapidamente arquivos em um projeto

6. Suporte para compilar o projeto

### Visualização estruturada dos arquivos

Após o plugin de projeto ser carregado na página de configuração do &kate;, abra um arquivo em um projeto e uma barra lateral aparecerá listando todos os projetos, bem como os arquivos do projeto, da seguinte forma:

Visualização do projeto

Como você pode ver, o projeto atualmente ativo é Kate, e seu conteúdo está listado na visualização em árvore. Clicar nos arquivos na visualização em árvore abre o arquivo no editor. Além disso, um menu de contexto é fornecido com o qual você pode abrir arquivos com outros aplicativos, como um arquivo `.ui` com o Qt Designer.

Você pode filtrar os itens digitando parte do nome que deseja buscar na barra de busca localizada a baixo da lista.

### Alternando entre projetos

A ideia é que você nunca precise abrir um projeto manualmente, isso nem sequer é suportado. Portanto, o que acontece quando você abre um arquivo é que o plugin de projeto verifica rapidamente a pasta e suas subpastas em busca de um arquivo `.kateproject`. Se encontrado, o projeto é carregado automaticamente.

Além disso, se você abrir outro documento no &kate;, que pertence a outro projeto, o plugin de projeto alterna automaticamente para o projeto atual. Assim, intuitivamente, o projeto correto está sempre ativo. Claro, você também pode alternar o projeto ativo usando a caixa de combinação.

### Pesquisar e substituir nos projetos

O &kate; possui um plugin de busca e substituição que aparece na barra lateral inferior. Se um projeto estiver carregado, abra a barra lateral de busca e substituição e mude para o modo para buscar e substituir no projeto atual:

Pesquisar nos projetos

### Simples autocompletar

Com o conhecimento de todos os arquivos pertencentes a um projeto, o plugin de projeto fornece recursos simples de autocompletar baseados em CTags. Se um projeto for aberto inicialmente, o CTags analisa todos os arquivos do projeto em uma thread em segundo plano e salva as informações do CTags em `/tmp`. Este arquivo é então usado para preencher o popup de autocompletar no &kate;.

Em contraste, sem esse recurso de autocompletar, o &kate; só consegue exibir itens de autocompletar com base nas palavras do arquivo atual. Portanto, o recurso de autocompletar fornecido pelo plugin de projeto é muito mais poderoso.

Completamento em projetos

Se o CTags estiver faltando, um pop-up discreto avisará sobre esse problema. Também é importante notar que o arquivo CTags em `/tmp` é limpo quando o &kate; é encerrado, portanto, o plugin não polui nenhuma pasta com arquivos indesejados.

### Suporte para compilar um projeto

Outra funcionalidade é o suporte ao Plugin de compilar, para que ele seja configurado automaticamente corretamente.

### Criando projetos

#### Carregando projetos automaticamente

O plugin de projeto possui um recurso de carregamento automático. Você pode ler a lista de arquivos do sistema de controle de versão. Para isso, o carregamento automático para o respectivo sistema de controle de versão precisa ser ativado nas configurações (ativado por padrão):

Configuração do plugin de projeto

#### Criando projetos manualmente

Basta criar um arquivo `.kateproject` na pasta raiz do projeto. Por exemplo, o arquivo Kate`.kateproject` teria a seguinte aparência:

    {
      "name": "Kate",
      "files": [
        {
          "git": 1
        }
      ]
    }

O conteúdo do arquivo está escrito em sintaxe &JSON;. O nome do projeto é Kate, e os arquivos contidos nele devem ser lidos do &git;.

Além do `git`, também são suportados o Subversion através do `svn` e o Mercurial através do `hg`. Se você não quiser ler arquivos de um sistema de controle de versão, você pode simplesmente invocar o Kate a partir da linha de comando como:

    kate /caminho/para/pasta

ou você pode instruí-lo a carregar arquivos recursivamente de diretórios da seguinte forma:

    {
      "name": "Kate",
      "files": [
        {
          "directory": "kate",
          "filters": [
            "*.cpp",
            "*.h",
            "*.ui",
            "CMakeLists.txt",
            "Find*.cmake"
          ],
          "recursive": 1,
          "hidden": 1
        }
      ],
      "exclude_patterns" : [
        "^build/.*"
      ]
    }

Aqui, subpastas e filtros definem o que faz parte do projeto. Você também pode misturar controle de versão e arquivos com base em filtros. Arquivos ocultos não serão recuperados se a opção `"hidden"` for 0. `"exclude_patterns"` é uma lista de padrões regex que podem ser usados ​​para excluir pastas e arquivos da árvore do projeto. Neste exemplo, todos os arquivos e pastas em um diretório `build` a partir da raiz serão excluídos.

Se você quiser adicionar suporte para compilação, pode escrever um `.kateproject` assim:

    {
      "name": "Kate",
      "files": [
        {
          "git": 1
        }
      ],
      "build": {
        "directory": "build",
        "build": "make all",
        "clean": "make clean",
        "install": "make install",
        "targets": [
          {
            "name": "all",
            "build_cmd": "ninja"
            "run_cmd": "./bin/kate"
          },
          {
            "name": "kate",
            "build_cmd": "ninja kate-bin"
          }
        ]
      }
    }

Os alvos especificados acima aparecerão então no Plugin Compilar em "Alvos do plugin de projeto". Se o array `"targets"` for especificado, então `"build"`, `"clean"` e `"install"` serão ignorados. Cada elemento no array especifica um alvo. `"name"` é o nome do alvo, `"build_cmd"` será usado para compilar o alvo, `"run_cmd"` será usado para executar o alvo. O mais importante de tudo é `"directory"`, onde os comandos serão executados.

Caso você tenha um arquivo `.kateproject` rastreado por um sistema de controle de versão, mas precise ajustar a configuração para um espaço de trabalho específico, você pode salvar essas alterações em um arquivo separado chamado `.kateproject.local`. O conteúdo deste arquivo terá precedência sobre `.kateproject`.

### Projeto atual

Usando &Alt;1 Projetos Ir para você pode abrir a visualização Projeto atual na parte inferior da janela do editor com quatro abas:

Projeto atual

Painel do terminal

- Um Emulador de terminal iniciando na pasta raiz do projeto.

Índice de código

- Ao inserir caracteres na barra de pesquisa, a busca será iniciada e serão exibidos os nomes correspondentes de funções, classes, símbolos &etc; juntamente com o tipo, nome do arquivo e número da linha.

  Selecione um item na lista para saltar para a linha correspondente no arquivo fonte.

Análise de código

- Clique em Iniciar análise para executar uma análise estática de código para os arquivos C e C++ usando `cppcheck` e gerar um relatório mostrando o nome do arquivo, o número da linha, a gravidade (estilo, aviso etc.) e o problema encontrado.

  Selecione um item na lista para saltar para a linha correspondente no arquivo fonte.

Notas

- O texto inserido nesta aba será salvo no arquivo `.kateproject.notes`.

### O menu de projetos

O menu Projetos permite alternar entre os projetos atualmente abertos. Ele é exibido pelo plugin de projeto.

&Ctrl;&Alt;&Left; Projetos Voltar

- Alterna para o projeto anterior.

&Ctrl;&Alt;&Right; Projetos Próximo

- Alterna para o projeto seguinte.

&Alt;1 Projetos Ir para

- Abra a visualização Projeto atual na parte inferior da janela do editor.

## Plugin do cliente LSP

O plugin do cliente LSP fornece muitos funcionalidades de linguagem, como preenchimento automático de código, navegação de código ou localização de referências com base no Protocolo do Servidor de Linguagem.

Depois de ativar o cliente LSP na página do plugin, uma nova página chamada Cliente LSP aparecerá na sua janela de configuração do &kate;.

### Estrutura do menu

Se apropriado, um comando LSP correspondente também é mencionado na explicação abaixo, cuja documentação pode então fornecer informações adicionais e interpretação, embora possa variar dependendo da linguagem específica. A expressão 'símbolo atual' refere-se ao símbolo correspondente à posição atual do cursor, conforme determinado pela linguagem e pela implementação do servidor.

Cliente LSP Ir para definição

- [textDocument/definition] Vai para a definição do símbolo atual.

Cliente LSP Ir para declaração

- [textDocument/declaration] Vai para a declaração do símbolo atual.

Cliente LSP Ir para definição de tipo

- [textDocument/typeDefinition] Vai para a definição de tipo do símbolo atual.

Cliente LSP Encontrar referências

- [textDocument/references] Encontra referências para o símbolo atual.

Cliente LSP Encontrar implementações

- [textDocument/implementation] Encontra implementações do símbolo atual.

Cliente LSP Realce

- [textDocument/documentHighlight] Realça as referências de símbolos atuais no documento atual.

Cliente LSP Client Sobre

- [textDocument/hover] Ativa a exibição de informações ao passar o cursor sobre o símbolo atual.

Cliente LSP Formato

- [textDocument/formatting] [textDocument/rangeFormatting] Formata o documento atual ou a seleção atual.

Cliente LSP Renomear

- [textDocument/rename] Renomeia o símbolo atual.

Cliente LSP Correção rápida

- [textDocument/codeAction, workspace/executeCommand] Calcula e aplica uma correção rápida para um diagnóstico na posição (ou linha) atual.

Cliente LSP Mostrar documentação de complementação da seleção

- Mostra a documentação para o item selecionado na lista de completamento.

Cliente LSP Ativar ajuda de assinatura com completamento automático

- Mostra também a ajuda para assinatura na lista de completamento.

Cliente LSP Incluir declaração nas referências

- Solicita a inclusão da declaração de um símbolo ao solicitar referências.

Cliente LSP Adiciona parênteses com a função de completamento

- Adiciona automaticamente um par de parênteses após o completamento de uma função.

Cliente LSP Mostrar informações sobre

- Mostra informações ao passar o cursor do mouse sobre o elemento. Independentemente dessa configuração, a solicitação sempre poderá ser iniciada manualmente.

Cliente LSP Formatar ao digitar

- [document/onTypeFormatting] Formata partes do documento ao digitar determinados caracteres de gatilho. Por exemplo, isso pode aplicar recuo em novas linhas, ou conforme determinado pelo Servidor LSP. Observe que os scripts de recuo do editor podem tentar fazer o mesmo (dependendo do modo) e, portanto, pode não ser recomendável ter ambos ativados ao mesmo tempo.

Cliente LSP Sincronização de documento incremental

- Envia edições parciais do documento para atualizar o servidor em vez do documento de texto inteiro (se suportado).

Cliente LSP Destacar localização ir para

- Fornece uma indicação visual temporária após executar um comando "goto" para um local (de definição, declaração, etc.).

Cliente LSP Mostrar notificações de diagnósticos

- [textDocument/publishDiagnostics] Processa e exibe notificações de diagnóstico enviadas pelo servidor.

Cliente LSP Mostrar destaques de diagnósticos

- Adiciona destaques de texto para os intervalos indicados nos diagnósticos.

Cliente LSP Mostrar marcas de diagnóstico

- Adiciona marcas de documento para as linhas indicadas no diagnóstico.

Cliente LSP Alternar para aba de diagnóstico

- Acessa a aba de diagnóstico na visualização de ferramentas do plugin.

Cliente LSP Fechar todas as abas que não sejam de diagnóstico

- Fecha todas as abas que não sejam de diagnóstico (⪚ referências) na visualização da ferramentas do plugin.

Cliente LSP Reiniciar o servidor LSP

- Reinicia o servidor LSP do documento atual.

Cliente LSP Reiniciar todos os servidores LSP

- Para todos os servidores LSP, que serão então (re)iniciados conforme necessário.

### Suporte ao símbolo de "goto"

O cliente LSP pode ajudá-lo a navegar até qualquer símbolo em seu projeto ou arquivo atual. Para navegar até qualquer símbolo no arquivo, use a ferramenta "Contorno de símbolo do cliente LSP" na borda direita do Kate. Esta ferramenta lista todos os símbolos encontrados pelo servidor no documento atual.

#### Configurando o contorno de símbolo do cliente LSP

Por padrão, os símbolos são classificados de acordo com sua ocorrência no documento, mas você pode alterar a classificação para ordem alfabética. Para isso, clique com o botão direito do mouse na janela de ferramentas e marque "Classificar alfabeticamente".

A visualização de ferramentas mostra os símbolos no modo de árvore por padrão, porém você pode alterá-la para uma lista usando o menu de contexto.

#### Suporte ao símbolo "goto" global

Para ir para qualquer símbolo em seu projeto, você pode abrir a caixa de diálogo do símbolo "Ir para" usando &Ctrl;&Alt;p. A caixa de diálogo está vazia quando é aberta, mas assim que você digita algo, ela começará a mostrar os símbolos correspondentes. A qualidade das correspondências, bem como os recursos de filtragem, dependem do servidor que você usa. Por exemplo, o clangd oferece suporte à filtragem aproximada, mas alguns outros servidores podem não oferecer.

### Outras funcionalidades

O comando de troca de cabeçalho de origem do Clangd é suportado. Para trocar o cabeçalho de origem em um projeto C ou C++, use a opção "Trocar cabeçalho de origem" no menu de contexto ou o atalho F12.

Você pode ir rapidamente para um símbolo colocando o mouse sobre ele e pressionando &Ctrl; + botão esquerdo do mouse.

### Configuração

A página de configuração do plugin permite, em sua maioria, a configuração persistente de alguns dos itens de menu acima. No entanto, há uma entrada adicional para especificar o arquivo de configuração do servidor. Este é um arquivo JSON que pode ser usado para especificar o servidor LSP a ser iniciado (e, em seguida, para se comunicar com ele via stdin/stdout). Para maior conveniência, algumas configurações padrão estão incluídas, as quais podem ser inspecionadas na página de configuração do plugin. Para auxiliar na explicação abaixo, um trecho dessa configuração é fornecido aqui:

    {
        "servers": {
            "bibtex": {
                "use": "latex",
                "highlightingModeRegex": "^BibTeX$"
            },
            "c": {
                "command": ["clangd", "-log=error", "--background-index"],
                "commandDebug": ["clangd", "-log=verbose", "--background-index"],
                "url": "https://clang.llvm.org/extra/clangd/",
                "highlightingModeRegex": "^(C|ANSI C89|Objective-C)$"
            },
            "cpp": {
                "use": "c",
                "highlightingModeRegex": "^(C\\+\\+|ISO C\\+\\+|Objective-C\\+\\+)$"
            },
            "d": {
                "command": ["dls", "--stdio"],
                "url": "https://github.com/d-language-server/dls",
                "highlightingModeRegex": "^D$"
            },
            "fortran": {
                "command": ["fortls"],
                "rootIndicationFileNames": [".fortls"],
                "url": "https://github.com/hansec/fortran-language-server",
                "highlightingModeRegex": "^Fortran.*$"
            },
            "javascript": {
                "command": ["typescript-language-server", "--stdio"],
                "rootIndicationFileNames": ["package.json", "package-lock.json"],
                "url": "https://github.com/theia-ide/typescript-language-server",
                "highlightingModeRegex": "^JavaScript.*$",
                "documentLanguageId": false
            },
            "latex": {
                "command": ["texlab"],
                "url": "https://texlab.netlify.com/",
                "highlightingModeRegex": "^LaTeX$"
            },
            "go": {
                "command": ["go-langserver"],
                "commandDebug": ["go-langserver", "-trace"],
                "url": "https://github.com/sourcegraph/go-langserver",
                "highlightingModeRegex": "^Go$"
            },
            "python": {
                "command": ["python3", "-m", "pyls", "--check-parent-process"],
                "url": "https://github.com/palantir/python-language-server",
                "highlightingModeRegex": "^Python$"
            },
            "rust": {
                "command": ["rls"],
                "path": ["%{ENV:HOME}/.cargo/bin", "%{ENV:USERPROFILE}/.cargo/bin"],
                "rootIndicationFileNames": ["Cargo.lock", "Cargo.toml"],
                "url": "https://github.com/rust-lang/rls",
                "highlightingModeRegex": "^Rust$"
            },
            "ocaml": {
                "command": ["ocamlmerlin-lsp"],
                "url": "https://github.com/ocaml/merlin",
                "highlightingModeRegex": "^Objective Caml.*$"
            }
        }
    }

Observe que cada "command" pode ser uma matriz ou uma string (nesse caso, ele é dividido em uma matriz). Além disso, uma entrada "global" de nível superior (ao lado de "server") também é considerada (veja mais abaixo). O binário especificado é procurado da maneira usual, por exemplo, usando `PATH`. Se ele estiver instalado em um local personalizado, este último pode precisar ser estendido. Ou, alternativamente, um link simbólico ou um script wrapper pode ser usado em um local que esteja dentro do `PATH` usual. Como ilustrado acima, também é possível especificar um "caminho" que será procurado após os locais padrão.

Todas as entradas em "command", "root" e "path" estão sujeitas à expansão de variáveis.

A expressão regular "highlightingModeRegex" é usada para mapear o modo de realce usado pelo &kate; ao ID da linguagem do servidor. Se nenhuma expressão regular for fornecida, o próprio ID da linguagem será usado. Se uma entrada "documentLanguageId" for definida como falsa, nenhum ID de linguagem será fornecido ao servidor ao abrir o documento. Isso pode apresentar melhores resultados para alguns servidores que são mais precisos na determinação do tipo de documento do que fazê-lo com base em um modo do Kate.

A partir do exemplo acima, a ideia principal provavelmente está clara. Além disso, cada objeto de entrada do servidor também pode ter uma entrada "initializationOptions", que é passada para o servidor como parte do método 'initialize'. Se presente, uma entrada "settings" é passada para o servidor por meio da notificação 'workspace/didChangeConfiguration'. "completionTriggerCharacters" ou "signatureTriggerCharacters" podem ser especificados como um objeto JSON com os membros de string "exclude" e/ou "include". Estes serão usados ​​para excluir ou adicionar caracteres ao conjunto de gatilhos correspondente, conforme fornecido pelo servidor.

São aplicadas várias etapas de sobreposição/fusão;

- configuração do usuário (carregada de um arquivo) substitui a configuração padrão (interna)

- entrada "lspclient" na configuração do projeto `.kateproject` substitui a acima

- a entrada "global" resultante é usada para complementar (não substituir) qualquer entrada do servidor

Uma instância de servidor é usada para cada combinação (raiz, tipo de servidor). Se "root" for especificado como um caminho absoluto, ele será usado como está; caso contrário, será relativo ao projectBase (conforme determinado pelo plugin de projeto), se aplicável, ou, caso contrário, relativo ao diretório do documento. Se não for especificado e "rootIndicationFileNames" for uma matriz de nomes de arquivos, um diretório pai do documento atual que contenha tal arquivo será selecionado. Alternativamente, se "root" não for especificado e "rootIndicationFilePatterns" for uma matriz de padrões de arquivo, um diretório pai do documento atual que corresponda ao padrão de arquivo será selecionado. Como último recurso, o diretório inicial é selecionado como "root". Para qualquer documento, o "root" resultante determina se uma instância separada é necessária ou não. Nesse caso, o "root" é passado como rootUri/rootPath.

Em geral, recomenda-se deixar o diretório raiz sem especificação, pois não é tão importante para um servidor (embora isso possa variar). Menos instâncias de servidor são obviamente mais eficientes e também têm uma visão mais ampla do que a visão de muitas instâncias separadas.

Como mencionado acima, várias entradas estão sujeitas à expansão de variáveis. Uma aplicação adequada disso, combinada com abordagens de "script wrapper", permite a personalização para uma grande variedade de circunstâncias. Por exemplo, considere um cenário de desenvolvimento em Python que consiste em múltiplos projetos (por exemplo, repositórios Git), cada um com sua própria configuração de ambiente virtual. Usando a configuração padrão, o servidor de linguagem Python não reconhecerá o ambiente virtual. No entanto, isso pode ser corrigido com a seguinte abordagem. Primeiro, o seguinte fragmento pode ser inserido nas "Configurações do servidor do usuário" do plugin LSPClient:

    {
            "servers":
            {
                    "python":
                    {
                            "command": ["pylsp_in_env", "%{Project:NativePath}"],
                            "root": "."
                    }
            }
    }

A entrada raiz acima é relativa ao diretório do projeto e garante que um servidor de linguagem separado seja iniciado para cada projeto, o que é necessário neste caso, pois cada um tem um ambiente virtual distinto.

`pylsp_in_env` é um pequeno "script auxiliar" que deve ser colocado em `PATH` com o seguinte conteúdo (a ser ajustado):

    #!/bin/bash
    cd $1
    # executa o servidor (python-lsp-server) dentro de um virtualenv
    # (i.e. com configuração de variáveis virtualenv)
    # então ative o virtualenv
    source XYZ
    # disponibilidade do servidor ou os argumentos podem variar
    exec meuservidor

Este é apenas um exemplo de um padrão mais geral que pode ser tratado de forma um pouco mais confortável, conforme descrito na seção Ambiente de execução abaixo.

#### Configurações do servidor LSP

Cada servidor LSP específico possui sua própria forma de personalização e pode usar meios específicos de linguagem/ferramenta para configuração, ⪚ `tox.ini` (entre outros, para Python) ou `.clang-format` para formato no estilo C++. Essa configuração também pode ser usada por outras ferramentas (não LSP), como tox ou clang-format. Além disso, alguns servidores LSP também carregam configurações de arquivos personalizados (⪚ `.ccls`). Ademais, a configuração personalizada do servidor também pode ser passada pelo LSP (protocolo), conforme mencionado nas entradas "initializationOptions" e "settings" na configuração do servidor.

Como são aplicados vários níveis de sobrescrita/fusão, o exemplo a seguir de configuração de cliente especificada pelo usuário ajusta algumas configurações do servidor de linguagem Python.

    {
        "servers": {
            "python": {
                "settings": {
                    "pyls": {
                        "plugins": {
                            "pylint": {
                                "enable": true
                            }
                        }
                    }
                }
            }
        }
    }

Infelizmente, a configuração/personalização do servidor LSP muitas vezes não é tão bem documentada, de forma que apenas a análise do código-fonte revela as abordagens de configuração e o conjunto de opções disponíveis. Em particular, o servidor do exemplo acima suporta muito mais opções em "configurações". Consulte a documentação de outro cliente LSP para vários outros exemplos de servidores de linguagem e configurações correspondentes, que podem ser facilmente transformadas na configuração &JSON; usada aqui e descrita acima.

#### Formatar o servidor LSP ao salvar

Você pode ativar a opção "formatar ao salvar" nas configurações do LSP, na janela de configuração.

#### Supressão de diagnóstico de servidor LSP

Pode acontecer de serem relatados diagnósticos que não sejam muito úteis. Isso pode ser bastante trabalhoso, especialmente se houver muitos (frequentemente do mesmo tipo). Em alguns casos, isso pode ser ajustado por meios específicos da linguagem (servidor). Por exemplo, o mecanismo de configuração do clangd permite o ajuste de alguns aspectos dos diagnósticos. Em geral, no entanto, pode nem sempre ser evidente como fazer isso, ou pode até não ser possível da maneira desejada devido a limitações ou bugs do servidor.

Assim, o plugin suporta a supressão de diagnósticos semelhante, por exemplo, às supressões do Valgrind. A configuração mais detalhada pode ser fornecida em uma chave "suppressions" na configuração &JSON; (mesclada).

    {
        "servers": {
            "c": {
                "suppressions": {
                    "rulename": ["filename", "foo"],
                    "clang_pointer": ["", "clang-tidy", "clear_pointer"],
                }
            }
        }
    }

Cada regra (válida) tem um nome arbitrário e é definida por uma matriz de comprimento 2 ou 3 que fornece uma expressão regular para corresponder ao nome do arquivo (completo), uma expressão regular para corresponder ao diagnóstico (texto) e uma expressão regular opcional que corresponde ao intervalo do código-fonte do texto ao qual o diagnóstico se aplica.

Além da configuração detalhada acima, o menu de contexto na aba de diagnósticos também permite adicionar/remover supressões que correspondam exatamente a um diagnóstico específico (texto), seja globalmente (qualquer arquivo) ou localmente (o arquivo específico em questão). Essas supressões são armazenadas e carregadas da configuração da sessão.

#### Solução de problemas com o servidor LSP

Uma coisa é descrever como configurar um servidor LSP (personalizado) para qualquer linguagem específica, outra é conseguir que o servidor funcione sem problemas. Normalmente, felizmente, este último é o caso mais comum. Às vezes, porém, podem surgir problemas devido a alguma configuração incorreta "boba" ou a um problema mais fundamental com o próprio servidor. Este último pode se manifestar tipicamente como algumas tentativas de iniciar o servidor, conforme relatado na aba Saída. Esta última, no entanto, destina-se apenas a transmitir mensagens ou progresso de alto nível, e não a fornecer diagnósticos detalhados, e muito menos para o que é, na verdade, outro processo (o servidor LSP).

A maneira usual de diagnosticar isso é adicionar alguma(s) flag(s) ao comando de inicialização (do servidor de linguagem) que habilite(m) o registro (adicional) em algum arquivo ou no erro padrão, caso isso não ocorra por padrão. Se o &kate; for iniciado na linha de comando, então poderemos obter mais informações sobre o que pode estar dando errado.

Também pode ser informativo examinar a troca de mensagens do protocolo entre o cliente LSP do &kate; e o servidor LSP. Novamente, este último geralmente possui maneiras de rastrear isso. O cliente LSP também fornece rastreamento de depuração adicional (para stderr) quando o &kate; é invocado com a seguinte opção `LSPCLIENT_DEBUG=1` e devidamente `exportado`.

#### Configuração do ambiente de execução

O exemplo de virtualenv em Python acima é apenas um exemplo de um "ambiente de execução" que opera de forma distinta e separada do ambiente usual do host. Isso pode ser alcançado por meio de diferentes configurações de variáveis ​​(por exemplo, virtualenv), ou uma configuração (s)chroot (alternando para outro diretório como novo root), um contêiner (por exemplo, podman, docker) ou uma sessão ssh para outro host. Em cada caso, o "outro ambiente" é definido por um "prefixo de execução". Ou seja, algum programa pode ser invocado/executado no outro ambiente por meio de um "prefixo" (um programa e argumentos) anexado à invocação pretendida. Por exemplo, `podman exec -i nome_do_contêiner` ou `ssh usuário@host`.

Em particular, como no exemplo anterior do virtualenv, pode-se optar/precisar executar um servidor LSP em um ambiente separado (por exemplo, um contêiner com todas as dependências necessárias para algum projeto). A abordagem "manual" descrita acima tem a desvantagem de substituir a linha de comando padrão do LSP, que precisa ser especificada e duplicada novamente no script wrapper. Além disso, em alguns dos outros exemplos mencionados acima, o "path namespace" do host (como visto pelo editor) pode ser diferente do do ambiente. Para lidar com essas questões de forma mais sistemática (do que uma abordagem "personalizada"), algumas configurações adicionais podem ser especificadas.

Por exemplo, o seguinte pode ser especificado em uma configuração `.kateproject`. Obviamente, os comentários "falsos" não devem ser incluídos.

    {
        // isto pode ser uma array de objetos
        "exec": {
            "hostname": "foobar"
            // o comando também pode ser uma array de string
            "prefix": "podman exec -i foobarcontainer",
            "mapRemoteRoot": true,
            "pathMappings": [
                // todas as formas a seguir são possíveis
                // um alternativa mais automágica existe também, veja a seguir/abaixo
                [ "/dir/on/host", "/mounted/in/container" ]
                { "localRoot": "/local/dir", "remoteRoot": "/remote/dir" }
            ]
        },
        "lspclient": {
            "servers": {
                "python": {
                    // isto irá corresponder/juntar com o objeto acima
                    "exec": { "hostname": "foobar" },
                    // confina este servidor a sua raiz de projeto,
                    // então ele não é usado para outros projetos que podem ser abertos
                    // (outros servidores podem já empregar raízes específicas, mas o python generalmente não pode)
                    "root": "."
                },
                "c": {
                    // as above
                    "exec": { "hostname": "foobar" },
                    "root": "."
                }
            }
        }
    }

Então, o que acontece como resultado do exposto acima? Como mencionado, a parte `lspclient` acima é mesclada à configuração global, portanto, uma seção `exec` é encontrada (para as linguagens especificadas). Uma busca é realizada por outro objeto (que especifica `hostname` correspondente) na seção `exec` ou `lspclient`, e um objeto correspondente serve como base para uma mesclagem. Como resultado, um servidor LSP (para C e Python) terá sua linha de comando anexada ao prefixo especificado (variável substituída) e, portanto, será iniciado dentro do contêiner fornecido. Obviamente, o contêiner deve ter sido criado, estar em um estado iniciado corretamente e equipado com servidores LSP apropriados. Poderia ter havido a tentação de usar a seção `global` (dentro de `lspclient`). Isso também poderia funcionar, mas então todos os servidores LSP seriam iniciados com esse prefixo, incluindo aqueles para, por exemplo, Markdown, script Bash ou JSON. É mais provável que o host usual ainda forneça esses (se estiverem em uso). Portanto, como sempre, depende da sua configuração específica.

No entanto, o servidor LSP agora pode observar caminhos (remotos) diferentes dos caminhos (locais) que são vistos e usados ​​pelo editor. Os `pathMappings` especificados são usados ​​para traduzir de um lado para o outro na comunicação com o servidor LSP. Isso é, obviamente, o máximo possível. Claramente, nem todos os caminhos locais têm uma representação remota, mas os ausentes também não são vistos (pelo servidor) e não representam um problema. Por outro lado, o servidor (remoto) agora pode ver e fornecer referências na "raiz remota" que não são evidentemente/facilmente representadas no sistema local. O `mapRemoteRoot` habilitado mapeia implicitamente a raiz remota para uma "URL local" `exec://foobar`, que é então tratada por um protocolo KIO simples. Este último utiliza essencialmente (por exemplo) `podman exec -i foobarcontainer cat somefile` para copiar de um arquivo remoto para um local (e outras variações semelhantes usando ferramentas do pacote `coreutils`). Basta dizer que não se destina ao uso geral e não promete qualquer desempenho, mas é suficiente para carregar um arquivo referenciado no editor de forma rápida e fácil.

Agora é fácil perceber que uma versão simplificada da configuração acima (sem `hostname` ou `pathMappings`) poderia ser usada para lidar com o ambiente virtual sem precisar duplicar a linha de comando do servidor (no script wrapper).

O que se segue pode não ser tão facilmente visível, por isso é mencionado aqui explicitamente.

- Tanto o `hostname` quanto o `prefix` definem o ambiente de execução (o primeiro pelo nome, o segundo pelo conteúdo). Em uma instância de processo de editor, o mesmo `hostname` não deve ser associado a `prefix` diferentes, pois isso leva a um comportamento indefinido (sem necessidade de diagnóstico).

- Tanto `prefix` quanto `pathMappings` estão sujeitos à expansão de variáveis ​​(do editor) (mas leve em consideração o item anterior).

- Em tempo de execução, algumas variáveis ​​de ambiente também são definidas, as quais podem ser usadas para ajustar (sutilmente) o comportamento do "inicializador de prefixo" (embora, novamente, preste atenção ao primeiro item). Em particular, `KATE_EXEC_PLUGIN` é definido como `lspclient` e `KATE_EXEC_SERVER` é definido com o ID do servidor (por exemplo, `python`).

- Em particular, também `KATE_EXEC_INSPECT` é definido como `1`. Isso notifica o "inicializador de prefixo" de que o receptor (plugin Kate) aceita alguns dados fora de banda/protocolo. Isso permite que o inicializador use algum meio para determinar mapeamentos de caminho (por exemplo, `podman inspect`) e comunique isso em um formato adequado. Isso será então removido do fluxo que, de outra forma, está em conformidade com o protocolo LSP e usado para estender qualquer mapeamento de caminho definido. Isso pode servir como uma alternativa para especificar, por exemplo, montagens de ligação explicitamente (novamente, duplicando a definição do contêiner). Concretamente, o trecho acima poderia então ser usado em vez disso;

      {
          // ...
          "exec": {
              "hostname": "foobar"
              // repetição infeliz do nome, mas o script auxiliar é simples e direto.
              "prefix": "exec_inspect.sh foobarcontainer podman exec -i foobarcontainer",
              "mapRemoteRoot": true,
              "pathMappings": []
          }
          // ...
      }

Por último, mas não menos importante, e se a abordagem "KIO de fallback" não for considerada adequada? Na prática, muitas vezes é possível "montar" a raiz remota no sistema de arquivos local e, em seguida, especificar este último em um `pathMappings`. Para começar, o conhecido sistema de arquivos `sshfs` (fuse) pode montar um sistema (realmente) remoto no local. Para um contêiner (podman/docker), a maioria das configurações (de driver de sistema de arquivos) suporta o seguinte truque;

    $ rootdir=/proc/`podman inspect --format '{{.State.Pid}}' containername`/root
    # alguns links simbólicos podem causar problemas, veja também a alternativa abaixo
    $ sudo mount --bind $rootdir /somewhere/containername

Se isso falhar, pode-se recorrer ao `sshfs`, ou, na verdade, a um subconjunto dele para montar a raiz remota/do contêiner;

    # consulte as respectivas páginas de manual; sftp-server é suficiente para o protocolo de operações de arquivo real (não criptografado)
    $ socat 'exec:podman exec -i containername /usr/lib/openssh/sftp-server'
       'exec:sshfs -o transform_symlinks -o passive \:/ /somewhere/containername'
    # ...
    $ fusermount -u /somewhere/containername

Observe que essa montagem da raiz remota no sistema de arquivos do host provavelmente será especificada manualmente e explicitamente em uma seção `pathMappings` (exceto em um inicializador de prefixo muito inteligente que organiza tudo isso automaticamente).

## Pesquisar e substituir

### Introdução

O plugin Pesquisar e substituir do &kate; permite-lhe pesquisar por um texto ou expressões regulares em vários arquivos de uma só vez. Você pode pesquisar em todos os arquivos abertos, todos os arquivos de uma pasta e, opcionalmente, em suas subpastas, ou no arquivo ativo. Você pode até mesmo filtrar por nome de arquivo, para por exemplo pesquisar somente em arquivos que terminam com uma extensão de arquivo específica.

### Interface

#### Parâmetros da pesquisa

As opções a seguir são exibidas sempre no topo da ferramenta Pesquisar nos arquivos:

- Você pode ter tantas pesquisas quanto desejar abertas ao mesmo tempo. Basta clicar no botão Nova aba no canto superior esquerdo da ferramenta de Pesquisa e uma nova aba de resultados será aberta, permitindo que você realize outra pesquisa.

- O botão no canto superior direito da ferramenta Pesquisar nos arquivos alternará a metade inferior da ferramenta entre exibir opções adicionais para o modo Pesquisar na pasta e os resultados de sua pesquisa.

Localizar

- Aqui é onde você digita o que deseja encontrar. Você pode inserir um texto padrão ou uma expressão regular, se este recurso estiver ativo.

Substituir (campo de texto)

- O texto de substituição que será adicionado ao(s) arquivo(s), em vez do texto no campo Localizar.

Pesquisa

- Quando terminar de configurar tudo, basta pressionar o botão Pesquisar para realizar a pesquisa; para realizar a pesquisa em uma nova aba, pressione e segure &Ctrl; antes de pressionar o botão Pesquisar. Você também pode pressionar &Enter; na caixa de texto Localizar para fazer o mesmo (da mesma forma, pressionar &Ctrl;&Enter; realizará a pesquisa em uma nova aba).

Substituir

- Quando você tiver terminado de configurar tudo, basta clicar no botão Substituir para substituir o texto introduzido no campo Localizar pelo conteúdo do campo Substituir. Você também pode pressionar &Enter; no campo Substituir para fazer o mesmo.

Próxima

- Vai para a próxima ocorrência da sua pesquisa, mudando de arquivo se necessário.

Substituir marcados

- Igual ao Substituir, mas só irá efetuar as substituições nos arquivos assinalados no painel abaixo.

#### Opções do Pesquisar na pasta

Estas opções são exibidas abaixo das opções de consulta mencionadas anteriormente. Se os resultados da pesquisa estiverem sendo exibidos, pressione o botão para exibi-las.

Pesquisar em

- Há três opções. Selecione Arquivos abertos para pesquisar em todos os arquivos atualmente abertos no &kate;. Selecione Pasta para pesquisar em uma pasta e opcionalmente em suas subpastas. Selecione Arquivo atual para pesquisar apenas no arquivo ativo.

  Se o plugin Projetos estiver carregado, você também poderá pesquisar no Projeto atual ou em Todos os projetos abertos.

Diferenciar maiúsculas de minúsculas

- Restringe os resultados da pesquisa apenas aos que tiverem a combinação exata de letras maiúsculas e minúsculas do texto da sua pesquisa.

Expressões regulares

- Permite-lhe usar expressões regulares, em vez de texto simples, no seu texto de pesquisa.

Expandir resultados

- Mostra todos os resultados encontrados em cada arquivo, em vez de apenas uma lista dos arquivos que contêm o texto da pesquisa.

Pasta

- Você pode inserir a localização da pasta que deseja pesquisar. Por exemplo, você pode inserir `~/development/kde/kate/` se deseja pesquisar no código-fonte do &kate;. Esta opção só fica disponível ao usar o modo na pasta.

Janela de abertura de arquivo

- Clique nesse botão para localizar a pasta no navegador de pastas do seu computador. Esse botão só funciona quando estiver usando o modo Pasta.

- Clique neste botão para mudar a Pasta para a pasta pai da atualmente selecionada. Esse botão só funciona quando estiver usando o modo Pasta.

- Este botão definirá a entrada Pasta para a pasta na qual o documento atual está localizado. Esse botão só funciona quando estiver usando o modo Pasta.

Filtro

- Isto permite que você pesquise somente por nomes de arquivos que correspondam a um determinado padrão. Por exemplo, para pesquisar somente por arquivos escritos em C++, mude isto para `*.cpp`. Para pesquisar somente por arquivos começando com `kate`, mude isto para `kate*`. Você pode inserir vários filtros separados por vírgula (`,`). Esta opção não está disponível quando estiver usando o modo Arquivos abertos.

Excluir

- É o oposto do Filtro, impedindo que o &kate; pesquise por arquivos que correspondam aos padrões indicados. Como no Filtro, você poderá indicar vários padrões separados por vírgula (`,`). Essa opção não está disponível quando estiver usando o modo Arquivos abertos.

Recursivo

- Se esta opção estiver ativa, o &kate; pesquisará também em todas as subpastas da pasta selecionada. Essa opção só está disponível quando estiver usando o modo Pasta.

Incluir ocultos

- Se esta opção estiver ativa, o &kate; também pesquisará em arquivos ou pastas que estão normalmente ocultos pelo seu &OS;. Essa opção só está disponível quando estiver usando o modo Pasta.

Seguir as ligações simbólicas

- O plugin Pesquisar nos arquivos normalmente não segue ligações simbólicas. Quando esta opção estiver ativa, o plugin as seguirá ao invés de pesquisar dentro dos arquivos ou pastas às quais elas se referem. Essa opção só está disponível quando estiver usando o modo Pasta.

  É possível ligações simbólicas que se referem a uma pasta que é a pai da pasta que estiver atualmente sendo pesquisada, ou que outras pastas contenham ligações simbólicas para seus pais. Se existir este tipo de ligação na pasta que está sendo pesquisada e esta opção estiver ativa, o &kate; seguirá repetidamente a ligação e pesquisará a pasta, e a pesquisa nunca terminará.

Incluir arquivos binários

- Se esta opção estiver ativa, o &kate; pesquisará também irá pesquisar nos arquivos que não parecem ser de texto.

#### Resultados da pesquisa

Os resultados de sua pesquisa são exibidos abaixo das opções de consulta. Se as opções do modo de Pesquisa em pasta estiverem sendo exibidas, basta pressionar o botão para exibi-los. Eles também serão automaticamente exibidos tão logo a pesquisa termine.

Os resultados da pesquisa mostram uma lista de arquivos que contêm o texto que corresponde à sua pesquisa, seguido do número de ocorrências encontradas nesse arquivo.

Para ver uma lista das ocorrências nesse arquivo, basta clicar na seta de expansão à esquerda do nome do arquivo. (Se você selecionou a opção Expandir resultados, isso já foi feito). Será apresentado o número da linha em que foi encontrada a ocorrência, seguido do conteúdo dessa linha, onde o texto da sua pesquisa será destacado em negrito.

Para abrir o arquivo em que foi encontrado o seu resultado, basta clicar duas vezes sobre ele, para ser aberto pelo &kate;, se necessário. Você também pode mover o cursor para o local da ocorrência, com um clique duplo nessa lista, em vez de no nome do arquivo.

### Estrutura do menu

&Ctrl;&Alt;F Editar Pesquisar nos arquivos

- Abre a janela da ferramenta Pesquisar e substituir.

Editar Ir para a próxima ocorrência

- Vai para a ocorrência seguinte de uma pesquisa efetuada pelo plugin Pesquisar e substituir.

Editar Ir para a ocorrência anterior

- Vai para a ocorrência anterior de uma pesquisa efetuada pelo plugin Pesquisar e substituir.

Exibir Visões da ferramenta Pesquisar e substituir

- Alterna a exibição da ferramenta Pesquisar e substituir do &kate;.

## Scripts e Snippets do &kate;

### Introdução

O plugin de Scripts & Snippets do &kate; permite adicionar e gerenciar seus próprios trechos de automação. Isso pode variar de trechos estáticos reutilizáveis ​​de texto simples, passando por modelos sofisticados com campos personalizados, automatizados e programáveis, até scripts &javascript; totalmente personalizados para modificar o conteúdo do seu documento.

Na maior parte dos casos, esses tipos de conteúdo são gerenciados exatamente da mesma maneira. Portanto, para facilitar a leitura, a discussão a seguir não diferencia entre trechos estáticos, trechos com script, snippets e scripts. Em vez disso, o termo trecho é usado para se referir a todos eles.

O plugin também suporta a atribuição de atalhos de teclado e a inserção de trechos de código por meio do preenchimento automático. Além disso, você pode baixar coleções de trechos de código (os chamados repositórios) da internet.

### Estrutura do menu

Exibir Áreas de ferramentas Mostrar trechos

- Mostra o painel de trechos que contém todos os trechos no seu repositório que digam respeito ao tipo de arquivo que estiver aberto.

Ferramentas Criar trecho

- Cria um novo trecho, que é um bloco de texto reutilizável que você pode inserir em qualquer parte de qualquer documento, ou um pequeno script.

### Painel de trechos

Painel de trechos do &kate; Painel de Trechos do Kate.

Painel de Trechos do &kate;.

No painel, você deverá ver uma lista de repositórios de trechos, em conjunto com as opções para criar os seus próprios, obtê-los da Internet ou carregá-los a partir de um arquivo local. Cada repositório tem uma opção de marcação que poderá ser usada para ativá-lo ou desativá-lo. Existem também botões para editar e excluir os repositórios existentes.

#### Carregamento dos arquivos do repositório de trechos

Você pode baixar repositórios de trechos a partir da Internet. Basta clica em Baixar novos trechos para abrir uma janela com uma lista de repositórios de trechos. Depois de baixar o trecho desejado, certifique-se que foi ativado.

#### Criação e edição de repositórios

Para criar um novo repositório de trechos, clique em Adicionar repositório. Você deverá ver uma caixa de diálogo que lhe pede o nome, licença e autor. Depois de escolher as opções desejadas, clique em Ok.

Editor de trechos O editor de repositório.

Interface do editor de repositório.

O editor de repositório de trechos contém as seguintes opções:

Nome

- Aparece na lista de trechos na área de ferramentas e também é pesquisada quando for usada a funcionalidade de autocompletar o código.

Espaço de nomes

- Prefixo usado ao utilizar o completamento de código.

Licença

- Seleciona a licença para o seu repositório de trechos de código.

Autores

- Insira o nome do autor ou autores do arquivo de trecho.

Tipos de arquivo

- Selecione o(s) tipo(s) de arquivo(s) onde quer que o repositório de trechos se aplique. Por padrão, ele está configurado como *, o que se aplica a todos os arquivos. Você pode alterá-lo para algo como `C++`, por exemplo, ou selecionar a partir de uma lista, clicando nos itens. Poderá também indicar mais de um tipo de arquivo, pressionando &Shift; enquanto adiciona os tipos.

#### Criação e edição de trechos

Editor de trechos Editor de Trechos.

Interface do Editor de Trechos.

Nome

- O nome conforme mostrado na lista de trechos e na lista de completamento (obrigatório).

Tipo

- Os trechos podem ser definidos como modelos de texto ou scripts. Ambos os tipos permitem o uso de funções &javascript; (veja detalhes abaixo) e, portanto, podem ser usados ​​com efeito semelhante. No entanto, como regra geral, os modelos de texto serão mais adequados se você quiser principalmente inserir texto, enquanto os scripts costumam ser uma solução mais fácil se você quiser modificar texto).

  O Kate precisa ser compilada com o KTextEditor versão 6.15.0 ou superior para que este recurso esteja disponível. Para versões anteriores, somente trechos de modelo de texto podem ser usados.

Atalho

- Ao pressionar este atalho, o trecho de código será inserido (ou executado) no documento atual.

Trecho (digite `Modelo de texto`)

- O texto que seu trecho de código irá inserir no documento.

  Um trecho de código pode conter campos editáveis. É possível alternar entre eles pressionando a tecla . As seguintes expressões podem ser usadas no texto do modelo para criar campos:

  `${`nome_campo`}` cria um campo simples e editável. Todas as ocorrências subsequentes do mesmo `nome_campo` criam campos que espelham o conteúdo do primeiro durante a edição.

  Os nomes dos campos podem conter qualquer caractere, exceto a chave de fechamento (`}`).

  Para inserir literalmente `${texto}` em um trecho de código, escape o sinal``$` com uma barra invertida: `\${texto}`. O texto não será então transformado em um campo. Para inserir barras invertidas literais antes de um campo, escape cada barra invertida individual: `\\${campo}`, `\\\\${campo}`, e assim por diante.

  `${func(`outro_campo1`, `outro_campo2`, ...)}` cria um campo que avalia uma função &javascript; a cada edição e é substituído pelo valor de retorno dessa função. Consulte a aba da Biblioteca de Scripts para mais informações.

  `${`nome_campo=padrão`}` define um valor padrão para o campo. `padrão` é uma expressão &javascript;. Use aspas (`${`campo_nome`=`"texto"`}`) para especificar uma string fixa como valor padrão.

  Ao usar valores padrão (`${`campo_nome=padrão`}`), lembre-se de que o valor padrão é avaliado imediatamente quando o trecho é inserido no documento e não é atualizado posteriormente quando os campos são alterados.

  Você pode referenciar outros campos em valores padrão se eles forem definidos antes do valor padrão que está sendo avaliado. No entanto, isso lhe dará acesso apenas ao valor padrão desses campos.

  Caso nenhum valor padrão personalizado seja definido, o valor padrão será o nome do campo.

  `${cursor}` marca a posição final do cursor após todo o resto ter sido preenchido. Inserir texto nesta posição finalizará a edição. Além disso, após pressionar &Esc; para finalizar a edição, o cursor saltará para esta posição.

Trecho (digite `Script`)

- O código &javascript; a ser avaliado para este trecho

  Se este código contiver uma instrução `return`, a string retornada será inserida na posição atual do cursor. Você também pode usar a API de scripting do &kate; para modificar o documento diretamente.

  Além disso, seu código pode usar funções definidas na aba da Biblioteca de scripts, que são compartilhadas entre todos os trechos em um repositório.

Biblioteca de scripts

- Funções auxiliares em &javascript; para usar em seus trechos de código. Essas funções são compartilhadas entre todos os trechos de código em um repositório.

  Você pode usar a API de script do &kate; para obter o texto selecionado, o texto completo, o nome do arquivo e muito mais, usando os métodos apropriados dos objetos `document` e `view`. Consulte a documentação da API de script para obter mais informações.

  Quando uma função é chamada em um campo de um trecho de `Modelo de texto`, seu valor de retorno é inserido no texto.

  Usando funções em trechos de código de `Modelo de texto`:

  - As funções podem acessar o conteúdo atualizado de todos os campos por meio do objeto `fields`: use `fields.meu_campo` ou `fields["meu_campo"]`. Ao usar uma função como valor padrão para um campo, somente os campos definidos no texto antes estarão disponíveis.

  - Os campos podem ser passados ​​como argumentos para funções. O nome do campo pode ser usado diretamente se for um identificador &javascript; válido e nenhuma variável com esse nome existir. Caso contrário, use o objeto `fields`: `${func(field)}`, `${func(fields.document)}`, `${func(fields["meu_campo"])}`

  - Os campos de função (por exemplo, `${func()}`) são reavaliados sempre que o conteúdo de qualquer campo é alterado. No entanto, isso não se aplica a chamadas de função com valores padrão: elas são avaliadas apenas uma vez quando o trecho de código é inserido no documento.

  - Para scripts mais complexos, pode ser importante entender que primeiro, o trecho bruto é inserido no documento, e depois as funções são avaliadas. Por exemplo, se uma função recupera o texto na linha onde o trecho está sendo inserido, esse texto também conterá `${functionCall()}`. Quando isso causar complicações, considere usar um trecho do tipo `Script` em vez disso.

  - Para simplesmente envolver o texto selecionado em tags, use: `<strong>${view.selectedText()}</strong>`

  - Lembre-se de que apenas o valor de retorno de uma função é inserido em um campo.

Descrição

- Uma descrição opcional do que este trecho faz. Ela será exibida em dicas de ferramentas. A descrição pode conter formatação HTML básica.

Exemplo de uso

- O exemplo a seguir invoca um script que envolve o texto selecionado ou - se não houver seleção - um texto padrão, em tags (Tipo de trecho: `Script`):

      let range = view.hasSelection() ? view.selection() : new Range(view.cursorPosition(), view.cursorPosition());
      let innertext = range.isEmpty() ? "Bold" : document.text(range);
      document.removeText(range);
      document.insertText(range.start, "<strong>" + innertext + "</strong>");

### Usando trechos

Trechos do &kate; em ação Acessando os trechos do &kate; a partir de uma área de ferramentas e de uma lista.

Selecionando a partir de uma lista de trechos.

Você pode chamar os trechos de diversas maneiras:

- Clicando no trecho a partir da área de ferramentas.

- Usando um atalho de teclado, caso tenha atribuído um.

- Enquanto estiver escrevendo, você pode pressionar &Ctrl; &Space; para mostrar todos os trechos em uma janela conveniente onde poderá fazer a escolha. Essa combinação de teclas oferece uma funcionalidade semelhante a de autocompletar o código.

Se o trecho conter variáveis (além do `${cursor}`), o cursor ficará automaticamente posicionado sobre a primeira ocorrência de uma variável, esperando que você digite algo. Quando terminar, você pode pressionar a tecla para ir até a próxima variável, e assim por diante.

### Agradecimentos e reconhecimento

Trechos do &kate; foi escrito por Joseph Wenninger.

Agradecimentos especiais ao participante Martin Gergov do Google Code-In 2011 pela escrita de grande parte desta seção.

## Plugin de macros de teclado

### Introdução

Grava e reproduz macros de teclado (ou seja, sequências de ação de teclado).

### Uso básico

#### Para começar a gravar uma macro de teclado:

Ferramentas Macros de teclado Gravar macro...(&Ctrl;&Shift;K).

O plugin irá gravar todas as teclas pressionadas até que você encerre a gravação.

#### Para finalizar a gravação:

Ferramentas Macros de teclado Finalizar gravação de macro(&Ctrl;&Shift;K).

O plugin irá parar de gravar as teclas pressionadas e salvar a sequência como a macro atual.

#### Para cancelar a gravação:

Ferramentas Macros de teclado Cancelar gravação de macro (&Ctrl;&Alt;&Shift;K).

O plugin deixará de gravar as teclas pressionadas, mas a macro atual não será alterada.

#### Para executar a macro atual:

Ferramentas Macros de teclado Executar macro (&Ctrl;&Alt;K).

O plugin irá executar a macro atual.

O comando `kmplay` sem argumentos também irá também executar a macro atual.

### Macros nomeadas

É possível salvar macros de teclado atribuindo-lhes um nome.

As macros nomeadas são persistentes entre as sessões de Kate, sendo salvas no arquivo `keyboardmacros.json` na pasta de dados do usuário do Kate (geralmente `~/.local/share/kate/`).

#### Para salvar a macro atual:

Ferramentas Macros de teclado Salvar macro atual (&Alt;&Shift;K).

O plugin solicitará que você insira um nome e salvará a macro com esse nome.

O comando `kmsave `nome`` salvará a macro atual com o nome ``nome``.

#### Para carregar uma macro salva como a macro atual:

Ferramentas Macros de teclado Carregar macro nomeada....

O plugin lista as macros salvas como itens neste submenu; ativar um item carregará a macro correspondente como a macro atual.

O comando `kmload `nome`` carregará a macro salva com o nome ``nome`` como a macro atual.

#### Para reproduzir uma macro salva sem carregá-la:

Ferramentas Macros de teclado Reproduzir macro nomeada....

O plugin lista as macros salvas como itens neste submenu; ativar um item irá executar a macro correspondente sem carregá-la.

Observe que cada macro salva é uma ação que faz parte da coleção de ações atual, de modo que um atalho personalizado pode ser atribuído a ela por meio da interface Configurações Configurar atalhos do teclado....

O comando `kmplay `nome``executará a macro salva com o nome ``nome`` sem carregá-la.

#### Para limpar (ou seja, excluir) uma macro salva:

Ferramentas Macros de teclado Limpar macro nomeada....

O plugin lista as macros salvas como itens neste submenu; ativar um item irá limpar (ou seja, excluir) a macro correspondente.

O comando `kmwipe `nome`` irá apagar a macro salva com o nome ``nome``.

#### Dicas para comandos:

Observe que, após o prefixo `km`, todos esses comandos usam uma letra diferente para que você possa chamá-los de forma eficiente usando a função de autocompletar com a tecla Tab!

### Limitações

Atualmente, as macros de teclado não funcionam corretamente se alguns tipos de widgets de GUI forem usados: QMenu, QuickOpenLineEdit ou TabSwitcherTreeView, por exemplo.Não sei o motivo, mas meu primeiro palpite é que esses widgets funcionam de maneira não padronizada em relação aos eventos de teclado.

## Plugin do SQL

### Introdução

O SQL (Structured Query Language) é uma linguagem especializada para atualizar, excluir e solicitar informações de bancos de dados.

O plugin do SQL do &kate; permite-lhe:

- Criar um banco de dados

- Conectar-se a bancos de dados existentes

- Inserir e excluir dados do banco de dados

- Executar consultas

- Exibir resultados em uma tabela

### Conectar-se a um banco de dados

Selecione a opção Adicionar conexão do menu SQL ou na barra de ferramentas e depois selecione o controlador de banco de dados do &Qt; que você deseja usar (incluindo QSQLITE, QMYSQL3, QMYSQL, QODBC3, QODBC, QPSQL7 e QPSQL). Se você não conseguir ver o controlador desejado, será necessário instalar. Depois, clique em Próximo.

Se o banco de dados que você selecionar usar um arquivo, basta indicar a localização do banco de dados e clicar no botão Próximo. Se ele precisar conectar-se a um servidor, você precisa indicar o nome do servidor, o seu usuário e senha, e quaisquer outras informações necessárias ao controlador. Depois, clique em Próximo.

Finalmente, forneça um nome a sua conexão e clique em Concluir.

### Executando consultas

#### INSERT/DELETE/UPDATE

Você pode inserir, excluir e atualizar dados usando o plugin SQL da mesma forma que faria pela linha de comando ou dentro de um programa. Basta inserir uma consulta e pressionar o botão Executar consulta na barra de ferramentas ou usar SQL Executar consulta (&Ctrl;E).

##### Alguns exemplos de consultas

`INSERT`

-     INSERT INTO nome_tabela ("campo1", "campo2", "campo3", "campo4", "campo5")
      VALUES ("valor1", "valor2", "valor3", "valor4", "valor5" )

`DELETE`

-     DELETE FROM nome_tabela WHERE nome = "texto"

`UPDATE`

-     UPDATE nome_tabela SET "campo1" = "texto", "campo2" = "texto", "campo3" = "texto", "campo4" = "texto", "campo5" = "texto"

#### SELECT

Depois de executar uma consulta `SELECT`, você poderá ver o resultado como uma tabela, que aparecerá na área de ferramentas Resultado dos dados em SQL na parte inferior do &kate; ou como texto no Resultado do texto em SQL. Se ocorrer um erro, você poderá ver no resultado de texto.

##### Exemplo de consulta `SELECT`

    SELECT * FROM nome_tabela

Na área de ferramentas Resultado dos dados em SQL existem diversos botões:

Ajustar as colunas ao conteúdo

- Altera o tamanho das colunas para caber o seu conteúdo.

Ajustar as linhas ao conteúdo

- Altera o tamanho das linhas para caber o seu conteúdo.

Copiar

- Seleciona todo o conteúdo da tabela e copia-o para a área de transferência.

Exportar

- Exporta todo o conteúdo da tabela para um arquivo, para a área de transferência ou para o documento atual, no formato de valores separados por vírgulas (CSV).

Limpar

- Remove tudo da área da tabela.

Você pode agora alterar as cores apresentadas na tabela, na seção SQL da opção Configurações Configurar &kate;... .

### Navegação

Você pode navegar pelo seu banco de dados com a ferramenta de Esquema de banco de dados no lado esquerdo. A informação apresentada varia de acordo com o controlador de banco de dados que você estiver usando.

Para atualizar esta lista, clique com o botão direito em qualquer lado da área da ferramenta e selecione a opção Atualizar. Para gerar uma pesquisa sobre qualquer item da lista, clique com o botão direito sobre um item, selecione Gerar e depois o tipo de instrução (SELECT, UPDATE, INSERT ou DELETE) no submenu que aparece.

### Estrutura do menu

SQL Adicionar conexão...

- Adiciona uma nova conexão usando um controlador de banco de dados.

SQL Remover conexão

- Remove a conexão selecionada.

SQL Editar conexão...

- Edita as configurações da conexão atual.

Conexões

- Todas as conexões ao banco de dados que você criou são apresentadas entre os itens do menu Editar conexão e Executar consulta. Selecione uma para executar pesquisas ou efetuar modificações sobre elas.

&Ctrl;E SQL Executar consulta

- Executa a sua consulta.

### Agradecimentos e reconhecimento

O plugin do SQL foi criado por Marco Mentasti.

Agradecimentos especiais ao participante Ömer Faruk ORUÇ do Google Code-In 2011 pela escrita de grande parte desta seção.

## Plugin de visualizador de símbolo

### Usando o plugin de fechamento com exclusão/inclusão

Permite aos desenvolvedores visualizar símbolos (funções, macros e estruturas) a partir do código-fonte.

Ao clicar nas informações analisadas, você pode navegar facilmente pelo código.

Atualmente, os seguintes idiomas são suportados:

C/C++, &Java;, Perl, PHP, Python, Ruby, XSLT, Tcl/Tk, Fortran

Lista de funcionalidades:

- Modo em Lista/Árvore
- Aivar/desativar ordenação
- Ocultar/mostrar parâmetros das funções
- Expandir/recolher modo em árvore
- Atualizar automaticamente ao alterar documento
- A análise sintática do código é baseada na estrutura de realce de sintaxe do &kde-frameworks;

### Estrutura do menu

&Ctrl;\ Exibir Visualizações de ferramenta Mostra lista de símbolos

- Alterna a exibição da lista de símbolos de &kate;, que mostra Funções, Macros e Estruturas do código-fonte no documento ativo.

### Configuração

Visualizador de símbolos

Seleciona as opções padrão do analisador

## Plugin da área da ferramenta Terminal

O Emulador de Terminal integrado é uma cópia do aplicativo &konsole; do &kde;; para sua conveniência. Ele está disponível no item de menu Exibir Visualizações de ferramenta Mostrar painel do terminal e receberá o foco se exibido. Adicionalmente, se a opção Sincronizar automaticamente o terminal com o documento ativo se possível estiver habilitada, ele irá para a pasta do documento atual, se possível, quando for exibido ou quando o documento atual for modificado.

A localização padrão na janela do &kate; estará na base, abaixo da área de edição.

Você poderá configurar o &konsole; com o seu menu de &RMB;; para mais informações, veja o manual do &konsole;.

O emulador de terminal embutido é fornecido pelo plugin de ferramenta de visualização de terminal.

### Estrutura do menu

Exibir Visualizações de ferramentas Mostrar o painel de terminal

- Alterna para a exibição de um emulador de terminal integrado.

  Quando ativado pela primeira vez, o terminal será criado.

  Quando o emulador de terminal for mostrado, ele obterá o foco, e assim você pode iniciar imediatamente a digitação de comandos. Se a opção Sincronizar automaticamente o terminal com o documento ativo quando possível estiver habilitada na página Terminal do Diálogo principal de configuração, a sessão shell irá para a pasta do documento ativo, se ele for um arquivo local.

Ferramentas Encaminhar para Terminal

- Fornece o texto selecionado ao emulador de terminal integrado. Não será adicionada nenhuma nova linha após o texto.

Ferramentas Sincronizar o terminal com documento atual

- Isto fará com que o terminal integrado use `cd` para a pasta do documento ativo.

  Alternativamente, você pode configurar o &kate; para sempre manter o terminal em sincronia com o documento atual. Veja em konsole-config para mais informações.

Ferramentas Executar documento atual

- Executa o documento atual no &konsole;. Somente documentos locais podem ser executados. O &kate; exibirá um aviso antes de executar o documento, pois esta ação pode representar uma séria ameaça à segurança.

Ferramentas Focar/Remover foco do painel de terminal

- Muda o foco do documento atual para o terminal e vice-versa.

### Configuração

Você pode configurar o plugin da área da ferramenta Terminal na página da caixa de diálogo de configuração.

Estão disponíveis as seguintes opções:

Sincronizar automaticamente o terminal com o documento atual se possível

- Isto causará a integração do terminal ao comando `cd` dentro da pasta do documento ativo quando lançado, e quando um novo documento obter o foco. Se não estiver habilitado, você terá que fazer toda a sua navegação pelo terminal sozinho.

Definir a variável de ambiente EDITOR como sendo 'kate -b'

- Isto define a variável de ambiente `EDITOR` de modo que programas executados no terminal embutido que abrem automaticamente um arquivo em um editor abrirão estes arquivos no &kate; ao invés do editor configurado em seu shell. Você não será capaz de continuar usando o terminal até que você feche o arquivo no &kate;, de modo que o programa que realizou a requisição saiba que você terminou a edição do arquivo.

Oculta o &konsole; ao pressionar 'Esc'

- Isso permite fechar o terminal integrado pressionando a tecla &Esc;. Pode causar problemas com aplicativos de terminal que usam a tecla &Esc;, por exemplo: vim. Adicione esses aplicativos na caixa de entrada de texto abaixo. Os itens da lista devem ser separados por vírgula.

## Plugin de filtro de texto

### Usando o plugin de filtro de texto

Você pode usar este plugin para processar o texto selecionado usando comandos do terminal. A seleção será usada como entrada para o comando e a saída substituirá a seleção ou será copiada para a área de transferência, dependendo das preferências do usuário.

### Exemplos:

- `less /etc/fstab` - cola o conteúdo deste arquivo ou copia-o para a área de transferência

- `wc` - conta linhas, palavras e caracteres da seleção e cola isso no documento ou copia para a área de transferência

- `sort` - classifica as linhas da seleção e cola o resultado no documento ou copia para a área de transferência

### Estrutura do menu

&Ctrl;\ Ferramentas Filtrar texto

- Abre a janela para filtro de texto:

  Janela de filtro de texto

  Insira o comando do shell na caixa de combinação ou selecione um comando anterior no histórico.

  Copiar o resultado ao invés de colar ele

- Copia o resultado para a área de transferência deixando um documento inalterado.

Mesclar STDOUT e STDERR

- Se selecionada, a saída de STDOUT e STDERR será mesclada e nenhum erro será relatado. Caso contrário, STDERR será exibido como uma mensagem passiva.

## Validação do &XML;

Este plugin verifica se os arquivos XML são válidos e estão bem formados.

Este plugin verifica o arquivo atual. Uma lista de avisos e erros aparecerá na parte inferior da janela principal do &kate;. Você pode clicar em uma mensagem de erro para ir para o local correspondente no arquivo. Se o arquivo tiver um DOCTYPE, o DTD fornecido com este doctype será usado para verificar a validade do arquivo. O DTD deve estar em uma posição relativa ao arquivo atual, ⪚ se o doctype se referir a DTD/xhtml1-transitional.dtd e o arquivo for `/home/peter/test.xml`, o DTD deve estar localizado em `/home/peter/DTD/xhtml1-transitional.dtd`. No entanto, DTDs remotos especificados via HTTP também são suportados.

Se o arquivo não tiver um doctype, será verificado se ele está bem formado.

Para saber mais sobre &XML;, consulte as páginas oficiais do W3C sobre &XML;.

Internamente, este plugin chama o comando externo `xmllint`, que faz parte do libxml2. Se este comando não estiver corretamente instalado em seu sistema, o plugin não funcionará.

Para carregar este plugin, abra a janela de configuração do &kate; em Configurações Configurar &kate;.... Em seguida, selecione Validação XML que aparecerá na seção Aplicativo / Plugins e feche a janela.

### Estrutura do menu

&XML; Validação do &XML;

- Isso iniciará a verificação, conforme descrito acima.

### Agradecimentos e reconhecimento

&kate; Plugin Validação &XML; direitos autorais 2002 &Daniel.Naber; &Daniel.Naber.mail;.

Copyright da Documentação 2001,2002 &Daniel.Naber;

## Completamento &XML;

Este plugin dá pistas sobre o que é permitido em determinada posição de um arquivo &XML;, de acordo com o DTD do arquivo. Ele lista elementos, atributos, valores de atributos ou entidades válidas, dependendo da posição do cursor (⪚, todas as entidades são mostradas se o caractere à esquerda do cursor for &). Também é possível fechar a marca aberta mais próxima à esquerda.

O DTD deve existir em formato &XML;, como produzido pelo programa Perl `dtdparse`. Chamaremos um DTD neste formato de meta DTD. Alguns meta DTDs são fornecidos. Eles estão instalados em `katexmltools/` no ``qtpaths` `--paths GenericDataLocation`` , que também é a pasta padrão quando você escolhe Designar Meta DTD.... Para produzir seus próprios meta DTDs, baixe o `dtdparse` em http://dtdparse.sourceforge.net.

### Como usar

Inicie o &kate; e abra a janela de configuração em Configurações Configurar o &kate;.... Depois, selecione o Completamento de &XML; que irá aparecer na página Aplicativo Plugins e feche a janela. Depois disso, selecione a opção do menu &XML;Atribuir uma Meta-DTD.... Se o seu documento não tiver nenhum DOCTYPE ou se ele for desconhecido, você terá que selecionar uma meta-DTD no sistema de arquivos. Caso contrário, será carregada automaticamente a meta-DTD que corresponder ao DOCTYPE do documento atual.

Você pode agora usar o plugin enquanto digita seu texto:

< (chave menor que)

- Isto disparará uma lista dos elementos possíveis a menos que o cursor esteja já dentro de uma tag. Note que você atualmente não pode usar isto para inserir os elementos de nível mais alto (⪚ <html>).

</ (tecla 'menor que' + barra)

- Inserir estes caracteres irá oferecer o fechamento do elemento atual (o mais próximo do que se encontra à esquerda do cursor). Pressione &Enter; para aceitar a sugestão. Ao contrário do item Fechar o elemento, isto funciona apenas com uma DTD atribuída.

" (chave de citação)

- A chave de citação disparará uma lista dos valores de atributos possíveis (se existirem) se você estiver dentro de uma tag.

(chave espaço)

- Isto disparará uma lista dos atributos possíveis para o elemento atual se você estiver dentro de uma tag.

& (chave E comercial)

- Isto disparará uma lista de entidades nomeadas.

### Características e limitações

Você pode testar todas as funções e limitações carregando `katexmltools/testcases.xml` em ``qtpaths` `--paths GenericDataLocation`` no &kate; e seguindo as instruções.

### Estrutura do menu

&Ctrl;&Enter; &XML; Inserir elemento...

- Isto irá abrir uma janela que lhe permite inserir um elemento em &XML;. Os caracteres <, > e a marca de fecho serão inseridos automaticamente. Se você tiver selecionado algum texto quando tiver selecionado este item do menu, o texto selecionado será rodeado pela marca de abertura e de fecho. A janela também oferece o completamento de todos os elementos que poderão ser inseridos na posição atual do cursor, caso tenha atribuído uma meta-DTD com a opção Atribuir uma Meta-DTD....

&Ctrl;< &XML; Fechar elemento

- Isto irá pesquisar em seu texto por uma tag que não está ainda fechada e irá fechá-la inserindo a tag de fechamento correspondente. A pesquisa inicia na posição do cursor e vai para a esquerda. Se não puder encontrar uma tag aberta nada acontecerá.

&XML; Designar Meta DTD...

- Isto irá dizer ao plugin qual meta DTD usar para o documento atual. Note que esta designação não será salva. Você terá que repetir isto quando você iniciar o &kate; na próxima vez.

### Agradecimentos e reconhecimento

Plugin para o &kate; de Completação de &XML; copyright 2001,2002 &Daniel.Naber; &Daniel.Naber.mail;.

Versão para o &kde; SC 4 com direitos autorais de 2010 de Tomáš Trnka

Copyright da Documentação 2001,2002 &Daniel.Naber;

## Plugin de explorador de compilador

O plugin de explorador de compilador permite que você use o explorador de compilador de dentro do Kate. O explorador de compilador geralmente é limitado a apenas um arquivo e é difícil usá-lo para visualizar a geração de código de um arquivo em seu projeto. Este plugin visa simplificar esse processo, detectando automaticamente os comandos de compilação do seu arquivo.

### Uso

A primeira coisa que você precisa fazer é abrir uma aba do explorador de compiladores. Pressione &Ctrl;&Alt;I para abrir a barra de comandos e procure por "Abrir arquivo atual no explorador de compiladores" e pressione Enter. Você pode adicionar essa ação à barra de ferramentas ou atribuir um atalho a ela para facilitar o acesso.

Em seguida, você precisa configurar uma instância local do explorador de compiladores ou usar a instância pública https://godbolt.org/. Consulte https://github.com/compiler-explorer/compiler-explorer. Depois de ter uma instância, clique na caixa de combinação Opções na aba do explorador de compiladores que você abriu anteriormente e selecione Alterar URL... e, em seguida, insira a URL do servidor do explorador de compiladores.

Em seguida, você precisa de um arquivo compile_commands.json se precisar visualizar a geração de código para um arquivo em seu projeto. Caso contrário, você pode pular esta parte. Isso pode ser facilmente obtido se você estiver usando um sistema de compilação moderno como CMake ou Meson. Para o CMake, basta passar `-DCMAKE_EXPORT_COMPILE_COMMANDS=ON` ao invocar o cmake. O arquivo `compile_commands.json` deve ser colocado na raiz do seu projeto. Feche e abra novamente a aba do explorador de compiladores no Kate. Após reabrir a aba, ela deverá mostrar os comandos de compilação necessários para compilar o arquivo.

Se você estiver usando o explorador de compiladores apenas para visualizar a geração de código de algo temporário, basta digitar os comandos de compilação para o seu arquivo e clicar em Compilar. Observe que a recompilação automática durante a edição não é suportada. Você precisa clicar em Compilar sempre que quiser recompilar o arquivo.

Após a compilação do arquivo, você deverá ver o código gerado no lado direito. Você pode clicar com o botão direito e selecionar Revelar código vinculado para ver o código gerado de uma linha específica. Da mesma forma, no lado direito, você pode clicar com o botão direito e selecionar Rolar até o código-fonte para exibir o código-fonte de uma determinada linha gerada.

## Plugin de formatação

O plugin de formatação permite formatar código facilmente. O objetivo do plugin é preservar o histórico de desfazer do documento e a posição do cursor do usuário ao formatar o código, para que a formatação não interrompa o trabalho do usuário. Isso é especialmente importante para a formatação automática ao salvar.

### Uso

Ele permite ao usuário formatar o código de duas maneiras:

- Utilizando manualmente a ação "Formatar Documento".

- Automaticamente ao salvar

Você pode pesquisar essa ação na barra de comandos e associar um atalho a ela para facilitar o acesso

### Linguagens suportadas e formatadores

A lista atual de idiomas e formatadores suportados é a seguinte:

- C/C++/ObjectiveC/ObjectiveC++/Protobuf/GLSL/Java - `clang-format`

- Javascript/Typescript/JSX/TSX - `prettier`

- JSON

  - `prettier`

  - `clang-format`

  - `jq`

- Dart - `dartfmt`

- Rust - `rustfmt`

- Go - `gofmt`

- XML - `xmllint`

- Zig - `zigfmt`

- CMake - `cmake-format`

- D - `dfmt`

- Fish Shell - `fish_indent`

- Bash - `shfmt`

- Nix - `nixfmt`

- QML - `qmlformat`

- HTML - `prettier`

- Swift - `swiftformat`

- Erlang - `erlfmt`

- Godot Script - `gdformat`

- Python

  - `autopep8`

  - `ruff`

- YAML

  - `yamlfmt`

  - `prettier`

### Configurando

O plugin pode ser configurado de duas maneiras:

- Globalmente, a partir da janela de configuração

- Para cada projeto, usando o arquivo `.kateproject`

Ao ler a configuração, o plugin primeiro tentará ler a configuração do arquivo `.kateproject` e, em seguida, lerá a configuração global. Exemplo:

    {
        "formatOnSave": true,
        "formatterForJson": "jq",
        "cmake-format": {
            "formatOnSave": false
        },
        "autopep8": {
            "formatOnSave": false
        }
    }

A configuração acima:

- ativa a opção "formatar ao salvar" globalmente

- especifica "jq" como o formatador para JSON

- desativa a opção "formatar ao salvar" para cmake-format e autopep8

Para configurar a formatação de um projeto, primeiro crie um arquivo `.kateproject` e, em seguida, adicione um objeto `"formatting"` a ele. No objeto `"formatting"`, você pode especificar suas configurações, como mostrado no exemplo anterior. Exemplo:

Você precisa habilitar o plugin de projeto para que isso funcione

    {
        "name": "Meu Projeto Legal",
        "files": [
            {
                "git": 1
            }
        ],
        "formatting": {
            "formatterForJson": "clang-format",
            "autopep8": {
                "formatOnSave": false
            }
        }
    }

### Desativa temporariamente a formatação ao salvar

Durante o trabalho, você frequentemente precisará desativar a formatação por um curto período de tempo por algum motivo. Você pode fazer isso na barra de menus, em Ferramentas Formatar ao salvar. Você também pode acionar essa ação na Barra de comandos.