[PATCH 11/12] Offer keyword arguments for WSDL to avoid repeated downloads.

[Felix Lechner]

---
 debbugs.el   | 42 ++++++++++++++++++++++++++----------------
 debbugs.texi | 37 +++++++++++++++++++++++++++++--------
 2 files changed, 55 insertions(+), 24 deletions(-)

diff --git a/debbugs.el b/debbugs.el
index ae6e72e1cb..995f0f7784 100644
--- a/debbugs.el
+++ b/debbugs.el
@@ -115,14 +115,16 @@ t or 0 disables caching, nil disables expiring."
 (defvar debbugs-soap-invoke-async-object nil
   "The object manipulated by `debbugs-soap-invoke-async'.")
 
-(defun debbugs-soap-invoke-async (operation-name parameters)
+(cl-defun debbugs-soap-invoke-async (operation-name
+                                     parameters
+                                     &key (soap-wsdl (debbugs-download-wsdl)))
   "Invoke the SOAP connection asynchronously."
   (apply
    #'soap-invoke-async
    (lambda (response &rest _args)
      (setq debbugs-soap-invoke-async-object
           (append debbugs-soap-invoke-async-object (car response))))
-   nil (debbugs-download-wsdl) debbugs-port operation-name parameters))
+   nil soap-wsdl debbugs-port operation-name parameters))
 
 (defcustom debbugs-show-progress t
   "Whether progress report is shown."
@@ -175,7 +177,7 @@ Don't set this globally, it shall be let-bound.")
                                    debbugs-progress-reporter-buffers))
                 (length debbugs-progress-reporter-buffers)))))))))
 
