branch: externals/compat
commit 2f486b34030d7905e4e295441377e65ff7056638
Author: Daniel Mendler <m...@daniel-mendler.de>
Commit: Daniel Mendler <m...@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}.
