# KABC Client - Usage examples

- List
- Search
- Add
- Remove
- Merge

If you have interesting use cases or scripts using kabcclient, let me know about it!

## Examples for list

Export all contacts to a vcard file

        kabcclient --list -of vcard -oc UTF8 > exported-contacts.vcf

This can be written even shorter because of the defaults for output format and output codec and the shorter form of the --list command

        kabcclient -L > exported-contacts.vcf

vcard is the default output format as it can contain all data for a addressbook entry. UTF8 is the default encoding for vcard because the VCard specification requests that.
However, if you need a different encoding, for example because another program doesn't understand UTF-8, you can always override the default choice.
Same example but encode output in the local encoding:

        kabcclient --list -oc LOCAL > exported-contacts.vcf

## Examples for search

### Simple searches

Search for contacts contacts that have "john" in either name or email addresses:

        kabcclient -S john

Doing the same but read from stdin:

        echo "john" | kabcclient -S

Both variants use a couple of option defaults. The full commandline, but still using -S instead of search's long form --search, would look like this

        kabcclient -if search -ic LOCAL -of vcard -oc UTF8 -S john

search is a special input format parser, which will apply the input text to both name and email fields so either can match contacts in the addressbook.
As discussed under examples for list default for output is vcard in combination with UTF8

### Matching options

Matching is case insensitive by default, i.e. the input "john" and the input "John" will result in the same output.
In case you want to switch text matching to case sensitive, add the commandline switch --match-case:

        kabcclient --match-case -S John

### Advanced searches

Searching for more than one name is as simple as adding them to the commandline:

        kabcclient -S John Jane Bob

This start a search for "John", then search for "Jane" and finally search for "Bob".
When reading from stdin the search input format parser, like most other input format parsers as well, assumes that each line is a separate search, or in other words that one line is one lookup string:

        echo "John Bob" | kabcclient -S

Will look for someone called "John Bob", while

        ( echo "John" ; echo "Bob" ) | kabcclient -S

will first look for all "Johns" and the for all "Bobs"

A more realistic input situation would be this

        kabcclient -S

Called like this, or even without the -S as search is the default operation, will let kabcclient wait for input directly from the terminal it runs on, i.e. each line you type will trigger a search for it.

### Output customization

The full VCard data of a contact might be too much, for example we could be only interested in poeple's emails:

        kabcclient -of email -S John

This will list the primary email address of all "Johns" in the addressbook.
To get not just the primary email address per contact but all available addresses, the additional output format options can be put to use:

        kabcclient -of email -of-opts allemails -S John

In cases where more than one "John" is in the addressbook, this can easily make it impossible to know which email address belongs to which "John".
But fortunately the email output knows a second option:

        kabcclient -of email -of-opts allemails,withname -S John

Multiple options are separated by commas. To get a list and description of the available format options, just use help as the parameter instead:

        kabcclient -of email -of-opts help

## Examples for add

### Operation basics

The add operation really adds entries to the addressbook, i.e. if the input is one of the entries which are already in the addressbook, you will have a duplicate.
The advantage is that is will not overwrite any data currently in the addressbook.
Add requires a input format to be specified because the default input format search isn't a good choice for this kind of operation.

Adding a new contact based on the name and email address as commonly formatted by email programs:

        kabcclient -if email --add "Marilyn Monroe <mmonroe@moviestars.com>"

Of course the possibilty to read from stdin still applies:

        echo "Marilyn Monroe <mmonroe@moviestars.com>" | kabcclient -if email --add

Output of both commands will be the VCard representation of the contact data (default output format being vcard as discussed in examples for list)

### Using the add operation as an format converter

A variant of the above exmple is to use kabcclient as a VCard converter:

        echo "Marilyn Monroe <mmonroe@moviestars.com>" | kabcclient -if email --nosave --add

The --nosave option keeps the new contact entry from actually being written to the addressbook's permanent location, e.g. the standard addressbook file, so the only affect the command has is to read the provided name and email combination and write the resulting contact to stdout, which, as shown above, is formatted by the vcard output format

### Importing previously exported contacts

Consider you have exported all your contacts to a VCard file on one machine:

        kabcclient --list > contacts.vcf

and you want to import them on a different machine or on a different user account:

        cat contacts.vcf | kabcclient -if vcard -A

Remember that this will not overwrite any data of the target addressbook but might lead to duplicate entries.

## Examples for remove

### Operation basics

The remove operation deletes contacts from the addressbook, unless the --nosave option keeps it from actually writing the changes to the permanent addresbook location.
As an additional safety measure, remove will only delete contacts that match unambiguoulsy, i.e. if more than one contact matches none of them is deleted.
Any deleted contact is written to stdout

Trying to remove contact data for "John" from the addressbook:

        kabcclient -R John

As explained in the examples for search the input "John" will be used by the default input format parser search for matching against name and email addresses of contacts in the addressbook and matches will be case insensitive.
Depending on the number of "John" occurences in the addressbook, this might not yield an unambiguous match, thus resulting in no contact being deleted.

### Better input for more exact matching

By providing more information about the contact to remove, the chance of getting a clear single match increases:

        kabcclient -if email -R "John Meyer <jmeyer@somecompany.com>"

Using the email input format parser provides name and email to match against possible candiates from the addressbook.

The best possible matching criteria is provided by the uid input format parser.
An UID is a unique identifier created by the addressbook itself, thus matching exactly just one contact entry.
UIDs can be retrieved by using other operations, e.g. --list and --search, using the uid output format:

        kabcclient -of uid -L > all-uids.txt

        cat one-uid.txt | kabcclient -if uid -R

As a consequence the following command sequence would empty the whole addressbook if the --nosave option would not be present:

        kabcclient -of uid -L | kabcclient -if uid --nosave -R

## Examples for merge

### Operation basics

The merge operation is quite similar to the add operation, but instead of adding new contact entries to the addressbook, it tries to add the new data to already existing contacts.
As a result it requires unambiguous matches like the remove operation.

As merging information results in changes to the addressbook, the --nosave switch can be used to just test the results some input data would have on the addressbook contacts.
For each successull match kabcclient will write the merged contact data to stdout, just like it would for new entries when using add.
As the program needs both something to match and some data to add, simple input formats like name won't be very effective.

### Adding additional e-mail addresses

Assuming that a person's name is enought information to find a single matching contact in the addressbook, the following example will add the given e-mail address unless it is already part of the contacts data:

        kabcclient -if email -M "John Meyer <jmeyer@somecompany.com>"

More effective merge operations can be conducted by using the vcard or csv input formats.

### Merging backups into current addressbook

As discussed in the examples for remove the best matching is provided by the UIDs the addressbook generates to uniquely identify contacts.
Assume that a backup of the contacts has been creates using the list operation and other kinds of access have corrupted parts of the contacts in the addressbook.

        cat exported-contacts.vcf | kabcclient -if vcard -M

Data that is present for contacts in the input file but not present for the respective contact in the addressbook will be added to the one in the addressbook.

Author: Kevin Krammer, 8010 Graz, Austria