# O Manual do &kabcclient;

## Introdução

O &kabcclient; é uma interface para a linha de comandos do livro de endereços do &kde;. Permite-lhe listar, procurar, inserir, remover ou reunir contactos através da linha de comandos ou de uma linguagem de programação. O &kabcclient; pode lidar com uma grande variedade de formatos à entrada ou à saída, permitindo a sua utilização para a importação ou exportação de livros de endereços do &kde; inteiros.

Quando é invocado sem argumentos, o &kabcclient; será colocado no modo de pesquisa e tentará corresponder todo o texto que possa ler do 'standard input' com os itens de contactos no livro de endereços do &kde;

Funcionalidades principais do &kabcclient;:

- Listar todos os contactos do livro de endereços do &kde;

- Procurar por contactos que correspondam aos dados introduzidos

- Inserir (adicionar) contactos

- Remover (apagar) contactos

- Reunir (modificar) os contactos correspondentes com os dados novos

O &kabcclient; não é outra interface gráfica para o livro de endereços do &kde; (i.e. &kaddressbook;). O &kabcclient; pretende apenas ser usado quando não é prático ou possível a utilização de uma interface gráfica.

O &kabcclient; não oferece uma linguagem de programação completa para efectuar pesquisas sobre o livro de endereços do utilizador, nem sequer é tal a intenção dos autores. Todos esses processamentos poderão ser efectuados a partir de outras ferramentas da linha de comandos ou das capacidades da própria linguagem de programação do programa.

Para facilitar a descoberta das suas capacidades, qualquer opção que necessite de argumentos poderá ser invocada com o valor `help`. Isto irá então apresentar todos os valores válidos que possam ser passados a essa opção.

## Características

Neste capítulo, irá conhecer as funcionalidades principais do &kabcclient; e saber como controlá-las com os parâmetros da linha de comandos (lembre-se que o &kabcclient; não é uma interface gráfica; é um programa apenas para a linha de comandos).

Irá aprender como inserir, apagar e procurar por dados de contactos, assim como usar diferentes formatos para a entrada e para a saída.

### Listar o livro de endereços

Este é o modo mais básico de operação, sendo iniciado com a opção `--list` ou `-L`. O &kabcclient; irá listar todos os contactos no livro de endereços do &kde;, escrevendo os dados para o 'standard output' do programa. A quantidade e formato dos resultados à saída irá depender do formato escolhido.

Para listar todos os contactos como itens em vCard-padrão, basta executar:

    % kabcclient -L

Para obter apenas uma linha por contacto, p.ex. para contagens, basta executar:

    % kabcclient -L -of UID

No exemplo seguinte, serão listados todos os endereços de e-mail:

    % kabcclient --list -of e-mail

### Procurar por contactos correspondentes aos dados introduzidos

O &kabcclient; pode retirar os dados da linha de comandos ou a partir do 'standard input' do programa, verificando as suas semelhanças com todos os contactos no livro de endereços do &kde;. A pesquisa é o modo por omissão, mas podê-lo-á escolher de forma explícita com os argumentos da linha de comandos `--search` ou `-S`.

No exemplo seguinte, todos os contactos que tenham `josé` como parte de qualquer campo de nome ou endereço de e-mail serão impressos no 'standard output' do programa, formatados como vCards (dados que este é o valor por omissão da opção `--output-format`):

    % kabcclient --search josé

A mesma pesquisa de novo, só que desta vez o texto a procurar é lido do 'standard input' do programa:

    % echo josé | kabcclient --search

Poderá activar ou desactivar a pesquisa com distinção de maiúsculas com a opção `--match-case`.

### Adicionar contactos

O &kabcclient; suporta a adição de contactos novos ao livro de endereços do &kde;, utilizando o argumento da linha de comandos `--add` ou `-A`. Os dados poderão ser passados como argumentos adicionais da linha de comandos ou lidos a partir do 'standard input'. Em caso de sucesso, os contactos resultantes serão apresentados no 'standard output' do programa. Dado que esta é uma operação que aplica alterações ao livro de endereços, poderá ser executada num modo de "Execução de testes" com a opção `--nosave`.

Adicione um contacto com o nome e o e-mail, interpretando um argumento adicional da linha de comandos como dados de entrada:

    % kabcclient --add --input-format e-mail "Zé Povinho <ze.povinho@exemplo.com>"

Para adicionar todos os contactos de um ficheiro vCard em sequência para o 'standard input' do programa:

    % cat ficheiro-exemplo.vcf | kabcclient --add --input-format vcard

### Apagar contactos

O &kabcclient; suporta a remoção de contactos do livro de endereços do &kde;, utilizando o argumento da linha de comandos `--remove` ou `-R`. Os dados de entrada são basicamente uma pesquisa para procurar os itens a remover. Em caso de sucesso, os contactos resultantes serão apresentados no 'standard output' do programa. Dado que esta é uma operação que aplica alterações ao livro de endereços, poderá ser executada num modo de "Execução de testes" com a opção `--nosave`.

