scratch/derived-mode-add-parents cf00f1526d0: Subject: (derived-mode-add-parents): Add documentation and one more test

[Stefan Monnier]

branch: scratch/derived-mode-add-parents
commit cf00f1526d04c0798a6a38c005b5704cf3b825f0
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Commit: Stefan Monnier <monnier@iro.umontreal.ca>

    Subject: (derived-mode-add-parents): Add documentation and one more test
    
    * doc/lispref/modes.texi (Derived Modes): Document new derived-modes API.
    * test/lisp/subr-tests.el (subt-tests--merge-ordered-lists): New test.
---
 doc/lispref/modes.texi  | 25 +++++++++++++++++++++++++
 etc/NEWS                | 12 ++++++++++++
 test/lisp/subr-tests.el | 10 ++++++++++
 3 files changed, 47 insertions(+)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index f365d88fade..22ff07f9641 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -937,6 +937,31 @@ This function returns non-@code{nil} if the current major 
mode is
 derived from any of the major modes given by the symbols @var{modes}.
 @end defun
 
+The graph of major modes is accessed with the following lower-level
+functions:
+
+@defun derived-mode-set-parent mode parent
+This function declares that @var{mode} inherits from @code{parent}.
+This is the function that @code{define-derived-mode} calls after
+defining @var{mode} to register the fact that @var{mode} was defined
+by reusing @code{parent}.
+@end defun
+
+@defun derived-mode-add-parents mode extra-parents
+This function makes it possible to register additional parents beside
+the one that was used when defining @var{mode}.  This can be used when
+the similarity between @var{mode} and the modes in @var{extra-parents}
+is such that it makes sense to treat it as a child of those
+modes for purposes like applying directory-local variables.
+@end defun
+
+@defun derived-mode-all-parents mode
+This function returns the list of all the modes in the ancestry of
+@var{mode}, ordered from the most specific to the least specific, and
+starting with @var{mode} itself.
+@end defun
+
+
 @node Basic Major Modes
 @subsection Basic Major Modes
 
diff --git a/etc/NEWS b/etc/NEWS
index 767e4c27b43..1db22c4f2f5 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1181,6 +1181,18 @@ values.
 
 * Lisp Changes in Emacs 30.1
 
+** New function 'merge-ordered-lists'.
+Mostly used internally to do a kind of topological sort of
+inheritance hierarchies.
+
+** New API to control the graph of major modes.
+While 'define-derived-mode' still only support single inheritance,
+modes can declare additional parents (for tests like 'derived-mode-p')
+with `derived-mode-add-parents`.
+Accessing the 'derived-mode-parent' property directly is now
+deprecated in favor of the new functions 'derived-mode-set-parent'
+and 'derived-mode-all-parents'.
+
 +++
 ** Drag-and-drop functions can now be called once for compound drops.
 It is now possible for drag-and-drop handler functions to respond to
diff --git a/test/lisp/subr-tests.el b/test/lisp/subr-tests.el
index 03eb0d5bf8c..f67ac70046a 100644
--- a/test/lisp/subr-tests.el
+++ b/test/lisp/subr-tests.el
@@ -381,6 +381,16 @@
                        '(subr-tests--mode-A subr-tests--mode-B prog-mode
                          subr-tests--mode-C subr-tests--derived-mode-1))))))
 
+(ert-deftest subt-tests--merge-ordered-lists ()
+  (should (equal (merge-ordered-lists
+                  '((B A) (C A) (D B) (E D C)))
+                 '(E D B C A)))
+  (should (equal (merge-ordered-lists
+                  '((E D C) (B A) (C A) (D B)))
+                 '(E D C B A)))
+  (should-error (merge-ordered-lists
+                 '((E C D) (B A) (A C) (D B))
+                 (lambda (_) (error "cycle")))))
 
 (ert-deftest number-sequence-test ()
   (should (= (length