[elpa] externals/excorporate 2916112 4/5: Add exco-select-connection-identifier function

[Thomas Fitzsimmons]

branch: externals/excorporate
commit 2916112e094e866949d909006c7df9e0b6b38e68
Author: Thomas Fitzsimmons <fitzsim@fitzsim.org>
Commit: Thomas Fitzsimmons <fitzsim@fitzsim.org>

    Add exco-select-connection-identifier function
    
    * excorporate.el (exco-select-connection-identifier): New
    function.
    (excorporate-disconnect): Rewrite to call
    exco-select-connection-identifier.
    * excorporate.texi (API Usage): Replace direct references to
    exco--connection-identifiers with calls to
    exco-select-connection-identifier.
    * excorporate.info: Regenerate.
---
 excorporate.el   | 46 +++++++++++++++++++++++++---------------------
 excorporate.info | 26 ++++++++++++++------------
 excorporate.texi | 25 ++++++++++++++-----------
 3 files changed, 53 insertions(+), 44 deletions(-)

diff --git a/excorporate.el b/excorporate.el
index f651a2b..b5459f8 100644
--- a/excorporate.el
+++ b/excorporate.el
@@ -661,6 +661,28 @@ use the `cdr' of the pair as the service URL."
        (fsm-send fsm :retrieve-xml))
       nil)))
 
+(defun exco-select-connection-identifier ()
+  "Return a connection identifier.
+Return the sole connection if only one exists, or prompt the user
+if more than one connection exists.  Return nil if the user
+provides a null response"
+  (exco--ensure-connection)
+  (if (= (length exco--connection-identifiers) 1)
+      (car exco--connection-identifiers)
+    (let* ((strings (mapcar (lambda (object)
+                             (format "%s" object))
+                           exco--connection-identifiers))
+          (value (completing-read "Excorporate connection: "
+                                  strings nil t)))
+      (unless (equal value "")
+       (let ((position (catch 'index
+                         (let ((index 0))
+                           (dolist (string strings)
+                             (when (equal value string)
+                               (throw 'index index))
+                             (setq index (1+ index)))))))
+         (nth position exco--connection-identifiers))))))
+
 (defun exco-operate (identifier name arguments callback)
   "Execute a service operation asynchronously.
 IDENTIFIER is the connection identifier.  Execute operation NAME
@@ -1249,27 +1271,9 @@ ARGUMENT is the prefix argument."
 (defun excorporate-disconnect ()
   "Disconnect a server connection."
   (interactive)
-  (catch 'cancel
-    (let ((identifier
-          (cond
-           ((= (length exco--connection-identifiers) 0)
-            (exco--ensure-connection))
-           ((= (length exco--connection-identifiers) 1)
-            (car exco--connection-identifiers))
-           (t
-            (let* ((strings (mapcar (lambda (object)
-                                      (format "%s" object))
-                                    exco--connection-identifiers))
-                   (value (completing-read "Excorporate: Disconnect: "
-                                           strings nil t))
-                   (_return (when (equal value "") (throw 'cancel nil)))
-                   (position (catch 'index
-                               (let ((index 0))
-                                 (dolist (string strings)
-                                   (when (equal value string)
-                                     (throw 'index index))
-                                   (setq index (1+ index))))) ))
-              (nth position exco--connection-identifiers))))))
+  (exco--ensure-connection)
+  (let ((identifier (exco-select-connection-identifier)))
+    (when identifier
       (exco-disconnect identifier)
       (message "Excorporate: Disconnected %s" identifier))))
 
diff --git a/excorporate.info b/excorporate.info
index d38b805..fb14e79 100644
--- a/excorporate.info
+++ b/excorporate.info
@@ -286,7 +286,7 @@ hacker2@gnu.org is invited, using a non-interactive 
function provided by
 Excorporate:
 
      (exco-calendar-item-meeting-create
-      (car exco--connection-identifiers)
+      (exco-select-connection-identifier)
       "Test meeting 1"
       "Hi,\n\nThis is a test meeting 1.\n\nRegards.\n"
       (encode-time 0 15 14 23 09 2020)
@@ -312,11 +312,13 @@ Excorporate:
 The callback is run asychronously after the server responds, so as not
 to block Emacs, and the result is what is printed in the '*Messages*'
 buffer.  This example assumes the user has already run 'M-x excorporate'
-to create a connection.  '(car exco--connection-identifiers)' is a hack
-that uses the first-established connection.  Excorporate fully supports
-connecting to multiple different servers though (see
-'exco-connection-iterate') so published code that uses the Excorporate
-API should not assume just one connection.
+to create a connection.  'exco-select-connection-identifier' will
+automatically use the sole connection if only one exists.  Excorporate
+fully supports connecting to multiple different servers though (see
+'exco-connection-iterate') so reusable code that calls Excorporate APIs
+should not assume just one connection.  You can find examples of
+iterating through multiple connections in 'excorporate-diary.el' and
+'excorporate-org.el'.
 
 There is lots of server-side functionality that Excorporate does not
 provide high-level non-interactive functions for.  Using that
@@ -330,7 +332,7 @@ accepted, unknown).  You can find ItemId forms to 
experiment with in the
 PROPERTIES drawer of calendar entries in the interactive Org buffer.
 
      (exco-operate-synchronously
-      (car exco--connection-identifiers)
+      (exco-select-connection-identifier)
       "GetItem"
       '(((ItemShape
           (BaseShape . "AllProperties"))
@@ -420,7 +422,7 @@ from Emacs's internal time zone (see 'current-time-zone'), 
the
 equivalent server time zone string.
 
      (exco-operate
-      (car exco--connection-identifiers)
+      (exco-select-connection-identifier)
       "GetUserAvailability"
       '(((TimeZone
           (Bias . 300)
@@ -556,7 +558,7 @@ nils with a length matching the number of arguments that the
 server functionality, but for now they can all be left 'nil'.
 
      (exco-operate
-      (car exco--connection-identifiers)
+      (exco-select-connection-identifier)
       "CreateItem"
       `(((SendMeetingInvitations . "SendToAllAndSaveCopy")
          (Items
@@ -598,7 +600,7 @@ Now we can retrieve the item's properties to see the 
recurrence and time
 zone details:
 
      (exco-operate
-      (car exco--connection-identifiers)
+      (exco-select-connection-identifier)
       "GetItem"
       '(((ItemShape
           (BaseShape . "AllProperties"))
@@ -728,7 +730,7 @@ returned as '(CalendarItem (ItemId ...) ...)' by the above 
'GetItem'
 operation, whose 'CalendarType' element is "RecurringMaster".
 
      (exco-operate
-      (car exco--connection-identifiers)
+      (exco-select-connection-identifier)
       "DeleteItem"
       '(((DeleteType . "MoveToDeletedItems")
          (SendMeetingCancellations . "SendToNone")
@@ -777,7 +779,7 @@ Node: Configuration3007
 Node: Usage4079
 Node: Troubleshooting6538
 Node: API Usage10221
-Node: Index27455
+Node: Index27583
 
 End Tag Table
 
diff --git a/excorporate.texi b/excorporate.texi
index 2c16212..5997e0d 100644
--- a/excorporate.texi
+++ b/excorporate.texi
@@ -322,7 +322,7 @@ Excorporate:
 @example
 @group
 (exco-calendar-item-meeting-create
- (car exco--connection-identifiers)
+ (exco-select-connection-identifier)
  "Test meeting 1"
  "Hi,\n\nThis is a test meeting 1.\n\nRegards.\n"
  (encode-time 0 15 14 23 09 2020)
@@ -351,11 +351,14 @@ Excorporate:
 The callback is run asychronously after the server responds, so as not
 to block Emacs, and the result is what is printed in the
 @code{*Messages*} buffer.  This example assumes the user has already run
-@kbd{M-x excorporate} to create a connection.  @code{(car
-exco--connection-identifiers)} is a hack that uses the first-established
-connection.  Excorporate fully supports connecting to multiple different
-servers though (see @code{exco-connection-iterate}) so published code
-that uses the Excorporate API should not assume just one connection.
+@kbd{M-x excorporate} to create a connection.
+@code{exco-select-connection-identifier} will automatically use the sole
+connection if only one exists.  Excorporate fully supports connecting to
+multiple different servers though (see @code{exco-connection-iterate})
+so reusable code that calls Excorporate APIs should not assume just one
+connection.  You can find examples of iterating through multiple
+connections in @code{excorporate-diary.el} and
+@code{excorporate-org.el}.
 
 @noindent
 There is lots of server-side functionality that Excorporate does not
@@ -373,7 +376,7 @@ PROPERTIES drawer of calendar entries in the interactive 
Org buffer.
 @example
 @group
 (exco-operate-synchronously
- (car exco--connection-identifiers)
+ (exco-select-connection-identifier)
  "GetItem"
  '(((ItemShape
      (BaseShape . "AllProperties"))
@@ -469,7 +472,7 @@ hacker2@@gnu.org, in the America/Toronto time zone.  Call
 @example
 @group
 (exco-operate
- (car exco--connection-identifiers)
+ (exco-select-connection-identifier)
  "GetUserAvailability"
  '(((TimeZone
      (Bias . 300)
@@ -611,7 +614,7 @@ complicated server functionality, but for now they can all 
be left
 @example
 @group
 (exco-operate
- (car exco--connection-identifiers)
+ (exco-select-connection-identifier)
  "CreateItem"
  `(((SendMeetingInvitations . "SendToAllAndSaveCopy")
     (Items
@@ -658,7 +661,7 @@ zone details:
 @example
 @group
 (exco-operate
- (car exco--connection-identifiers)
+ (exco-select-connection-identifier)
  "GetItem"
  '(((ItemShape
      (BaseShape . "AllProperties"))
@@ -795,7 +798,7 @@ returned as @code{(CalendarItem (ItemId ...) ...)} by the 
above
 @example
 @group
 (exco-operate
- (car exco--connection-identifiers)
+ (exco-select-connection-identifier)
  "DeleteItem"
  '(((DeleteType . "MoveToDeletedItems")
     (SendMeetingCancellations . "SendToNone")