branch: externals/excorporate
commit 2916112e094e866949d909006c7df9e0b6b38e68
Author: Thomas Fitzsimmons <fitz...@fitzsim.org>
Commit: Thomas Fitzsimmons <fitz...@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 @@ hack...@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")