-(defun debbugs-get-bugs (query)
+(cl-defun debbugs-get-bugs (query &key (soap-wsdl (debbugs-download-wsdl)))
   "Return a list of bug numbers which match QUERY.
 
 QUERY is a sequence of keyword-value pairs where the values are
@@ -186,6 +188,8 @@ have multiple occurrence within the query at any place.  The
 subqueries with the same keyword form the logical subquery, which
 returns the union of bugs of every subquery it contains.
 
+SOAP-WSDL is an object returned by `soap-load-wsdl'.
+
 The result of the QUERY is an intersection of results of all
 subqueries.
 
@@ -296,15 +300,16 @@ patch:
     (unless (null query)
       (error "Unknown key: %s" (car query)))
     (prog1
-       (sort (car (soap-invoke (debbugs-download-wsdl) debbugs-port "get_bugs" 
vec)) #'<)
+       (sort (car (soap-invoke soap-wsdl debbugs-port "get_bugs" vec)) #'<)
       (when debbugs-show-progress
        (remove-function
         (symbol-function debbugs-url-display-message-or-percentage-function)
         "debbugs-url-display-message-or-percentage")
        (progress-reporter-done debbugs-progress-reporter)))))
 
-(defun debbugs-newest-bugs (amount)
-  "Return the list of bug numbers, according to AMOUNT (a number) latest bugs."
+(cl-defun debbugs-newest-bugs (amount &key (soap-wsdl (debbugs-download-wsdl)))
+  "Return the list of bug numbers, according to AMOUNT (a number) latest bugs.
+SOAP-WSDL is an object returned by `soap-load-wsdl'."
   (if (= amount 1)
       ;; We cache it as bug "0" in `debbugs-cache-data'.
       (let ((status (gethash 0 debbugs-cache-data)))
@@ -333,7 +338,7 @@ patch:
            (cons 'newest_bug
                  (caar
                   (soap-invoke
-                   (debbugs-download-wsdl) debbugs-port "newest_bugs" 
amount)))))
+                   soap-wsdl debbugs-port "newest_bugs" amount)))))
 
          ;; Cache it.
          (when (or (null debbugs-cache-expiry) (natnump debbugs-cache-expiry))
@@ -343,7 +348,7 @@ patch:
        (list (alist-get 'newest_bug status)))
 
     (sort
-     (car (soap-invoke (debbugs-download-wsdl) debbugs-port "newest_bugs" 
amount)) #'<)))
+     (car (soap-invoke soap-wsdl debbugs-port "newest_bugs" amount)) #'<)))
 
 (defun debbugs-convert-soap-value-to-string (string-value)
   "If STRING-VALUE is unibyte, decode its contents as a UTF-8 string.
@@ -366,7 +371,7 @@ bytes represent a UTF-8 string and decode them accordingly."
        string-value)
     (error "Invalid string value")))
 
-(defun debbugs-get-status (bug-numbers)
+(cl-defun debbugs-get-status (bug-numbers &key (soap-wsdl 
(debbugs-download-wsdl)))
   "Return a list of status entries for the bugs identified by BUG-NUMBERS,
 which is a list.
 
@@ -499,7 +504,8 @@ Example:
                          #'vector
                          (butlast
                           bug-ids (- (length bug-ids)
-                                     debbugs-max-hits-per-request)))))))
+                                     debbugs-max-hits-per-request))))
+                   :soap-wsdl soap-wsdl)))
 
                bug-ids
                (last bug-ids (- (length bug-ids)
@@ -572,7 +578,7 @@ Example:
            (alist-get 'value x))))
       debbugs-soap-invoke-async-object))))
 
-(defun debbugs-get-usertag (query)
+(cl-defun debbugs-get-usertag (query &key (soap-wsdl (debbugs-download-wsdl)))
   "Return a list of bug numbers which match QUERY.
 
 QUERY is a list of keyword-value pairs where the values are
@@ -594,6 +600,8 @@ Valid keywords are:
 If there is no :tag entry, no bug numbers will be returned but a list of
 existing user tags for :user.
 
+SOAP-WSDL is an object returned by `soap-load-wsdl'.
+
 Example:
 
   \(debbugs-get-usertag '(:user \"emacs\"))
@@ -637,7 +645,7 @@ Example:
 
     (setq
      object
-     (car (soap-invoke (debbugs-download-wsdl) debbugs-port "get_usertag" (car 
user))))
+     (car (soap-invoke soap-wsdl debbugs-port "get_usertag" (car user))))
 
     (if (null tags)
        ;; Return the list of existing tags.
@@ -650,7 +658,7 @@ Example:
 
 ;; get_bug_log ought to have an optional argument $msg_num.  According
 ;; to Debbugs/SOAP.pm, currently $msg_num is completely ignored.  So we do.
-(defun debbugs-get-bug-log (bug-number)
+(cl-defun debbugs-get-bug-log (bug-number &key (soap-wsdl 
(debbugs-download-wsdl)))
   "Return a list of messages related to BUG-NUMBER.
 
 Every message is an association list with the following attributes:
@@ -664,9 +672,9 @@ Every message is an association list with the following 
attributes:
 
   `attachments' A list of possible attachments, or nil.  Not
   implemented yet server side."
-  (car (soap-invoke (debbugs-download-wsdl) debbugs-port "get_bug_log" 
bug-number)))
+  (car (soap-invoke soap-wsdl debbugs-port "get_bug_log" bug-number)))
 
-(defun debbugs-search-est (query)
+(cl-defun debbugs-search-est (query &key (soap-wsdl (debbugs-download-wsdl)))
   "Return the result of a full text search according to QUERY.
 
 QUERY is a list of lists of keyword-value pairs where the
@@ -755,6 +763,8 @@ The following conditions are possible:
   attribute value and no operator.  In this case, ATTRIBUTE is
   not used for the search.
 
+SOAP-WSDL is an object returned by `soap-load-wsdl'.
+
 The result of the QUERY is a list of association lists with the
 same attributes as in the conditions.  Additional attributes are
 
@@ -947,7 +957,7 @@ Examples:
          (setq args (vconcat args (list vec)))))
 
       (setq result
-           (car (soap-invoke (debbugs-download-wsdl) debbugs-port "search_est" 
args)))
+           (car (soap-invoke soap-wsdl debbugs-port "search_est" args)))
       ;; The result contains lists (key value).  We transform it into
       ;; cons cells (key . value).
       (dolist (elt1 result)
diff --git a/debbugs.texi b/debbugs.texi
index e6db73b084..4c3d93413a 100644
--- a/debbugs.texi
+++ b/debbugs.texi
@@ -183,7 +183,7 @@ In Debbugs BTS, the bug number is the unique identifier of 
a bug
 report.  The functions described in this section return from the
 Debbugs server the list of bug numbers that match a user's query.
 
-@defun debbugs-get-bugs query
+@defun debbugs-get-bugs query &key soap-wsdl
 This function returns a list of bug numbers that match the
 @var{query}. @var{query} is a list of keyword-value pairs where the
 values are strings, i.e. :KEYWORD ``VALUE'' [:KEYWORD ``VALUE'']*
@@ -193,6 +193,9 @@ have multiple occurrence within the query at any place.  The
 subqueries with the same keyword form the logical subquery, which
 returns the union of bugs of every subquery it contains.
 
+@var{soap-wsdl} SOAP-WSDL is an object returned by
+@code{soap-load-wsdl}.
+
 The result of the @var{query} is an intersection of results of all
 subqueries.
 
@@ -297,10 +300,13 @@ packages which are maintained by @code{"me"} and which 
have a patch:
 @end example
 @end defun
 
-@defun debbugs-newest-bugs amount
+@defun debbugs-newest-bugs amount &key soap-wsdl
 This function returns a list of bug numbers, according to @var{amount}
 (a number) of latest bugs.
 
+@var{soap-wsdl} SOAP-WSDL is an object returned by
+@code{soap-load-wsdl}.
+
 Example.  Get the latest six bug report numbers from Debian BTS:
 
 @example
@@ -318,10 +324,15 @@ Bug status is a collection of fields that holds the 
information about
 the state and importance of the bug report, about originator, owner and
 various aspects of relationship with other bug reports.
 
-@defun debbugs-get-status bug-numbers
+@defun debbugs-get-status bug-numbers &key soap-wsdl
 Return a list of status entries for the bug reports identified by
-@var{bug-numbers}.  Every returned entry is an association list with the
-following attributes:
+@var{bug-numbers}.
+
+@var{soap-wsdl} SOAP-WSDL is an object returned by
+@code{soap-load-wsdl}.
+
+Every returned entry is an association list with the following
+attributes:
 
 @table @code
 @item id
@@ -463,7 +474,7 @@ The search engine uses an index over the bug database.  
This index is
 refreshed once a day only; search hits do not include recent changes
 of the same day.
 
-@defun debbugs-search-est query
+@defun debbugs-search-est query &key soap-wsdl
 Return the result of a full text search according to @var{query}.
 
 @var{query} is a list of lists of keyword-value pairs where the
@@ -561,6 +572,9 @@ A special case is an @code{:order}, where there is no 
corresponding
 attribute value and no operator.  In this case, @var{attribute} is
 not used for the search.
 
+@var{soap-wsdl} SOAP-WSDL is an object returned by
+@code{soap-load-wsdl}.
+
 The result of the @var{query} is a list of association lists with the
 same attributes as in the conditions.  Additional attributes are
 
@@ -618,7 +632,7 @@ Example.  Show all messages for package "emacs" on GNU BTS 
between
 @node Requesting messages
 @chapter Requesting messages
 
-@defun debbugs-get-bug-log bug-number
+@defun debbugs-get-bug-log bug-number &key soap-wsdl
 Returns a list of messages related to @var{bug-number}.  Every message is
 an association list with the following attributes:
 
@@ -635,6 +649,10 @@ The message body.
 A list of possible attachments, or @code{nil}.  Not implemented yet server
 side.
 @end table
+
+@var{soap-wsdl} SOAP-WSDL is an object returned by
+@code{soap-load-wsdl}.
+
 @end defun
 
 @defun debbugs-get-message-numbers messages
@@ -711,7 +729,7 @@ A user tag is a string, a user has assigned to one or 
several bugs.
 The user is identified by an email address.  The port @code{"gnu.org"}
 uses also package names as user identification.
 
-@defun debbugs-get-usertag query
+@defun debbugs-get-usertag query &key soap-wsdl
 Return a list of bug numbers which match @var{query}.
 
 @var{query} is a list of keyword-value pairs where the values are
@@ -737,6 +755,9 @@ identification, like @code{"cedet"} or @code{"tramp"} for 
the package
 If there is no @code{:tag} entry, no bug numbers will be returned but
 a list of existing user tags for @code{:user}.
 
+@var{soap-wsdl} SOAP-WSDL is an object returned by
+@code{soap-load-wsdl}.
+
 Example.  Get all user tags for the package @code{"emacs"}:
 
 @example
-- 
2.41.0