# Manual do &kfilereplace;

## Introdução

O &kfilereplace; é uma aplicação que efectua procuras e substituições de texto num ou mais ficheiros. Os textos que deseja procurar poderão ser literais ou expressões regulares do &Qt;. Existem ainda outras opções que poderá usar para afinar a sua procura.

## Utilizar o &kfilereplace;

O &kfilereplace; na sua versão independente O &kfilereplace; na sua versão independente

### A Barra de Ferramentas

A barra de ferramentas do &kfilereplace; tem este aspecto: A barra de ferramentas do &kfilereplace; A barra de ferramentas do &kfilereplace;

A barra de ferramentas mostra-lhe os botões com as funcionalidades principais.

### Ícones da Barra de Ferramentas

Personalizar a Sessão de Pesquisa/Substituição

- Este botão mostra uma janela de sessão, na qual poderá definir várias opções básicas; se o &kfilereplace; correr como uma aplicação autónoma, deverá carregar neste botão como primeiro passo.

Procurar

- Este botão inicia um ciclo de procura.

Simular

- Este botão inicia um ciclo de procura e substituição simulada. Não irá acontecer nada, de facto, quando carregar neste botão.

Substituir

- Este botão inicia um ciclo de procura e substituição. Quando for encontrada uma determinada sequência de texto, o &kfilereplace; substitui-la-á por outro texto.

Parar

- Este botão interrompe uma operação.

Adicionar um Texto

- Este botão abre uma janela para Adicionar Textos, na qual poderá editar a sua lista de textos.

Apagar o Texto

- Este botão remove o texto seleccionado (ou o actual, se não estiver nenhum seleccionado) da lista.

Editar o Texto Seleccionado

- Este botão edita um determinado texto seleccionado.

Esvaziar a Lista de Textos

- Este botão remove todos os textos da lista.

Inverter o Texto Actual

- Este botão troca um determinado texto de procura pelo seu texto de substituição; deste modo, poderá inverter o ciclo de procura/substituição.

Carregar a Lista de Textos de um Ficheiro

- Este botão carrega uma lista de textos gravada num ficheiro XML com a extensão `kfr`.

Incluir as Sub-Pastas

- Este botão permite-lhe procurar/substituir recursivamente nas subpastas da sua pasta de base.

Criar Cópias de Segurança

- Este botão activa a geração de ficheiros de cópias de segurança.

Distinguir Capitalização

- Este botão activa a procura num modo que faça a distinção entre maiúsculas e minúsculas.

Activar os Comandos no Texto de Substituição

- Este botão activa a capacidade dos comandos. Os comandos são sequências de texto especiais. Veja a secção sobre os kfilereplace-commands.

Activar as Expressões Regulares

- Este botão activa as expressões regulares do tipo do &Qt;.

### A Lista de Resultados

Área de resultados do &kfilereplace; Área de resultados do &kfilereplace;

A área de Resultados mostra o nome dos ficheiros que contêm os textos que deve obter (e substituir), a sua localização, tamanho, número de textos encontrados e o nome do utilizador dos ficheiros. Esta área mostra também a posição exacta dos textos correspondentes. Poderá também abrir um ficheiro se carregar nele com o &RMB; na lista que contém a posição da linha e coluna.

### A Lista de Textos

Esta é a área de Textos: Área de textos do &kfilereplace; Área de textos do &kfilereplace;

A área de Textos mostra a lista de palavras que deseja procurar/substituir. Lembre-se que o &kfilereplace;, no modo de procura, a área de Resultados e de Textos têm uma disposição diferente.

### A Janela de Pesquisa & Substituição de Ficheiros

A janela de Pesquisa & Substituição nos Ficheiros é usada para configurar os parâmetros básicos que são necessários para o &kfilereplace; funcionar. Consiste em duas páginas: a página Geral e a Avançado.

#### A Página Geral

A página Geral do &kfilereplace; A página Geral do &kfilereplace;

Quando você quiser iniciar uma nova sessão, o primeiro passo é carregar no botão de Personalizar a Sessão de Pesquisa/Substituição. Depois, terá de indicar a pasta de base e uma sequência de caracteres especiais do tipo da consola (p.ex., * e ?) a usar como filtro.

Depois, poderá definir algumas opções úteis, como a procura em todas as subpastas, fazer uma pesquisa com distinção entre maiúsculas e minúsculas, a activação de comandos e/ou expressões regulares

Repare por favor que as expressões regulares e os comandos poderão reduzir a velocidade de execução.

, fazendo uma cópia de segurança de cada ficheiro antes da substituição.

