bug#65449: 30.0.50; [PATCH] strokes: Support running other function when no stroke matches

[Liu Hui <liuhui1610@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 535 bytes --]

Eli Zaretskii <eliz@gnu.org> 于2023年8月22日周二 19:17写道：
>
> Thanks.  This is a useful extension, IMO, but please extend the doc
> string of strokes-no-match-function to explain how it will be called
> and what is expected from it, including the expected return value(s)
> and their meaning.

I have updated the doc string in the attached patch. However, the
return value cannot be specified because the return value of
`strokes-execute-stroke' is not specified, i.e., `command-execute'
could return any value.

[-- Attachment #2: 0001-strokes-Support-running-other-function-when-no-strok.patch --]
[-- Type: text/x-patch, Size: 2657 bytes --]

From 805f6108c2184e0f7aab11da11359eca8be2bfbd Mon Sep 17 00:00:00 2001
From: Liu Hui <liuhui1610@gmail.com>
Date: Tue, 22 Aug 2023 13:52:03 +0800
Subject: [PATCH] strokes: Support running other function when no stroke
 matches

* lisp/strokes.el (strokes-no-match-function): New variable.
(strokes-no-match-default): New function.
(strokes-execute-stroke): Run `strokes-no-match-function' when no
stroke matches.
---
 lisp/strokes.el | 25 ++++++++++++++++---------
 1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/lisp/strokes.el b/lisp/strokes.el
index 293bdf0f369..1a39e5fefd3 100644
--- a/lisp/strokes.el
+++ b/lisp/strokes.el
@@ -266,6 +266,14 @@ strokes-use-strokes-buffer
 the delay in switching to the strokes buffer."
   :type 'boolean)
 
+(defvar strokes-no-match-function 'strokes-no-match-default
+  "Function run by `strokes-execute-stroke' when no stroke matches.
+The function is called with two arguments, the stroke and the
+closest match returned by `strokes-match-stroke'.  It can be used
+to show detailed information about the unmatched stroke or
+perform some fallback action.  The default function
+`strokes-no-match-default' simply signals an error.")
+
 ;;; internal variables...
 
 (defvar strokes-window-configuration nil
@@ -838,14 +846,16 @@ strokes-read-complex-stroke
 	    (goto-char (point-min))
 	    (bury-buffer)))))))
 
+(defun strokes-no-match-default (&rest _)
+  "Signal an error when no stroke matches."
+  (error
+   "No stroke matches; see variable `strokes-minimum-match-score'"))
+
 (defun strokes-execute-stroke (stroke)
   "Given STROKE, execute the command which corresponds to it.
 The command will be executed provided one exists for that stroke,
-based on the variable `strokes-minimum-match-score'.
-If no stroke matches, nothing is done and return value is nil."
-  ;; FIXME: Undocument return value.  It is not documented for all cases,
-  ;; and doesn't allow differentiating between no stroke matches and
-  ;; command-execute returning nil, anyway.
+based on the variable `strokes-minimum-match-score'.  If no
+stroke matches, `strokes-no-match-function' is called."
   (let* ((match (strokes-match-stroke stroke strokes-global-map))
 	 (command (car match))
 	 (score (cdr match)))
@@ -859,10 +869,7 @@ strokes-execute-stroke
 				     strokes-file))
 		    (strokes-load-user-strokes))
 	     (error "No strokes defined; use `strokes-global-set-stroke'")))
-	  (t
-	   (error
-	    "No stroke matches; see variable `strokes-minimum-match-score'")
-	   nil))))
+	  (t (funcall strokes-no-match-function stroke match)))))
 
 ;;;###autoload
 (defun strokes-do-stroke (event)
-- 
2.25.1