kde-playground/kdepim/console/kabcclient/README

kabcclient - A commandline client for accessing the KDE addressbook KABC
========================================================================

The application has actually a second personality. If it is started with the
name kabc2mutt, e.g. a symbolic link named kabc2mutt pointing to kabcclient,
it tries to react like that equally named application by Tobias König
<tokoe AT kde DOT org>.

This document describes the main personality.


========
Contents
========
1. Design: How it works
2. Operations: What it can do
3. Usage: How it can be adjusted
4. Usage examples: How it can be used (see also doc/examples.html)

1. Design
---------

The client can operate in call-and-return fashion and in filter-in-stream
fashion, i.e. input values can be given as commandline paramaters or
being read from stdin.

Parameters from the commandline are written into a std::stringstream to
allow uniform access to the input later on.

All input is processed by an input format filter, which creates a
KABC::Addressee object for every item it can treat separately according
to the formatting/parsing rules it implements.

Base rule is one item per line of input, unless the input format is multiline
in nature, e.g. vCard.

Matching is tried for UID, realName() and emails(), can be case sensitive
(case insensitive is default) and the search text only has to be included
in the target's data, i.e. no exact match necessary, unless the compared
field is UID.

The chosen operation is performed for each item individually.
While this increases the number of addressbook traversals it allows to
continually process input from stdin.

Output of operations is written to stdout, formatted by an output format
filter.
This allows to accommodate different needs for details, ranging from
UID to full vCard.

Filters can offer options to further tailor their work.

All operations that modify the addressbook can be run in "simulation mode",
i.e. the carry out their work as usual but changes are not saved.

Input and output can be processed by a text codec in case the input isn't
encoded in the default encoding for the current locale settings, or
if an output to the current encoding would loose information, e.g.
vcards for contacts with different locales.

2. Operations
-------------

* List all entries in the addressbook
* Search in the addressbook
* Add entries to the addressbook
* Remove entries from the addressbook
* Merge new data into the addressbook

The return code is 0 on success and a different value on failure.
Exact value depends on the operation. 1 indicates a common problem, e.g.
input stream went bad.

2.1. List
---------
Listing is the simplest operation. It just gets all addressees from the
standard addressbook and writes them to stdout.

The associated commandline switch is --list

2.2. Search
-----------

Is the operation with the highest precedence, i.e. if another operation mode
commandline switch is present, search operation is performed.
It is also the default opertation, i.e. no other operation mode's commandline
switch is given.

The associated commandline switch is --search
Using the optional switch --match-case makes the search case sensitive.

Returns 2 if no input item resulted in at least one match.

2.3. Add
--------

Allows to add new entries to the addressbook.
If the input filter read an UID it will be used for unless the same UID is
already used by the addressbook to make sure the operations doesn't
accidentally overwrite data.

All added entries are written to stdout.

The associated commandline switch is --add
Using the optional switch --nosave makes all adds only to the in-memory
addressbook and does not call KABC::AddressBook:save

Returns 2 if no items were available for adding.
Returns 3 if saving fails.

2.4. Remove
-----------

This is the operation with the lowest precedence as it potentially can cause
the most damage. So it will only be used if it is the only specified operation
mode.

More or less works like search in that it matches input items against the
addressbook.
However it only removes items which are the only single match for the
respective input.

Writes the deleted addressee to stdout.

The associated commandline switch is --remove
Using the optional switch --nosave makes all adds only to the in-memory
addressbook and does not call KABC::AddressBook:save

Returns 2 if no items could be removed.
Returns 3 if saving fails.

2.5. Merge
-----------

This operation has next lowest precedence, i.e. if both Remove and Merge are
specified Merge will be used.

Works like a mixture between Add and Remove as it operates only on unambiguous
matches like Remove but appends data like Add.

Data from the input is merged with the already present data, i.e. new things
are appended while already present information is not duplicated.

Only useful with input formats that can provide something to match with
and some information to add, for example email (adding email address using name
for matching) or vcard.

Writes the merged addressee to stdout.

The associated commandline switch is --merge
Using the optional switch --nosave makes all adds only to the in-memory
addressbook and does not call KABC::AddressBook:save

Returns 2 if no items could be merged.
Returns 3 if saving fails.

3. Usage
--------

The application understands the standard --help option for printing a general
usage information.