Se quiser iniciar a procura, poderá colocar um texto no campo de procura e carregar em Procurar Agora, caso contrário deixe o campo de procura vazio e carregue em Procurar Mais Tarde.

#### A Página Avançado

A página Avançado do &kfilereplace; A página Avançado do &kfilereplace;

A página Avançado permite-lhe configurar algumas opções úteis para restringir a procura a um sub-conjunto da sua árvore de ficheiros de alvo. Se quiser executar o &kfilereplace; apenas sobre os ficheiros que tiverem um tamanho entre 10KB - 100KB, então poderá usar as opções de tamanho. Existe também uma opção de data que restringe a procura num intervalo temporal e uma última opção que lhe permite procurar apenas nos ficheiros que pertençam (ou não) a um dado utilizador (isto poderá ser mais útil para os administradores de sistemas).

### A Janela de Opções

Esta janela contém as opções que estão na barra de ferramentas e as opções extra que poderão ser úteis para uma determinada situação. Poderá invocá-la com a opção Configuração Configurar o KFileReplace... do menu.

#### Opções gerais

Estas opções foram apresentadas na secção da Barra de Ferramentas. A página Geral da janela de Opções A página Geral da janela de Opções

#### Opções avançadas

A página Avançado da janela de Opções A página Avançado da janela de Opções

Não mostrar os ficheiros se não forem encontrados ou substituídos textos Ao procurar, parar no primeiro texto encontrado Seguir as ligações simbólicas Ignorar os ficheiros e pastas escondidos
- mostra apenas os ficheiros que correspondem a algum dos seus textos. Isto irá acelerar a procura. O &kfilereplace; irá parar, quando encontrar um texto correspondente, e continuará a pesquisa por outros textos ou, se procurar apenas por uma ocorrência, no próximo ficheiro. se um ficheiro for uma ligação para outro, então procura no ficheiro real. se forem encontrados ficheiros ou pastas escondidos, ignora-os.

### A Janela de Inserção de Textos de Pesquisa/Substituição

A janela para Inserir um Texto de Pesquisa/Substituição do &kfilereplace; A janela para Inserir um Texto de Pesquisa/Substituição do &kfilereplace;

Esta janela é usada para inserir e editar uma lista de textos. É simples de usar, pelo que só precisa de escolher se deseja introduzir uma lista apenas para procuras ou uma lista para procura-e-substituição, introduzindo a partir daí os seus textos. Os botões das setas permitem-lhe adicionar um par de textos ou removê-lo, se concluir que cometeu algum erro. Quando terminar, carregue no botão OK.

## Funcionalidades do &kfilereplace;

Este capítulo oferece algumas informações sobre determinadas capacidades úteis do &kfilereplace;.

### Como gravar a sua lista de textos

Quando desejar reutilizar uma lista com os textos, poderá gravá-la num ficheiro `XML`. Para o fazer, seleccione no menu a opção Procurar/Substituir Textos Gravar a Lista de Textos num Ficheiro. Quando gravar uma lista, será criado um ficheiro simples em `XML` com a extensão `kfr`. Para carregar um ficheiro `kfr`, seleccione no menu a opção Procurar/Substituir Textos Carregar uma Lista de Textos do Ficheiro. O formato actual deste ficheiro é:

    <?xml version="1.0" ?>
    <kfr>
            <mode search="false"/>
            <replacement>
                    <oldstring
    ><![CDATA[TEXTO_PROCURA_1]]
    ></oldstring>
                    <newstring
    ><![CDATA[TEXTO_SUBSTITUIÇÃO_1]]
    ></newstring>
            </replacement>
            <replacement>
                    <oldstring
    ><![CDATA[TEXTO_PROCURA_2]]
    ></oldstring>
                    <newstring
    ><![CDATA[TEXTO_SUBSTITUIÇÃO_2]]
    ></newstring>
            </replacement>

            <replacement>
                    <oldstring
    ><![CDATA[TEXTO_PROCURA_N]]
    ></oldstring>
                    <newstring
    ><![CDATA[TEXTO_SUBSTITUIÇÃO_N]]
    ></newstring>
            </replacement>

    </kfr
    >

Se estiver a usar um formato anterior, poderá actualizar à mão o seu ficheiro, tornando-o compatível com o esquema acima descrito. Em alternativa, poderá carregar o ficheiro no formato antigo e gravá-lo de novo com o &kfilereplace;, tal como está descrito anteriormente.

### Como Criar um Relatório Simples

