Scripting
*********

Many of khard’s subcommands can be used for scripting purposes.  The
commands "list", "birthdays", "email", "phone" and "postaddress"
feature a "--parsable" option which changes the output to be tab
separated (normally the fields are visually aligned with spaces).
They list several contacts at once.  If the search terms are known to
match one single contact the command "khard show --format=yaml" can
also be used for scripting.  It produces the contact in the yaml
format that is also used for editing.  But if the search terms produce
more than one result the "show" command first asks the user to select
one contact which is unsuitable for scripting.


Specifying output fields
========================

The "list" command additionally features a "--fields"/"-F" options
which allows to specify the fields of a contact that should be
printed.  The list of supported field names can be seen with "khard
list -F help".

Some fields can hold complex data structures like mappings and lists.
These can be specified by dot-subscripting the field name.  Lists are
subscribed with numbers starting at zero.  Subscripting can be nested.

If the contact for somebody would contain several email addresses for
example:

   $ khard list --fields emails somebody
   Emails
   {'work': ['work@example.org'], 'home': ['some@example.org', 'body@example.org']}

One could access these with different nested field descriptions like
this:

   $ khard list --fields emails.work somebody
   Emails
   ['work@example.org']
   $ khard list --fields emails.home.1 somebody
   Emails
   body@example.org


Integration
***********

Khard can be used together with email or SIP clients or a
synchronisation program like vdirsyncer.  For synchronisation programs
it is important to note that khard expects the contacts in the
configured address book directories to be stored in individual files.
The files are expected to have a ".vcf" extension.

If you already have ".vcf" files containing multiple "VCARD" entries
(i.e. from Android/MacOS Contacts app), below are some scripts that
generate the corresponding single entry ".vcf" files:

* vcardtool (processes one input file at a time)

* vcf-splitter (needs to be used with the "-u"/"--uid" flag to
  generate the required UID entry)

You might need to preparse your ".vcf" input files with vcard2to3 if
they contain "VERSION:2.1" entries.


vdirsyncer
==========

Make sure to write the contacts into individual files as "VCARD"
records and give them a ".vcf" file extension:

   [storage local_storage_for_khard]
   type = "filesystem"
   fileext = "vcf"
   path = "..."


mutt
====

Khard may be used as an external address book for the email client
mutt. To accomplish that, add the following to your mutt config file
(mostly "~/.mutt/muttrc"):

   set query_command = "khard email --parsable %s"
   bind editor <Tab> complete-query
   bind editor ^T    complete

Then you can complete email addresses by pressing the Tab-key in
mutt’s new mail dialog. If your address books contain hundreds or even
thousands of contacts and the query process is very slow, you may try
the "--search-in-source-files" option to speed up the search:

   set query_command = "khard email --parsable --search-in-source-files %s"

If you want to complete multi-word search strings like “john smith”
then you may try out the following instead:

   set query_command = "echo %s | xargs khard email --parsable --"

To add email addresses to khard’s address book, you may also add the
following lines to your muttrc file:

   macro index,pager A \
     "<pipe-message>khard add-email<return>" \
     "add the sender email address to khard"

If you want to search for email addresses in specific header fields,
append the “–header” parameter:

   macro index,pager A \
     "<pipe-message>khard add-email --headers=from,cc --skip-already-added<return>" \
     "add the sender and cc email addresses to khard"

Then navigate to an email message in mutt’s index view and press “A”
to start the address import dialog.


Alot
====

Add the following lines to your alot config file:

   [accounts]
     [[youraccount]]
       [[[abook]]]
         type = shellcommand
         command = khard email --parsable
         regexp = '^(?P<email>[^@]+@[^\t]+)\t+(?P<name>[^\t]+)'
         ignorecase = True


Twinkle
=======

For those who also use the SIP client twinkle to take phone calls,
khard can be used to query incoming numbers. The plugin tries to find
the incoming caller id and speaks it together with the phone’s ring
tone. But it is more or less a proof of concept - feel free to extend.

