contrib: add carddav-query script

Add a standalone python script to allow querying contacts from a CardDAV
compatible server. The script works with python 3.6+ and has no external
dependencies.

Link: https://sabre.io/dav/building-a-carddav-client/
Link: https://www.rfc-editor.org/rfc/rfc6352
Signed-off-by: Robin Jarry <robin@jarry.cc>
Tested-by: Tim Culverhouse <tim@timculverhouse.com>

1 files changed, 103 insertions, 0 deletions

diff --git a/doc/carddav-query.1.scd b/doc/carddav-query.1.scd
new file mode 100644
index 00000000..bdd708ab
--- /dev/null
+++ b/doc/carddav-query.1.scd
@@ -0,0 +1,103 @@
+CARDDAV-QUERY(1)
+
+# NAME
+
+carddav-query - Query a CardDAV server for contact names and emails.
+
+# SYNOPSIS
+
+*carddav-query* [*-h*] [*-l* _<limit>_] [*-v*] [*-c* _<file>_]
+\[*-s* _<section>_] [*-k* _<key\_source>_] [*-C* _<key\_cred\_cmd>_]
+\[*-s* _<server\_url>_] [*-u* _<username>_] [*-p* _<password>_] _<term>_ [_<term>_ ...]
+
+This tool has been tailored for use as *address-book-cmd* in *aerc-config*(5).
+
+# OPTIONS
+
+*-h*, *--help*
+	show this help message and exit
+
+*-v*, *--verbose*
+	Print debug info on stderr.
+
+*-l* _<limit>_, *--limit* _<limit>_
+	Maximum number of results returned by the server. If the server does not
+	support limiting, this option will be disregarded.
+
+	Default: _10_
+
+*-c* _<file>_, *--config-file* _<file>_
+	INI configuration file from which to read the CardDAV URL endpoint.
+
+	Default: _~/.config/aerc/accounts.conf_
+
+*-S* _<section>_, *--config-section* _<section>_
+	INI configuration section where to find _<key\_source>_ and
+	_<key\_cred\_cmd>_. By default the first section where _<key\_source>_
+	is found will be used.
+
+*-k* _<key\_source>_, *--config-key-source* _<key\_source>_
+	INI configuration key to lookup in _<section>_ from _<file>_. The value
+	must respect the following format:
+
+		https?://_<username>_[:_<password>_]@_<hostname>_/_<path/to/addressbook>_
+
+	Both _<username>_ and _<password>_ must be percent encoded. If
+	_<password>_ is omitted, it can be provided via *--config-key-cred-cmd*
+	or *--password*.
+
+	Default: _carddav-source_
+
+*-C* _<key\_cred\_cmd>_, *--config-key-cred-cmd* _<key\_cred\_cmd>_
+	INI configuration key to lookup in _<section>_ from _<file>_. The value
+	is a command that will be executed with *sh -c* to determine
+	_<password>_ if it is not present in _<key\_source>_.
+
+	Default: _carddav-source-cred-cmd_
+
+*-s* _<server_url>_, *--server-url* _<server_url>_
+	CardDAV server URL endpoint. Overrides configuration file.
+
+*-u* _<username>_, *--username* _<username>_
+	Username to authenticate on the server. Overrides configuration file.
+
+*-p* _<password>_, *--password* _<password>_
+	Password for the specified user. Overrides configuration file.
+
+# POSITIONAL ARGUMENTS
+
+_<term>_
+	Search term. Will be used to search contacts from their FN (formatted
+	name), EMAIL, NICKNAME, ORG (company) and TITLE fields.
+
+# EXAMPLES
+
+These are excerpts of _~/.config/aerc/accounts.conf_.
+
+## Fastmail
+
+```
+[fastmail]
+carddav-source = https://janedoe%40fastmail.com@carddav.fastmail.com/dav/addressbooks/user/janedoe@fastmail.com/Default
+carddav-source-cred-cmd = pass fastmail.com/janedoe
+address-book-cmd = carddav-query -S fastmail %s
+```
+
+## Gmail
+
+```
+[gmail]
+carddav-source = https://johndoe%40gmail.com@www.googleapis.com/carddav/v1/principals/johndoe@gmail.com/lists/default
+carddav-source-cred-cmd = pass gmail.com/johndoe
+address-book-cmd = carddav-query -S gmail %s
+```
+
+# SEE ALSO
+
+*aerc-config*(5)
+
+# AUTHORS
+
+Created by Robin Jarry <robin@jarry.cc> who is assisted by other open source
+contributors. For more information about aerc development, see
+https://sr.ht/~rjarry/aerc/.