Quando apagar algo do livro de endereços, não poderá voltar atrás! Por outras palavras, quando apagar um contacto, não poderá anular a remoção; será removido em definitivo.

Para testar a remoção de todos os contactos que tenham `josé` em qualquer campo do nome do contacto ou do seu e-mail:

    % kabcclient --remove --nosave josé

### Formatos de Entrada e Saída

O &kabcclient; pode interpretar os dados à entrada e formatar os dados à saída, de acordo com várias regras de formatação. Dependendo do cenário de utilização actual, certas combinações poderão representar o resultado mais útil. Alguns dos formatos aceitam parâmetros adicionais, de modo a personalizar ainda mais o seu comportamento.

Dado que os dados textuais poderão ser codificados, tanto a entrada como a saída poderão estar sujeitos a descodificações ou codificações, respectivamente.

Todas estas opções da linha de comandos irão reagir ao valor especial `help`, que irá listar os valores permitidos.

#### Formato do vCard

O vCard (RFC 2426) é o formato-padrão para os dados de contactos e, como tal, poderá apresentar todas as informações que outras aplicações de livros de endereços, como o &kaddressbook;, podem aceder. Como tal, é o formato por omissão para a formatação de saída.

#### Formato "Comma-Separated Values" (CSV)

O formato de valores separados por vírgulas (CSV) poderá ser usado como formato de entrada para preencher os dados em campos específicos de um item de contacto e como um formato de saída para reduzir ou reordenar os dados para processamentos futuros. Para permitir um mapeamento mais flexível dos campos de contactos com colunas do CSV, poderá usar os ficheiros de descrição de modelos CSV do &kaddressbook; para esse fim.

## Argumentos da Linha de Comandos

O &kabcclient; suporta as seguintes opções:

Opção | Descrição
`--help, --help-all` | Mostra ajuda acerca das opções do programa.
`--author` | Mostra informações acerca do autor do programa.
`-v, --version` | Mostra informações da versão do programa.
`--license` | Mostra informações da licença do programa.
`--verbose` | Imprime mensagens úteis durante a execução.
`--nosave` | Imprime o que seria feito, mas não executa nada de facto. Não altera nada de todo no livro de endereços do &kde;; não remove, insere ou modifica nenhuns dos contactos.
`--match-case` | Use a pesquisa com distinção de maiúsculas/minúsculas, caso queira comparar os dados introduzidos com os contactos no livro de endereços.
Modos Principais de Operação:
`-L, --list` | Imprime todos os contactos no formato de exportação indicado.
`-A, --add` | Insere contactos no livro de endereços.
`-R, --remove` | Remove contactos do livro de endereços.
`-M, --merge` | Junta os dados à entrada com os contactos correspondentes no livro de endereços.
Formatação e Codificação:
`-if, --input-format` `formato` | Como interpretar os dados à entrada. Use o `help` para obter uma lista com os valores disponíveis.
`-of, --output-format` `formato` | Como formatar os dados à saída. Use o `help` para obter uma lista com os valores disponíveis.
`-if-opts, --input-format-options` `opções` | Define um conjunto de opções de personalização específicas do formato de entrada. Use o `help` para obter uma lista dos valores disponíveis.
`-of-opts, --output-format-options` `opções` | Define um conjunto de opções de personalização específicas do formato à saída. Use o `help` para obter uma lista dos valores disponíveis.
`-ic, --input-codec` `codificação` | A codificação de texto usada para apresentar os dados à entrada. Use o `help` para obter uma lista com os valores disponíveis.
`-oc, --output-codec` `codificação` | A codificação de texto usada para apresentar os dados à saída. Use o `help` para obter uma lista com os valores disponíveis.

## Perguntas e Respostas

&reporting.bugs; &updating.documentation;

Que ficheiros de configuração usa o &kabcclient;?

Nenhum.

Quais são os nomes da aplicação &kabcclient;?

O nome da aplicação &kabcclient; é kabcclient.

Como é que posso adicionar a minha dúvida a esta FAQ?

Envie as suas questões para kevin.krammer@gmx.at.

## Créditos e Licença

&kabcclient; Programa com 'copyright' 2005-2008:

- Kevin Krammer kevin.krammer@gmx.at

Documentação com 'copyright' de 2008:

- Kevin Krammer kevin.krammer@gmx.at

Tradução de José Nuno Pires zepires@gmail.com

&underFDL; &underGPL;

## Instalação

### Como obter o &kabcclient;:

&install.intro.documentation;

O &kabcclient; vem incluído no &kde;4 e não está disponível em separado.

### Requisitos

O &kabcclient; necessita de ter instaladas as seguintes bibliotecas-padrão do &kde; (o pacote `kdelibs` e o `kdepimlibs`). Para compilar a partir do código-fonte, também precisa do &Qt; e dos pacotes de desenvolvimento `kdelibs` e `kdepimlibs`.

Pode encontrar uma lista de modificações no ficheiro `ChangeLog`.

### Configuração

Não é necessária nenhuma configuração especial para ter o &kabcclient; a executar no ambiente de trabalho do &kde;.

&documentation.index;