The plugin needs the following programs:

   sudo aptitude install ffmpeg espeak sox mpc

sox and ffmpeg are used to cut and convert the new ring tone and
espeak speaks the caller id.  mpc is a client for the music player
daemon (mpd). It’s required to stop music during an incoming call.
Skip the last, if you don’t use mpd. Don’t forget to set the
“stop_music”-parameter in the "config.py" file to "False", too.

After the installation, copy the scripts and sounds folders to your
twinkle config folder:

   cp -R misc/twinkle/* ~/.twinkle/

Next convert the sound samples to wave:

   ffmpeg -i incoming_call.ogg incoming_call.wav
   ffmpeg -i outgoing_call.ogg outgoing_call.wav
   ffmpeg -i ringtone_segment.ogg ringtone_segment.wav

Then edit your twinkle config file (mostly "~/.twinkle/twinkle.cfg")
like this:

   # RING TONES
   # We need a default ring tone. Otherwise the phone would not ring at all, if
   # something with the custom ring tone creation goes wrong.
   ringtone_file=/home/USERNAME/.twinkle/sounds/incoming_call.wav
   ringback_file=/home/USERNAME/.twinkle/sounds/outgoing_call.wav

   # SCRIPTS
   script_incoming_call=/home/USERNAME/.twinkle/scripts/incoming_call.py
   script_in_call_answered=
   script_in_call_failed=/home/USERNAME/.twinkle/scripts/incoming_call_failed.py
   script_outgoing_call=
   script_out_call_answered=
   script_out_call_failed=
   script_local_release=/home/USERNAME/.twinkle/scripts/incoming_call_ended.py
   script_remote_release=/home/USERNAME/.twinkle/scripts/incoming_call_ended.py


Zsh
===

The file "misc/zsh/_khard" contains a khard cli completion function
for the zsh and "misc/zsh/_email-khard" completes email addresses.

Install by copying to a directory where zsh searches for completion
functions (the "$fpath" array). If you, for example, put all
completion functions into the folder "~/.zsh/completions" you must add
the following to your zsh main config file:

   fpath=( $HOME/.zsh/completions $fpath )
   autoload -U compinit
   compinit


sdiff
=====

Use the wrapper script "misc/sdiff/sdiff_khard_wrapper.sh" if you want
to use sdiff as your contact merging tool. Just make the script
executable and set it as your merge editor in khard’s config file:

   merge_editor = /path/to/sdiff_khard_wrapper.sh


Davcontroller
=============

Khard also contains a helper script called davcontroller. It’s
designed to create and remove address books and calendars at the
server. I have created davcontroller cause my previously used CalDAV
server (Darwin calendarserver) offered no simple way to create new
address books and calendars. But davcontroller should be considered as
a hacky solution and it’s only tested against the Darwin
calendarserver. So if your CalDAV server offers a way to create new
address books and calendars I recommend to prefer that method over
davcontroller.

If you nonetheless want to try davcontroller, you have to install the
CalDAVClientLibrary first. Unfortunately that library isn’t compatible
to python3 so you have to create an extra python2 virtual environment
and install in there:

   # create python2 virtual environment
   virtualenv -p python2 ~/.virtualenvs/davcontroller
   # get library from svn repository
   sudo aptitude install subversion
   svn checkout http://svn.calendarserver.org/repository/calendarserver/CalDAVClientLibrary/trunk CalDAVClientLibrary
   cd CalDAVClientLibrary
   # install library
   ~/.virtualenvs/davcontroller/bin/python setup.py install
   # start davcontroller script
   ~/.virtualenvs/davcontroller/bin/python /path/to/khard-x.x.x/misc/davcontroller/davcontroller.py

This small script helps to create and remove new address books and
calendars at the carddav and caldav server.

List available resources:

   davcontroller -H example.com -p 11111 -u USERNAME -P PASSWORD list

Possible actions are: list, new-addressbook, new-calendar and remove.
After creating or removing you must adapt your vdirsyncer config.