Poderá criar um relatório se escolher a opção Procurar/Substituir Resultados Criar um Ficheiro de Relatório do menu. Um relatório é uma pasta que contém um ficheiro `XML` e um ficheiro `CSS`. Os relatórios poderão ser úteis, se pretender manter um sistema de registo das suas operações. Veja por favor a imagem. A funcionalidade de Relatório do &kfilereplace; A funcionalidade de Relatório do &kfilereplace;

### Como Usar as Expressões Regulares

Se quiser procurar por todos os textos que comecem por x ou ht ou u e terminem em ml, poderá indicar uma expressão regular do tipo `(x|ht|u)ml`. Introduza esta expressão no editor de procura, carregue no botão OK e, finalmente, active as expressões regulares com o botão de expressões regulares. Lembre-se que a utilização de expressões regulares permite-lhe fazer pesquisas muito complicadas, mas o curto poderá ser uma degradação da velocidade. As expressões regulares poderão ser bastante complicadas e, normalmente, é o caso de se quiser resolver um problema com uma expressão regular, você tem dois problemas.

### Como Proteger os Ficheiros Originais

Se não quiser perder os seus ficheiros originais, poderá fazer uma cópia deles antes de fazer as substituições de texto. Só precisa de introduzir os seus textos e, antes de iniciar a substituição, assinalar o botão de Cópia de segurança. Se quiser personalizar a extensão dos ficheiros de cópias de segurança, abra a janela de opções.

### Como Abrir um Ficheiro

Se quiser abrir um ficheiro que corresponda a algum dos seus textos, deverá seleccionar uma linha da janela do resultado e carregar nela com o &RMB;. Irá aparecer um menu, onde depois só terá de seleccionar uma opção dele.

### Comandos

Suponha que deseja substituir a frase "As aventuras de Alice no país das maravilhas" com o ficheiro inteiro que contém a obra de Carroll. Provavelmente, não o quererá fazer à mão, pelo que necessita aqui de um "comando" que o faça por si. Deste modo, carregue no botão adicionar, seleccione o "modo de procura e substituição" e introduza os seguintes textos: "As aventuras de Alice no país das maravilhas" no mini-editor de procura e o texto "[$loadfile:`/local-da-minha-pasta/minha-pasta/meu-ficheiro`$]" no mini-editor de substituição. Carregue no botão Ok; nessa altura, quando voltar à janela principal do &kfilereplace;, carregue no botão da acção de comando que activa os comandos, iniciando a substituição. Estão presentes outros comandos; veja por favor o Apêndice B para obter uma lista com os comandos disponíveis.

## Créditos e Licença

&kfilereplace;. Programa copyright 1999 por François Dupoux dupoux@dupoux.com, 2003 Andras Mantia amantia@kde.org, 2004 Gulmini Emiliano emi_barbarossa@yahoo.it

## Os autores e equipa de manutenção do &kfilereplace;:

François Dupoux dupoux@dupoux.com

- Autor original

Andras Mantia amantia@kde.org

- Autor da 'shell', criador da KPart, co-manutenção

Emiliano Gulmini emi_barbarossa@yahoo.it

- Manutenção actual, limpeza e reescrita de código

Documentação com 'copyright' 2004 de Emiliano Gulmini emi_barbarossa@yahoo.it

Tradução de Pedro Morais morais@kde.org

&underFDL; &underGPL;

## Instalação e Compilação

&install.intro.documentation; &install.compile.documentation;

### Requisitos

Para poder usar o comando [$mathexp:`uma_expressao_matematica`$], deverá instalar o utilitário matemático 'bc' (versão 1.06 ou posterior), que é da autoria de Philip A. Nelson(philnelson@acm.org).

## Comandos do &kfilereplace;

[$datetime:iso$] [$datetime:local$] [$user:uid$] [$user:gid$] [$user:loginname$] [$user:fullname$] [$user:homedir$] [$user:shell$] [$loadfile:`/local/pasta/o-meu-ficheiro`$] [$empty:$] [$random:`UM_NUMERO_INTEIRO`$] [$random:$] [$mathexp:`expressão-do-bc`$]
- este comando devolve a data e hora actuais no formato ISO do &Qt;. como o anterior, mas no formato local. devolve o UID do utilizador actual. devolve o GID do utilizador actual. devolve o nome do utilizador actual. devolve o nome completo do utilizador actual. devolve a pasta pessoal do utilizador actual. devolve a linha de comandos do utilizador actual. devolve o conteúdo do ficheiro meu-ficheiro. devolve um texto vazio. devolve um número aleatório, usando o UM_NUMERO_INTEIRO como raiz inicial dos números aleatórios. como o anterior, mas sem raiz inicial. devolve o resultado de uma expressão matemática do &bc; v1.06.

&documentation.index;