[elpa] externals/compat 2f486b3403: compat-29: Add with-delayed-message

[ELPA Syncer]

branch: externals/compat
commit 2f486b34030d7905e4e295441377e65ff7056638
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>

    compat-29: Add with-delayed-message
---
 NEWS.org        |  4 ++++
 compat-29.el    | 29 +++++++++++++++++++++++++++++
 compat-tests.el |  5 +++++
 compat.texi     | 34 +++++++++++++++++++++++++++++++---
 4 files changed, 69 insertions(+), 3 deletions(-)

diff --git a/NEWS.org b/NEWS.org
index 6f88f58cae..108be19785 100644
--- a/NEWS.org
+++ b/NEWS.org
@@ -1,5 +1,9 @@
 #+title: compat.el - Changelog
 
+* Development
+
+- compat-29: Add ~funcall-with-delayed-message~ and ~with-delayed-message~.
+
 * Release of "Compat" Version 29.1.3.1
 
 - Fix regression, which prevented loading Compat in interpreted mode. We ensure
diff --git a/compat-29.el b/compat-29.el
index e597d5ea37..665366eefe 100644
--- a/compat-29.el
+++ b/compat-29.el
@@ -170,6 +170,35 @@ This function does not move point.  Also see 
`line-end-position'."
 
 ;;;; Defined in subr.el
 
+(compat-defmacro with-delayed-message (_args &rest body) ;; 
<compat-tests:with-delayed-message>
+  "Like `progn', but display MESSAGE if BODY takes longer than TIMEOUT seconds.
+The MESSAGE form will be evaluated immediately, but the resulting
+string will be displayed only if BODY takes longer than TIMEOUT seconds.
+
+NOTE: The compatibility function never displays the message,
+which is not problematic since the only effect of the function is
+to display a progress message to the user.  Backporting this
+feature is not possible, since the implementation is directly
+baked into the Elisp interpreter.
+
+\(fn (timeout message) &rest body)"
+  (declare (indent 1))
+  (macroexp-progn body))
+
+(compat-defun funcall-with-delayed-message (timeout message function) ;; 
<compat-tests:with-delayed-message>
+  "Like `funcall', but display MESSAGE if FUNCTION takes longer than TIMEOUT.
+TIMEOUT is a number of seconds, and can be an integer or a
+floating point number. If FUNCTION takes less time to execute
+than TIMEOUT seconds, MESSAGE is not displayed.
+
+NOTE: The compatibility function never displays the message,
+which is not problematic since the only effect of the function is
+to display a progress message to the user.  Backporting this
+feature is not possible, since the implementation is directly
+baked into the Elisp interpreter."
+  (ignore timeout message)
+  (funcall function))
+
 (compat-defun string-lines (string &optional omit-nulls keep-newlines) ;; 
<compat-tests:string-lines>
   "Handle additional KEEP-NEWLINES argument."
   :extended "28.1"
diff --git a/compat-tests.el b/compat-tests.el
index e8a5189de0..2c4d1cffd5 100644
--- a/compat-tests.el
+++ b/compat-tests.el
@@ -2848,5 +2848,10 @@
     (should sentence-end-double-space)
     (should-equal major-mode #'text-mode)))
 
+(ert-deftest with-delayed-message ()
+  ;; No real test, since the backported function never displays a message.
+  (should-equal 'result (with-delayed-message (1 "timeout") 'result))
+  (should-equal 'result (funcall-with-delayed-message 1 "timeout" (lambda () 
'result))))
+
 (provide 'compat-tests)
 ;;; compat-tests.el ends here
diff --git a/compat.texi b/compat.texi
index b0822a99bb..563a4d9deb 100644
--- a/compat.texi
+++ b/compat.texi
@@ -2246,6 +2246,37 @@ Like @code{line-end-position}, but ignores fields (and 
is more
 efficient).
 @end defun
 
+@c copied from lispref/display.texi
+@defmac with-delayed-message (timeout message) body@dots{}
+Sometimes it's unclear whether an operation will take a long time to
+execute or not, or it can be inconvenient to implement a progress
+reporter.  This macro can be used in those situations.
+
+@lisp
+(with-delayed-message (2 (format "Gathering data for %s" entry))
+  (setq data (gather-data entry)))
+@end lisp
+
+In this example, if the body takes more than two seconds to execute,
+the message will be displayed.  If it takes a shorter time than that,
+the message won't be displayed.  In either case, the body is evaluated
+as normally, and the return value of the final element in the body is
+the return value of the macro.
+
+The @var{message} element is evaluated before @var{body}, and is
+always evaluated, whether the message is displayed or not.
+@end defmac
+
+@c based on src/eval.c
+@defun funcall-with-delayed-message timeout message function
+Like @code{funcall}, but display @var{message} if @var{function} takes
+longer than @var{timeout}.  @var{timeout} is a number of seconds, and
+can be an integer or a floating point number.
+
+If @var{function} takes less time to execute than @var{timeout}
+seconds, @var{message} is not displayed.
+@end defun
+
 @c copied from lispref/display.texi
 @defun buttonize string callback &optional data help-echo
 Sometimes it's more convenient to make a string into a button without
@@ -2907,9 +2938,6 @@ The command @code{string-edit} and 
@code{read-string-from-buffer}.
 @item
 The macro @code{with-undo-amalgamate}.
 @item
-The macro @code{with-delayed-message} and the function
-@code{funcall-with-delayed-message}.
-@item
 The function @code{string-glyph-split}.
 @item
 The function @code{string-limit}.