Aside from the operation mode switches --list, --search, --add and --remove,
the case matching switch --match-case and the simulation mode switch --nosave,
it has a couple of switches with parameters for the input and output filtering.

-if or --input-format
specifies which input format interprets the input data

-of or --output-format
specifies which output format is applied to resulting addressee objects

-if-opts or --input-format-options
specifies optional format parameters. Might not be available for all input filters
(currently no input format uses that)

-of-opts or --output-format-options
specifies optional format parameters. Might not be available for all output filters

Each of those options understands the 'help' parameter, which makes it list
all its available options and results in applications after possible other
help parameters have been processed.

4. Usage examples
-----------------

#> kabcclient -if help -of help
List all available input and output formats

#> kabcclient -of email -of-opts help
List all options for the output format 'email'

#> kabcclient -oc help -ic help
List codec help information for both input and output codec

#> kabcclient --list -of email
Lists all addressbook entries using the email output format, encoding
the output in the locale specific text encoding

#> kabcclient --list -oc utf8
Lists all addressbook entries using the default output format vcard,
encoding the output in UTF-8 (8 bit Unicode) as expected for vCards.

#> kabcclient --search kde
Searches the addressbook for names or email addresses containing kde.
Matches are performed case insensitive.
Writes all matches to stdout using the default output format (vcard),
encoding it in UTF-8. While locale specific encoding is the default
UTF-8 is the override default when using vcard format.

#> kabcclient kde
Equivalent to the above as --search is the default operation

#> kabcclient --match-case --search kde
Like above but perform matches case sensitive.

#> echo "kde" | kabcclient --search --match-case
Like above but read input from stdin

#> kabcclient -oc utf8 --search
Waits for input on stdin, using the local encoding to interpret the input text.
Performs a search for each line it reads and writes the matching entries to
stdout using the default output format (vcard), encoding the vcards in UTF-8

#> kabcclient -ic local -oc utf8 --search
Equal to the above as "local" is the default for encoding

#> kabcclient -ic "ISO 8859-1" -oc utf8 --search
Almost equal to the above in case, but interprets input as being encoded
in "ISO 8859-1" (aka Latin1, western european standard encoding).
In case the environment is set for this locale, this command the one above
result in identical behaviour.

#> kabcclient -of email -of-opts withname --search foo
Writes the preferred email of each match and decorates it with the
entry's name, e.g. John Doe <jdoe@foo.com>

#> kabcclient -of email --search foo
Like above but email address only, e.g. jdoe@foo.com

#> kabcclient --add -if email "Marilyn Monroe <mmonroe@moviestars.com>"
Adds a new entry to the addressbook using the input filter 'email' to interpret
the input text.
Input filter 'email' tries to parse this into name and address.
Writes resulting addressee object using the default output format (vcard)

#> kabcclient --add -if email --nosave "Marilyn Monroe <mmonroe@moviestars.com>"
Like above but does not save the changes

#> kabcclient --remove --nosave Marilyn
Removes the entry for Marilyn, provided it is the only match.
Does not save the change.
Writes the matching entry to stdout using the default output format (vcard)

#> kabcclient --remove --nosave --match-case Marilyn
Removes the entry for Marilyn, provided it is the only match, this time
case sensitive.
Does not save the change.
Writes the matching entry to stdout using the default output format (vcard)

#> kabcclient --remove --match-case Marilyn
Removes the entry for Marilyn, provided it is the only match, this time
also saves the change.
Writes the matching entry to stdout using the default output format (vcard)

#> kabcclient --merge -if email "Monroe, Marilyn <marilyn@monroe.info>"
Merges the additonal email address to the entry for Marilyn.
The name part of the input matches the entry in the addressbook, the
email part is the new information.
Writes the merged entry to stdout using the default output format (vcard)

#> kabcclient --search
Waits for input on stdin. Performs a search for each line it reads and writes
the matching entries to stdout using the default output format (vcard)

#> kabcclient
Equivalent to the above as --search is the default operation

#> kabcclient --list -of uid | kabcclient -if uid --remove
Removes all entries from the addressbook ;)

#> kabcclient --list | grep -E "(FN.*)|(TEL.*)" | sed s#FN:#\\nFN:#g | cut -d ':' -f 2
Lists call contacts and their telephone numbers. This serves as an example
on how to use kabcclient in a pipe&filter chain to extract any information
of interest from the vcard output, as this one contains all information
of a contact