1Scripting
2=========
3
4Many of khard's subcommands can be used for scripting purposes.  The commands
5``list``, ``birthdays``, ``email``, ``phone`` and ``postaddress`` feature a
6``--parsable`` option which changes the output to be tab separated (normally
7the fields are visually aligned with spaces).  They list several contacts at
8once.  If the search terms are known to match one single contact the command
9``khard show --format=yaml`` can also be used for scripting.  It produces the
10contact in the yaml format that is also used for editing.  But if the search
11terms produce more than one result the ``show`` command first asks the user to
12select one contact which is unsuitable for scripting.
13
14Specifying output fields
15------------------------
16
17The ``list`` command additionally features a ``--fields``/``-F`` options which
18allows to specify the fields of a contact that should be printed.  The list of
19supported field names can be seen with ``khard list -F help``.
20
21Some fields can hold complex data structures like mappings and lists.  These
22can be specified by dot-subscripting the field name.  Lists are subscribed with
23numbers starting at zero.  Subscripting can be nested.
24
25If the contact for somebody would contain several email addresses for example:
26
27.. code-block::
28
29  $ khard list --fields emails somebody
30  Emails
31  {'work': ['work@example.org'], 'home': ['some@example.org', 'body@example.org']}
32
33One could access these with different nested field descriptions like this:
34
35.. code-block::
36
37  $ khard list --fields emails.work somebody
38  Emails
39  ['work@example.org']
40  $ khard list --fields emails.home.1 somebody
41  Emails
42  body@example.org
43
44
45Integration
46===========
47
48Khard can be used together with email or SIP clients or a synchronisation
49program like `vdirsyncer`_.  For synchronisation programs it is important to
50note that khard expects the contacts in the configured address book directories
51to be stored in individual files.  The files are expected to have a ``.vcf``
52extension.
53
54.. _vdirsyncer: https://github.com/pimutils/vdirsyncer/
55
56vdirsyncer
57----------
58
59Make sure to write the contacts into individual files as ``VCARD`` records and
60give them a ``.vcf`` file extension:
61
62.. code-block:: ini
63
64    [storage local_storage_for_khard]
65    type = "filesystem"
66    fileext = "vcf"
67    path = "..."
68
69
70mutt
71----
72
73Khard may be used as an external address book for the email client mutt. To
74accomplish that, add the following to your mutt config file (mostly
75``~/.mutt/muttrc``):
76
77.. code-block::
78
79  set query_command = "khard email --parsable %s"
80  bind editor <Tab> complete-query
81  bind editor ^T    complete
82
83Then you can complete email addresses by pressing the Tab-key in mutt's new
84mail dialog. If your address books contain hundreds or even thousands of
85contacts and the query process is very slow, you may try the
86``--search-in-source-files`` option to speed up the search:
87
88.. code-block::
89
90  set query_command = "khard email --parsable --search-in-source-files %s"
91
92If you want to complete multi-word search strings like "john smith" then you
93may try out the following instead:
94
95.. code-block::
96
97  set query_command = "echo %s | xargs khard email --parsable --"
98
99To add email addresses to khard's address book, you may also add the following
100lines to your muttrc file:
101
102.. code-block::
103
104  macro index,pager A \
105    "<pipe-message>khard add-email<return>" \
106    "add the sender email address to khard"
107
108Then navigate to an email message in mutt's index view and press "A" to start
109the address import dialog.
110
111
112Alot
113----
114
115Add the following lines to your alot config file:
116
117.. code-block:: ini
118
119  [accounts]
120    [[youraccount]]
121      [[[abook]]]
122        type = shellcommand
123        command = khard email --parsable
124        regexp = '^(?P<email>[^@]+@[^\t]+)\t+(?P<name>[^\t]+)'
125        ignorecase = True
126
127
128Twinkle
129-------
130
131For those who also use the SIP client twinkle to take phone calls, khard can be used to query
132incoming numbers. The plugin tries to find the incoming caller id and speaks it together with the
133phone's ring tone. But it is more or less a proof of concept - feel free to extend.
134
135The plugin needs the following programs:
136
137.. code-block:: shell
138
139  sudo aptitude install ffmpeg espeak sox mpc
140
141sox and ffmpeg are used to cut and convert the new ring tone and espeak speaks
142the caller id.  mpc is a client for the music player daemon (mpd). It's
143required to stop music during an incoming call. Skip the last, if you don't use
144mpd. Don't forget to set the "stop_music"-parameter in the ``config.py`` file
145to ``False``, too.
146
147After the installation, copy the scripts and sounds folders to your twinkle
148config folder:
149
150.. code-block:: shell
151
152  cp -R misc/twinkle/* ~/.twinkle/
153
154Next convert the sound samples to wave:
155
156.. code-block:: shell
157
158  ffmpeg -i incoming_call.ogg incoming_call.wav
159  ffmpeg -i outgoing_call.ogg outgoing_call.wav
160  ffmpeg -i ringtone_segment.ogg ringtone_segment.wav
161
162Then edit your twinkle config file (mostly ``~/.twinkle/twinkle.cfg``) like
163this:
164
165.. code-block:: ini
166
167  # RING TONES
168  # We need a default ring tone. Otherwise the phone would not ring at all, if
169  # something with the custom ring tone creation goes wrong.
170  ringtone_file=/home/USERNAME/.twinkle/sounds/incoming_call.wav
171  ringback_file=/home/USERNAME/.twinkle/sounds/outgoing_call.wav
172
173  # SCRIPTS
174  script_incoming_call=/home/USERNAME/.twinkle/scripts/incoming_call.py
175  script_in_call_answered=
176  script_in_call_failed=/home/USERNAME/.twinkle/scripts/incoming_call_failed.py
177  script_outgoing_call=
178  script_out_call_answered=
179  script_out_call_failed=
180  script_local_release=/home/USERNAME/.twinkle/scripts/incoming_call_ended.py
181  script_remote_release=/home/USERNAME/.twinkle/scripts/incoming_call_ended.py
182
183
184Zsh
185---
186
187The file ``misc/zsh/_khard`` contains a khard cli completion function for the
188zsh and ``misc/zsh/_email-khard`` completes email addresses.
189
190Install by copying to a directory where zsh searches for completion functions
191(the ``$fpath`` array). If you, for example, put all completion functions into
192the folder ``~/.zsh/completions`` you must add the following to your zsh main
193config file:
194
195.. code-block:: zsh
196
197  fpath=( $HOME/.zsh/completions $fpath )
198  autoload -U compinit
199  compinit
200
201
202sdiff
203-----
204
205Use the wrapper script ``misc/sdiff/sdiff_khard_wrapper.sh`` if you want to use
206sdiff as your contact merging tool. Just make the script executable and set it
207as your merge editor in khard's config file:
208
209.. code-block:: ini
210
211  merge_editor = /path/to/sdiff_khard_wrapper.sh
212
213.. include:: davcontroller.rst
214