Function: define-derived-mode
define-derived-mode is an autoloaded macro defined in derived.el.gz.
Signature
(define-derived-mode CHILD PARENT NAME [DOCSTRING] [KEYWORD-ARGS...] &rest BODY)
Documentation
Create a new mode CHILD which is a variant of an existing mode PARENT.
The arguments are as follows:
CHILD: the name of the command for the derived mode.
PARENT: the name of the command for the parent mode (e.g. text-mode)
or nil if there is no parent.
NAME: a string that will appear in the mode line (e.g. "HTML")
DOCSTRING: an optional documentation string--if you do not supply one,
the function will attempt to invent something useful.
KEYWORD-ARGS:
optional arguments in the form of pairs of keyword and value.
The following keyword arguments are currently supported:
:group GROUP
Declare the customization group that corresponds
to this mode. The command customize-mode uses this.
:syntax-table TABLE
Use TABLE instead of the default (CHILD-syntax-table).
A nil value means to simply use the same syntax-table
as the parent.
:abbrev-table TABLE
Use TABLE instead of the default (CHILD-abbrev-table).
A nil value means to simply use the same abbrev-table
as the parent.
:after-hook FORM
A single Lisp form which is evaluated after the mode
hooks have been run. It should not be quoted.
:interactive BOOLEAN
Whether the derived mode should be interactive or not.
The default is t.
BODY: forms to execute just before running the
hooks for the new mode. Do not use interactive here.
Here is how you could define LaTeX-Thesis mode as a variant of LaTeX mode:
(define-derived-mode LaTeX-thesis-mode LaTeX-mode "LaTeX-Thesis")
You could then make new key bindings for LaTeX-thesis-mode-map
without changing regular LaTeX mode. In this example, BODY is empty,
and DOCSTRING is generated by default.
As a more complex example, the following command uses sgml-mode as
the parent, and then sets the variable case-fold-search to nil:
(define-derived-mode article-mode sgml-mode "Article"
"Major mode for editing technical articles."
(setq case-fold-search nil))
Note that if the documentation string had been left out, it would have been generated automatically, with a reference to the keymap.
The new mode runs the hook named MODE-hook. For foo-mode,
the hook will be named foo-mode-hook.
See Info node (elisp)Derived Modes for more details.
Probably introduced at or before Emacs version 19.23.
Source Code
;; Defined in /usr/src/emacs/lisp/emacs-lisp/derived.el.gz
;; PUBLIC: define a new major mode which inherits from an existing one.
;;;###autoload
(defmacro define-derived-mode (child parent name &optional docstring &rest body)
"Create a new mode CHILD which is a variant of an existing mode PARENT.
The arguments are as follows:
CHILD: the name of the command for the derived mode.
PARENT: the name of the command for the parent mode (e.g. `text-mode')
or nil if there is no parent.
NAME: a string that will appear in the mode line (e.g. \"HTML\")
DOCSTRING: an optional documentation string--if you do not supply one,
the function will attempt to invent something useful.
KEYWORD-ARGS:
optional arguments in the form of pairs of keyword and value.
The following keyword arguments are currently supported:
:group GROUP
Declare the customization group that corresponds
to this mode. The command `customize-mode' uses this.
:syntax-table TABLE
Use TABLE instead of the default (CHILD-syntax-table).
A nil value means to simply use the same syntax-table
as the parent.
:abbrev-table TABLE
Use TABLE instead of the default (CHILD-abbrev-table).
A nil value means to simply use the same abbrev-table
as the parent.
:after-hook FORM
A single Lisp form which is evaluated after the mode
hooks have been run. It should not be quoted.
:interactive BOOLEAN
Whether the derived mode should be `interactive' or not.
The default is t.
BODY: forms to execute just before running the
hooks for the new mode. Do not use `interactive' here.
Here is how you could define LaTeX-Thesis mode as a variant of LaTeX mode:
(define-derived-mode LaTeX-thesis-mode LaTeX-mode \"LaTeX-Thesis\")
You could then make new key bindings for `LaTeX-thesis-mode-map'
without changing regular LaTeX mode. In this example, BODY is empty,
and DOCSTRING is generated by default.
As a more complex example, the following command uses `sgml-mode' as
the parent, and then sets the variable `case-fold-search' to nil:
(define-derived-mode article-mode sgml-mode \"Article\"
\"Major mode for editing technical articles.\"
(setq case-fold-search nil))
Note that if the documentation string had been left out, it would have
been generated automatically, with a reference to the keymap.
The new mode runs the hook named MODE-hook. For `foo-mode',
the hook will be named `foo-mode-hook'.
See Info node `(elisp)Derived Modes' for more details.
\(fn CHILD PARENT NAME [DOCSTRING] [KEYWORD-ARGS...] &rest BODY)"
(declare (debug (&define name symbolp sexp [&optional stringp]
[&rest keywordp sexp] def-body))
(doc-string 4)
(indent defun))
(when (and docstring (not (stringp docstring)))
;; Some trickiness, since what appears to be the docstring may really be
;; the first element of the body.
(push docstring body)
(setq docstring nil))
(when (eq parent 'fundamental-mode) (setq parent nil))
(let ((map (derived-mode-map-name child))
(syntax (derived-mode-syntax-table-name child))
(abbrev (derived-mode-abbrev-table-name child))
(declare-abbrev t)
(declare-syntax t)
(hook (derived-mode-hook-name child))
(group nil)
(interactive t)
(after-hook nil))
;; Process the keyword args.
(while (keywordp (car body))
(pcase (pop body)
(:group (setq group (pop body)))
(:abbrev-table (setq abbrev (pop body)) (setq declare-abbrev nil))
(:syntax-table (setq syntax (pop body)) (setq declare-syntax nil))
(:after-hook (setq after-hook (pop body)))
(:interactive (setq interactive (pop body)))
(_ (pop body))))
(setq docstring (derived-mode-make-docstring
parent child docstring syntax abbrev))
`(progn
(defvar ,hook nil)
(unless (get ',hook 'variable-documentation)
(put ',hook 'variable-documentation
,(format "Hook run after entering `%S'.
No problems result if this variable is not bound.
`add-hook' automatically binds it. (This is true for all hook variables.)"
child)))
(unless (boundp ',map)
(put ',map 'definition-name ',child))
(with-no-warnings (defvar ,map (make-sparse-keymap)))
(unless (get ',map 'variable-documentation)
(put ',map 'variable-documentation
(purecopy ,(format "Keymap for `%s'." child))))
,(if declare-syntax
`(progn
(defvar ,syntax)
(unless (boundp ',syntax)
(put ',syntax 'definition-name ',child)
(defvar ,syntax (make-syntax-table)))
(unless (get ',syntax 'variable-documentation)
(put ',syntax 'variable-documentation
(purecopy ,(format "Syntax table for `%s'." child))))))
,(if declare-abbrev
`(progn
(defvar ,abbrev)
(unless (boundp ',abbrev)
(put ',abbrev 'definition-name ',child)
(defvar ,abbrev
(progn (define-abbrev-table ',abbrev nil) ,abbrev)))
(unless (get ',abbrev 'variable-documentation)
(put ',abbrev 'variable-documentation
(purecopy ,(format "Abbrev table for `%s'." child))))))
(if (fboundp 'derived-mode-set-parent) ;; Emacs≥30.1
(derived-mode-set-parent ',child ',parent)
(put ',child 'derived-mode-parent ',parent))
,(if group `(put ',child 'custom-mode-group ,group))
(defun ,child ()
,docstring
,(and interactive '(interactive))
; Run the parent.
(delay-mode-hooks
(,(or parent 'kill-all-local-variables))
; Identify the child mode.
(setq major-mode (quote ,child))
(setq mode-name ,name)
; Identify special modes.
,(when parent
`(progn
(if (get (quote ,parent) 'mode-class)
(put (quote ,child) 'mode-class
(get (quote ,parent) 'mode-class)))
; Set up maps and tables.
(unless (keymap-parent ,map)
;; It would probably be better to set the keymap's parent
;; at the toplevel rather than inside the mode function,
;; but this is not easy for at least the following reasons:
;; - the parent (and its keymap) may not yet be loaded.
;; - the parent's keymap name may be called something else
;; than <parent>-mode-map.
(set-keymap-parent ,map (current-local-map)))
,(when declare-syntax
`(let ((parent (char-table-parent ,syntax)))
(unless (and parent
(not (eq parent (standard-syntax-table))))
(set-char-table-parent ,syntax (syntax-table)))))
,(when declare-abbrev
`(unless (or (abbrev-table-get ,abbrev :parents)
;; This can happen if the major mode defines
;; the abbrev-table to be its parent's.
(eq ,abbrev local-abbrev-table))
(abbrev-table-put ,abbrev :parents
(list local-abbrev-table))))))
(use-local-map ,map)
,(when syntax `(set-syntax-table ,syntax))
,(when abbrev `(setq local-abbrev-table ,abbrev))
; Splice in the body (if any).
,@body
)
,@(when after-hook
`((push (lambda () ,after-hook) delayed-after-hook-functions)))
;; Run the hooks (and delayed-after-hook-functions), if any.
(run-mode-hooks ',hook)))))