Defining generic and mode-specific Emacs Lisp functions with cl-defmethod
| elisp, emacs, subed
2022-01-27: Added example function description.
2022-01-02: Changed quote to function in the defalias.
I recently took over the maintenance of subed, an Emacs mode for editing subtitles. One of the things on my TODO list was to figure out how to handle generic and format-specific functions instead of relying on defalias. For example, there are SubRip files (.srt), WebVTT files (.vtt), and Advanced SubStation Alpha (.ass). I also want to add support for Audacity labels and other formats.
There are some functions that will work across all of them once you have the appropriate format-specific functions in place, and there are some functions that have to be very different depending on the format that you're working with. Now, how do you do those things in Emacs Lisp? There are several ways of making general functions and specific functions.
For example, the forward-paragraph and backward-paragraph commands
use variables to figure out the paragraph separators, so buffer-local
variables can change the behaviour.
However, I needed a bit more than regular expressions. An approach
taken in some packages like smartparens is to have buffer-local
variables have the actual functions to be called, like
sp-forward-bound-fn and sp-backward-bound-fn.
(defvar-local sp-forward-bound-fn nil "Function to restrict the forward search") (defun sp--get-forward-bound () "Get the bound to limit the forward search for looking for pairs. If it returns nil, the original bound passed to the search function will be considered." (and sp-forward-bound-fn (funcall sp-forward-bound-fn)))
Since there were so many functions, I figured that might be a little bit unwieldy. In Org mode, custom export backends are structs that have an alist that maps the different types of things to the functions that will be called, overriding the functions that are defined in the parent export backend.
(cl-defstruct (org-export-backend (:constructor org-export-create-backend) (:copier nil)) name parent transcoders options filters blocks menu) (defun org-export-get-all-transcoders (backend) "Return full translation table for BACKEND. BACKEND is an export back-end, as return by, e.g,, `org-export-create-backend'. Return value is an alist where keys are element or object types, as symbols, and values are transcoders. Unlike to `org-export-backend-transcoders', this function also returns transcoders inherited from parent back-ends, if any." (when (symbolp backend) (setq backend (org-export-get-backend backend))) (when backend (let ((transcoders (org-export-backend-transcoders backend)) parent) (while (setq parent (org-export-backend-parent backend)) (setq backend (org-export-get-backend parent)) (setq transcoders (append transcoders (org-export-backend-transcoders backend)))) transcoders)))
The export code looked a little bit complicated, though. I wanted to
see if there was a different way of doing things, and I came across
cl-defmethod. Actually, the first time I tried to implement this, I
was focused on the fact that cl-defmethod could call different
things depending on the class that you give it. So initially I had
created a couple of classes: subed-backend class, and then
subclasses such as subed-vtt-backend. This allowed me to store the
backend as a buffer-local variable and differentiate based on that.
(require 'eieio) (defclass subed-backend () ((regexp-timestamp :initarg :regexp-timestamp :initform "" :type string :custom string :documentation "Regexp matching a timestamp.") (regexp-separator :initarg :regexp-separator :initform "" :type string :custom string :documentation "Regexp matching the separator between subtitles.")) "A class for data and functions specific to a subtitle format.") (defclass subed-vtt-backend (subed-backend) nil "A class for WebVTT subtitle files.") (cl-defmethod subed--timestamp-to-msecs ((backend subed-vtt-backend) time-string) "Find HH:MM:SS,MS pattern in TIME-STRING and convert it to milliseconds. Return nil if TIME-STRING doesn't match the pattern. Use the format-specific function for BACKEND." (save-match-data (when (string-match (oref backend regexp-timestamp) time-string) (let ((hours (string-to-number (match-string 1 time-string))) (mins (string-to-number (match-string 2 time-string))) (secs (string-to-number (match-string 3 time-string))) (msecs (string-to-number (subed--right-pad (match-string 4 time-string) 3 ?0)))) (+ (* (truncate hours) 3600000) (* (truncate mins) 60000) (* (truncate secs) 1000) (truncate msecs))))))
Then I found out that you can use major-mode as a context specifier
for cl-defmethod, so you can call different specific functions
depending on the major mode that your buffer is in. It doesn't seem to
be mentioned in the elisp manual, so at some point I should figure out
how to suggest mentioning it. Anyway, now I have some functions that
get called if the buffer is in subed-vtt-mode and some functions
that get called if the buffer is in subed-srt-mode.
The catch is that cl-defmethod can't define interactive functions.
So if I'm defining a command, an interactive function that can be
called with M-x, then I will need to have a regular function that
calls the function defined with cl-defmethod. This resulted in a bit
of duplicated code, so I have a macro that defines the method and then
defines the possibly interactive command that calls that method. I
didn't want to think about whether something was interactive or not,
so my macro just always creates those two functions. One is a
cl-defmethod that I can override for a specific major mode, and one
is the function that actually calls it, which may may not be
interactive. It doesn't handle &rest args, but I don't have any in
subed.el at this time.
(defmacro subed-define-generic-function (name args &rest body) "Declare an object method and provide the old way of calling it." (declare (indent 2)) (let (is-interactive doc) (when (stringp (car body)) (setq doc (pop body))) (setq is-interactive (eq (caar body) 'interactive)) `(progn (cl-defgeneric ,(intern (concat "subed--" (symbol-name name))) ,args ,doc ,@(if is-interactive (cdr body) body)) ,(if is-interactive `(defun ,(intern (concat "subed-" (symbol-name name))) ,args ,(concat doc "\n\nThis function calls the generic function `" (concat "subed--" (symbol-name name)) "' for the actual implementation.") ,(car body) (,(intern (concat "subed--" (symbol-name name))) ,@(delq nil (mapcar (lambda (a) (unless (string-match "^&" (symbol-name a)) a)) args)))) `(defalias (quote ,(intern (concat "subed-" (symbol-name name)))) (function ,(intern (concat "subed--" (symbol-name name)))) ,doc)))))
For example, the function:
(subed-define-generic-function timestamp-to-msecs (time-string) "Find timestamp pattern in TIME-STRING and convert it to milliseconds. Return nil if TIME-STRING doesn't match the pattern.")
expands to:
(progn (cl-defgeneric subed--timestamp-to-msecs (time-string) "Find timestamp pattern in TIME-STRING and convert it to milliseconds. Return nil if TIME-STRING doesn't match the pattern.") (defalias 'subed-timestamp-to-msecs 'subed--timestamp-to-msecs "Find timestamp pattern in TIME-STRING and convert it to milliseconds. Return nil if TIME-STRING doesn't match the pattern."))
and the interactive command defined with:
(subed-define-generic-function forward-subtitle-end () "Move point to end of next subtitle. Return point or nil if there is no next subtitle." (interactive) (when (subed-forward-subtitle-id) (subed-jump-to-subtitle-end)))
expands to:
(progn (cl-defgeneric subed--forward-subtitle-end nil "Move point to end of next subtitle. Return point or nil if there is no next subtitle." (when (subed-forward-subtitle-id) (subed-jump-to-subtitle-end))) (defun subed-forward-subtitle-end nil "Move point to end of next subtitle. Return point or nil if there is no next subtitle. This function calls the generic function `subed--forward-subtitle-end' for the actual implementation." (interactive) (subed--forward-subtitle-end)))
Then I can define a specific one with:
(cl-defmethod subed--timestamp-to-msecs (time-string &context (major-mode subed-srt-mode)) "Find HH:MM:SS,MS pattern in TIME-STRING and convert it to milliseconds. Return nil if TIME-STRING doesn't match the pattern. Use the format-specific function for MAJOR-MODE." (save-match-data (when (string-match subed--regexp-timestamp time-string) (let ((hours (string-to-number (match-string 1 time-string))) (mins (string-to-number (match-string 2 time-string))) (secs (string-to-number (match-string 3 time-string))) (msecs (string-to-number (subed--right-pad (match-string 4 time-string) 3 ?0)))) (+ (* (truncate hours) 3600000) (* (truncate mins) 60000) (* (truncate secs) 1000) (truncate msecs))))))
The upside is that it's easy to either override or extend a function's behavior. For example, after I sort subtitles, I want to renumber them if I'm in an SRT buffer because SRT subtitles have numeric IDs. This doesn't happen in any of the other modes. So I can just define that this bit of code runs after the regular code that runs.
(cl-defmethod subed--sort :after (&context (major-mode subed-srt-mode)) "Renumber after sorting. Format-specific for MAJOR-MODE." (subed-srt--regenerate-ids))
The downside is that going to the function's definition and stepping
through it is a little more complicated because it's hidden behind
this macro and the cl-defmethod infrastructure. I think that if you
describe-function the right function, the internal version with the
--, then it will list the different implementations of it. I added a
note to the regular function's docstring to make it a little easier.
Here's what M-x describe-function subed-forward-subtitle-end looks like:
Figure 1: Describing a generic function
I'm going to give this derived-mode branch a try for a little while by
subtitling some more EmacsConf talks before I merge it into the main
branch. This is my first time working with cl-defmethod, and it
looks pretty interesting.