Re: [Proposal] New EUDC backend for macOS address book

[Alexander Adolf]

Hello Thomas, Emacs Developers,

Thomas Fitzsimmons <fitzsim@fitzsim.org> writes:

>>> [...]
>>> You can make the changes to eudc.texi, create a patch, then reply to
>>> this message with the patch attached.
>>> [...]

Apologies for the delay! Please kindly find the patch attached.

What I did:

• Under "Overview", I added a new @section, paralleling what already
  existed for BBDB.

• Since the backend is not enabled by default, I have also added a new
  @section under "Installation". That new section, besides telling how
  to enable the macOS Contacts backend, also describes the two available
  backends, and how they differ. The text also deprecates the
  pre-existing eudcb-mab.el, and recommends the new
  eudcb-macos-contacts.el for new configurations.


Looking forward to your thoughts,

  --alexander

diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi
index 66867cbc58..0cea3126a0 100644
--- a/doc/misc/eudc.texi
+++ b/doc/misc/eudc.texi
@@ -85,6 +85,8 @@ LDAP, Lightweight Directory Access Protocol
 CCSO PH/QI
 @item
 BBDB, Big Brother's Insidious Database
+@item
+macOS Contacts
 @end itemize
 
 The main features of the EUDC interface are:
@@ -110,6 +112,7 @@ Interface to BBDB to let you insert server records into 
your own BBDB database
 * LDAP::                        What is LDAP ?
 * CCSO PH/QI::                  What is CCSO, PH, QI ?
 * BBDB::                        What is BBDB ?
+* macOS Contacts::              What is macOS Contacts ?
 @end menu
 
 
@@ -186,6 +189,31 @@ performing queries on multiple servers.
 EUDC also offers a means to insert results from directory queries into
 your own local BBDB (@pxref{Creating BBDB Records})
 
+
+@node macOS Contacts
+@section macOS Contacts
+
+@url{https://support.apple.com/guide/contacts/welcome/mac,, macOS
+Contacts} is the rolodex-like application that ships with the macOS
+operating system@footnote{Apple have changed the names of their
+operating system and some applications over time.  macOS used to be
+called Mac OS X in the past, and the Contacts application was
+previously called Address Book.}.  It is tightly integrated with the
+other Apple applications (Mail, Calendar, etc.), and can synchronise
+contacts information between Apple devices via CardDAV servers (such
+as e.g. iCloud).
+
+EUDC considers macOS Contacts as a directory server back end just like
+LDAP or PH/QI servers, though the macOS Contacts application always
+resides locally on your machine.  The point in this is not to offer an
+alternate way to query your macOS Contacts database (the macOS
+Contacts application itself provides much more flexible ways to do
+that), but rather to offer an interface to your local directory that
+is consistent with the interface to external directories (LDAP,
+PH/QI).  This is particularly interesting when performing queries on
+multiple servers.
+
+
 @node Installation
 @chapter Installation
 
@@ -214,6 +242,7 @@ email composition buffers (@pxref{Inline Query Expansion})
 
 @menu
 * LDAP Configuration::           EUDC needs external support for LDAP
+* macOS Contacts Configuration:: Enable the macOS Contacts backend
 @end menu
 
 @node LDAP Configuration
@@ -339,6 +368,42 @@ and the @file{.emacs} expressions become:
 (customize-set-variable 'ldap-host-parameters-alist '(("" auth-source t)))
 @end lisp
 
+
+@node macOS Contacts Configuration
+@section macOS Contacts Configuration
+
+macOS Contacts support is added by means of @file{eudcb-mab.el}, or
+@file{eudcb-macos-contacts.el} which are part of Emacs.
+
+@file{eudcb-mab.el} reverse engineers the format of the database file
+used by the macOS Contacts app, and accesses its contents directly.
+While this may promise some performance advantages, it comes at the
+cost of using an undocumented interface.  Hence, users of
+@file{eudcb-mab.el} are recommended to double check the compatibility
+of @file{eudcb-mab.el} before upgrading to a new version of macOS.
+@file{eudcb-mab.el} is retained for backwards compatibility with
+existing configurations, and may be removed in a future release.
+
+@file{eudcb-macos-contacts.el} uses the public scripting interfaces
+offered by the Contacts app via the macOS
+@url{https://developer.apple.com/library/archive/documentation/AppleScript/Conceptual/AppleScriptX/Concepts/osa.html,,
+Open Scripting Architecture (OSA)}.  To accomplish this,
+@file{eudcb-macos-contacts.el} uses an external command line utility
+named
+@url{https://developer.apple.com/library/archive/documentation/OpenSource/Conceptual/ShellScripting/AdvancedTechniques/AdvancedTechniques.html#//apple_ref/doc/uid/TP40004268-TP40003521-SW44,,
+osascript}, which is included with all macOS versions since 10.0
+(which was released 2001).  @file{eudcb-macos-contacts.el} is hence
+recommended for all new configurations.
+
+To enable a macOS Contacts backend, first `require' the respective
+library to load it, and then set the `eudc-server' to localhost in
+your init file:
+@lisp
+(require 'eudcb-macos-contacts)
+(eudc-macos-contacts-set-server "localhost")
+@end lisp
+
+
 @node Usage
 @chapter Usage