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

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

[Liu Hui]

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

Hi,

This patch allows users to call another function when no stroke
matches, instead of signaling an error. I bind down-mouse-3 to
strokes-do-stroke, and would like to pop up the context menu when no
stroke matches. In addition, two arguments stroke and match can be
passed to the function for other uses (e.g. making the error message
more informative).

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

From b507a99e55709600dc17780d35efcd52236c7833 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 | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/lisp/strokes.el b/lisp/strokes.el
index 293bdf0f369..3537e4ff2ed 100644
--- a/lisp/strokes.el
+++ b/lisp/strokes.el
@@ -266,6 +266,9 @@ 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 when no stroke matches.")
+
 ;;; internal variables...
 
 (defvar strokes-window-configuration nil
@@ -838,14 +841,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 +864,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

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

[Eli Zaretskii]

> From: Liu Hui <liuhui1610@gmail.com>
> Date: Tue, 22 Aug 2023 14:25:24 +0800
> 
> This patch allows users to call another function when no stroke
> matches, instead of signaling an error. I bind down-mouse-3 to
> strokes-do-stroke, and would like to pop up the context menu when no
> stroke matches. In addition, two arguments stroke and match can be
> passed to the function for other uses (e.g. making the error message
> more informative).

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.

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

[Liu Hui]

[-- 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

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

[Eli Zaretskii]

> From: Liu Hui <liuhui1610@gmail.com>
> Date: Tue, 22 Aug 2023 21:50:58 +0800
> Cc: 65449@debbugs.gnu.org
> 
> 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.

Thanks, looks reasonable.

Let's wait for a few days, to give others a chance to chime in and
voice comments.  If nothing serious comes up, I will install this in a
few days.

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

[Eli Zaretskii]

> Cc: 65449@debbugs.gnu.org
> Date: Tue, 22 Aug 2023 19:05:47 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> 
> > From: Liu Hui <liuhui1610@gmail.com>
> > Date: Tue, 22 Aug 2023 21:50:58 +0800
> > Cc: 65449@debbugs.gnu.org
> > 
> > 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.
> 
> Thanks, looks reasonable.
> 
> Let's wait for a few days, to give others a chance to chime in and
> voice comments.  If nothing serious comes up, I will install this in a
> few days.

No further comments, so I've now installed this on the master branch,
and I'm closing the bug.