# Manual do &kabcclient;

## Introdução

O &kabcclient; é uma interface para a linha de comando do livro de endereços do &kde;. Permite-lhe listar, procurar, inserir, remover ou mesclar contatos através da linha de comando ou de uma linguagem de programação. O &kabcclient; pode lidar com uma grande variedade de formatos de entrada ou de 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 contatos no livro de endereços do &kde;

Funcionalidades principais do &kabcclient;:

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

- Procurar por contatos que correspondam aos dados inseridos

- Inserir (adicionar) contatos

- Remover (apagar) contatos

- Mesclar (modificar) os contatos 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 efetuar pesquisas no livro de endereços do usuário, nem sequer é esta a intenção dos autores. Todos esses processamentos poderão ser efetuados a partir de outras ferramentas da linha de comando 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.

## Recursos

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

Irá aprender como inserir, apagar e procurar por dados de contatos, 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 contatos no livro de endereços do &kde;, escrevendo os dados para o 'standard output' do programa. A quantidade e formato dos resultados de saída irá depender do formato escolhido.

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

    % kabcclient -L

Para obter apenas uma linha por contato, ⪚, para contagens, basta executar:

    % kabcclient -L -of UID

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

    % kabcclient --list -of e-mail

### Procurar por contatos correspondentes aos dados inseridos

O &kabcclient; pode retirar os dados da linha de comando ou a partir do 'standard input' do programa, verificando as suas semelhanças com todos os contatos no livro de endereços do &kde;. A pesquisa é o modo padrão, mas isto poderá ser selecionado de forma explícita com os argumentos da linha de comando `--search` ou `-S`.

No exemplo a seguir, todos os contatos que tenham `joão` como parte de qualquer campo de nome ou endereço de e-mail serão impressos no 'standard output' do programa, formatados como vCards (uma vez que este é o valor padrão da opção `--output-format`):

    % kabcclient --search joão

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

    % echo joão | kabcclient --search

A pesquisa com distinção de maiúsculas poderá ser ativada ou desativada com a opção `--match-case`.

### Adicionando contatos

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

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

    % kabcclient --add --input-format e-mail "João da Silva <joao.silva@exemplo.com.br>"

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

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

### Removendo contatos

O &kabcclient; suporta a remoção de contatos do livro de endereços do &kde;, utilizando o argumento da linha de comando `--remove` ou `-R`. Os dados de entrada são basicamente uma pesquisa para procurar os itens a remover. Em caso de sucesso, os contatos resultantes serão apresentados no 'standard output' do programa. Uma vez 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, você não poderá voltar atrás! Em outras palavras, quando apagar um contato, não poderá anular a remoção; ele será removido em definitivo.

Para testar a remoção de todos os contatos que tenham `joão` em qualquer campo do nome do contato ou do seu e-mail:

    % kabcclient --remove --nosave joão

### Formatos de Entrada e Saída

O &kabcclient; pode interpretar os dados de entrada e formatar os dados de saída, de acordo com várias regras de formatação. Dependendo do cenário de utilização atual, 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.

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

Todas estas opções da linha de comando 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 contatos e, como tal, poderá apresentar todas as informações que outros aplicativos de livros de endereços, como o &kaddressbook;, podem acessar. Como tal, é o formato padrã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 contato 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 contatos com colunas do CSV, poderão ser usados os arquivos de descrição de modelos CSV do &kaddressbook;.

## Argumentos da linha de comando

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

Opção | Descrição
`--help, --help-all` | Mostra ajuda sobre as opções do programa.
`--author` | Mostra informações sobre o 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 fato. Não altera nada no livro de endereços do &kde;; não remove, insere ou modifica nenhum dos contatos.
`--match-case` | Use a pesquisa com distinção de maiúsculas/minúsculas, caso queira comparar os dados inseridos com os contatos no livro de endereços.
Modos Principais de Operação:
`-L, --list` | Imprime todos os contatos no formato de exportação indicado.
`-A, --add` | Insere contatos no livro de endereços.
`-R, --remove` | Remove contatos do livro de endereços.
`-M, --merge` | Mescla os dados de entrada com os contatos correspondentes no livro de endereços.
Formatação e Codificação:
`-if, --input-format` `formato` | Como interpretar os dados de entrada. Use o `help` para obter uma lista com os valores disponíveis.
`-of, --output-format` `formato` | Como formatar os dados de 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 de 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 de 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 de saída. Use o `help` para obter uma lista com os valores disponíveis.

## Perguntas e respostas

&reporting.bugs; &updating.documentation;

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

Nenhum.

Quais são os nomes do aplicativo &kabcclient;?

O nome do aplicativo &kabcclient; é kabcclient.

Como 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 Marcus Gama marcus.gama@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 separadamente.

### Requisitos

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

Você pode encontrar uma lista de modificações no arquivo `ChangeLog`.

### Configuração

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

&documentation.index;