Commit | Line | Data |
---|---|---|
5a7a545c | 1 | ;;; easy-mmode.el --- easy definition for major and minor modes. |
6b279740 | 2 | |
c8c21615 | 3 | ;; Copyright (C) 1997,2000 Free Software Foundation, Inc. |
6b279740 RS |
4 | |
5 | ;; Author: Georges Brun-Cottan <Georges.Brun-Cottan@inria.fr> | |
29cc3b84 | 6 | ;; Maintainer: Stefan Monnier <monnier@gnu.org> |
6b279740 RS |
7 | |
8 | ;; This file is part of GNU Emacs. | |
9 | ||
10 | ;; GNU Emacs is free software; you can redistribute it and/or modify | |
11 | ;; it under the terms of the GNU General Public License as published by | |
12 | ;; the Free Software Foundation; either version 2, or (at your option) | |
13 | ;; any later version. | |
14 | ||
15 | ;; GNU Emacs is distributed in the hope that it will be useful, | |
16 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | ;; GNU General Public License for more details. | |
19 | ||
20 | ;; You should have received a copy of the GNU General Public License | |
21 | ;; along with GNU Emacs; see the file COPYING. If not, write to the | |
22 | ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, | |
23 | ;; Boston, MA 02111-1307, USA. | |
24 | ||
25 | ;;; Commentary: | |
26 | ||
27 | ;; Minor modes are useful and common. This package makes defining a | |
28 | ;; minor mode easy, by focusing on the writing of the minor mode | |
29 | ;; functionalities themselves. Moreover, this package enforces a | |
30 | ;; conventional naming of user interface primitives, making things | |
31 | ;; natural for the minor-mode end-users. | |
32 | ||
33 | ;; For each mode, easy-mmode defines the following: | |
34 | ;; <mode> : The minor mode predicate. A buffer-local variable. | |
35 | ;; <mode>-map : The keymap possibly associated to <mode>. | |
c8c21615 SM |
36 | ;; <mode>-hook : The hook run at the end of the toggle function. |
37 | ;; see `define-minor-mode' documentation | |
6b279740 RS |
38 | ;; |
39 | ;; eval | |
c8c21615 | 40 | ;; (pp (macroexpand '(define-minor-mode <your-mode> <doc>))) |
6b279740 RS |
41 | ;; to check the result before using it. |
42 | ||
43 | ;; The order in which minor modes are installed is important. Keymap | |
44 | ;; lookup proceeds down minor-mode-map-alist, and the order there | |
45 | ;; tends to be the reverse of the order in which the modes were | |
46 | ;; installed. Perhaps there should be a feature to let you specify | |
47 | ;; orderings. | |
48 | ||
5a7a545c SM |
49 | ;; Additionally to `define-minor-mode', the package provides convenient |
50 | ;; ways to define keymaps, and other helper functions for major and minor modes. | |
6b279740 | 51 | |
5a7a545c | 52 | ;;; Code: |
6b279740 | 53 | |
be22f4cc SM |
54 | (eval-when-compile (require 'cl)) |
55 | ||
b5bbbb76 SM |
56 | (defun easy-mmode-pretty-mode-name (mode &optional lighter) |
57 | "Turn the symbol MODE into a string intended for the user. | |
58 | If provided LIGHTER will be used to help choose capitalization." | |
59 | (let* ((case-fold-search t) | |
b643ec53 SM |
60 | (name (concat (replace-regexp-in-string |
61 | "-Minor" " minor" | |
62 | (capitalize (replace-regexp-in-string | |
63 | "-mode\\'" "" (symbol-name mode)))) | |
b5bbbb76 SM |
64 | " mode"))) |
65 | (if (not (stringp lighter)) name | |
66 | (setq lighter (replace-regexp-in-string "\\`\\s-+\\|\\-s+\\'" "" lighter)) | |
67 | (replace-regexp-in-string lighter lighter name t t)))) | |
3837de12 | 68 | |
6b279740 | 69 | ;;;###autoload |
29cc3b84 SM |
70 | (defalias 'easy-mmode-define-minor-mode 'define-minor-mode) |
71 | ;;;###autoload | |
72 | (defmacro define-minor-mode (mode doc &optional init-value lighter keymap &rest body) | |
6b279740 | 73 | "Define a new minor mode MODE. |
b5bbbb76 | 74 | This function defines the associated control variable MODE, keymap MODE-map, |
bff53411 | 75 | toggle command MODE, and hook MODE-hook. |
6b279740 RS |
76 | |
77 | DOC is the documentation for the mode toggle command. | |
29cc3b84 | 78 | Optional INIT-VALUE is the initial value of the mode's variable. |
c8c21615 | 79 | Optional LIGHTER is displayed in the modeline when the mode is on. |
6b279740 | 80 | Optional KEYMAP is the default (defvar) keymap bound to the mode keymap. |
b5bbbb76 | 81 | If it is a list, it is passed to `easy-mmode-define-keymap' |
bff53411 SM |
82 | in order to build a valid keymap. It's generally better to use |
83 | a separate MODE-map variable than to use this argument. | |
84 | The above three arguments can be skipped if keyword arguments are | |
85 | used (see below). | |
86 | ||
29cc3b84 | 87 | BODY contains code that will be executed each time the mode is (dis)activated. |
b5bbbb76 SM |
88 | It will be executed after any toggling but before running the hooks. |
89 | BODY can start with a list of CL-style keys specifying additional arguments. | |
bff53411 SM |
90 | The following keyword arguments are supported: |
91 | :group Followed by the group name to use for any generated `defcustom'. | |
92 | :global If non-nil specifies that the minor mode is not meant to be | |
93 | buffer-local. By default, the variable is made buffer-local. | |
bff53411 SM |
94 | :init-value Same as the INIT-VALUE argument. |
95 | :lighter Same as the LIGHTER argument." | |
96 | ;; Allow skipping the first three args. | |
97 | (cond | |
98 | ((keywordp init-value) | |
99 | (setq body (list* init-value lighter keymap body) | |
100 | init-value nil lighter nil keymap nil)) | |
101 | ((keywordp lighter) | |
102 | (setq body (list* lighter keymap body) lighter nil keymap nil)) | |
103 | ((keywordp keymap) (push keymap body) (setq keymap nil))) | |
104 | ||
6b279740 | 105 | (let* ((mode-name (symbol-name mode)) |
b5bbbb76 | 106 | (pretty-name (easy-mmode-pretty-mode-name mode lighter)) |
c8c21615 | 107 | (globalp nil) |
bff53411 | 108 | (togglep t) ;why would you ever want to toggle? |
0a74e3bf SM |
109 | (group nil) |
110 | (extra-args nil) | |
1328a6df SM |
111 | (keymap-sym (if (and keymap (symbolp keymap)) keymap |
112 | (intern (concat mode-name "-map")))) | |
b5bbbb76 SM |
113 | (hook (intern (concat mode-name "-hook"))) |
114 | (hook-on (intern (concat mode-name "-on-hook"))) | |
115 | (hook-off (intern (concat mode-name "-off-hook")))) | |
116 | ||
b5bbbb76 | 117 | ;; Check keys. |
be22f4cc SM |
118 | (while (keywordp (car body)) |
119 | (case (pop body) | |
bff53411 SM |
120 | (:init-value (setq init-value (pop body))) |
121 | (:lighter (setq lighter (pop body))) | |
be22f4cc | 122 | (:global (setq globalp (pop body))) |
0a74e3bf SM |
123 | (:extra-args (setq extra-args (pop body))) |
124 | (:group (setq group (nconc group (list :group (pop body))))) | |
bff53411 | 125 | (t (pop body)))) |
eab6e8b9 | 126 | |
0a74e3bf SM |
127 | (unless group |
128 | ;; We might as well provide a best-guess default group. | |
129 | (setq group | |
130 | `(:group ',(intern (replace-regexp-in-string "-mode\\'" "" | |
131 | mode-name))))) | |
b5bbbb76 SM |
132 | ;; Add default properties to LIGHTER. |
133 | (unless (or (not (stringp lighter)) (get-text-property 0 'local-map lighter) | |
134 | (get-text-property 0 'keymap lighter)) | |
135 | (setq lighter | |
136 | (apply 'propertize lighter | |
137 | 'local-map (make-mode-line-mouse2-map mode) | |
138 | (unless (get-text-property 0 'help-echo lighter) | |
139 | (list 'help-echo | |
140 | (format "mouse-2: turn off %s" pretty-name)))))) | |
141 | ||
6b279740 | 142 | `(progn |
5e21ef7a | 143 | ;; Define the variable to enable or disable the mode. |
d5b037c5 SM |
144 | ,(if (not globalp) |
145 | `(progn | |
146 | (defvar ,mode ,init-value ,(format "Non-nil if %s is enabled. | |
b5bbbb76 | 147 | Use the function `%s' to change this variable." pretty-name mode)) |
d5b037c5 | 148 | (make-variable-buffer-local ',mode)) |
6b279740 | 149 | |
1328a6df SM |
150 | (let ((curfile (or (and (boundp 'byte-compile-current-file) |
151 | byte-compile-current-file) | |
152 | load-file-name))) | |
153 | `(defcustom ,mode ,init-value | |
bff53411 SM |
154 | ,(format "Toggle %s on or off. |
155 | See the command `%s' for a description of this minor-mode. | |
d5b037c5 SM |
156 | Setting this variable directly does not take effect; |
157 | use either \\[customize] or the function `%s'." | |
bff53411 | 158 | pretty-name mode mode) |
1328a6df SM |
159 | :set (lambda (symbol value) (funcall symbol (or value 0))) |
160 | :initialize 'custom-initialize-default | |
0a74e3bf | 161 | ,@group |
1328a6df SM |
162 | :type 'boolean |
163 | ,@(when curfile | |
164 | (list | |
165 | :require | |
166 | (list 'quote | |
167 | (intern (file-name-nondirectory | |
168 | (file-name-sans-extension curfile))))))))) | |
169 | ||
b5bbbb76 | 170 | ;; The actual function. |
0a74e3bf | 171 | (defun ,mode (&optional arg ,@extra-args) |
b5bbbb76 | 172 | ,(or doc |
bff53411 SM |
173 | (format (concat "Toggle %s on or off. |
174 | Interactively, with no prefix argument, toggle the mode. | |
175 | With universal prefix ARG " (unless togglep "(or if ARG is nil) ") "turn mode on. | |
b5bbbb76 | 176 | With zero or negative ARG turn mode off. |
bff53411 SM |
177 | \\{%s}") pretty-name keymap-sym)) |
178 | (interactive (list (or current-prefix-arg (if ,mode 0 1)))) | |
b5bbbb76 SM |
179 | (setq ,mode |
180 | (if arg | |
181 | (> (prefix-numeric-value arg) 0) | |
bff53411 | 182 | ,(if togglep `(not ,mode) t))) |
b5bbbb76 SM |
183 | ,@body |
184 | ;; The on/off hooks are here for backward compatibility only. | |
185 | (run-hooks ',hook (if ,mode ',hook-on ',hook-off)) | |
186 | ;; Return the new setting. | |
187 | (if (interactive-p) | |
188 | (message ,(format "%s %%sabled" pretty-name) | |
189 | (if ,mode "en" "dis"))) | |
bff53411 | 190 | (force-mode-line-update) |
b5bbbb76 | 191 | ,mode) |
6b279740 | 192 | |
1328a6df SM |
193 | ;; Autoloading an easy-mmode-define-minor-mode autoloads |
194 | ;; everything up-to-here. | |
195 | :autoload-end | |
196 | ||
0a74e3bf SM |
197 | ;; The toggle's hook. |
198 | (defcustom ,hook nil | |
199 | ,(format "Hook run at the end of function `%s'." mode-name) | |
200 | :group ,(cadr group) | |
201 | :type 'hook) | |
202 | ||
d5b037c5 | 203 | ;; Define the minor-mode keymap. |
1328a6df | 204 | ,(unless (symbolp keymap) ;nil is also a symbol. |
d5b037c5 | 205 | `(defvar ,keymap-sym |
1328a6df SM |
206 | (let ((m ,keymap)) |
207 | (cond ((keymapp m) m) | |
208 | ((listp m) (easy-mmode-define-keymap m)) | |
209 | (t (error "Invalid keymap %S" ,keymap)))) | |
d5b037c5 SM |
210 | ,(format "Keymap for `%s'." mode-name))) |
211 | ||
b5bbbb76 | 212 | (add-minor-mode ',mode ',lighter |
1328a6df | 213 | ,(if keymap keymap-sym |
cb5da1a3 SM |
214 | `(if (boundp ',keymap-sym) |
215 | (symbol-value ',keymap-sym)))) | |
bff53411 | 216 | |
c8c21615 SM |
217 | ;; If the mode is global, call the function according to the default. |
218 | ,(if globalp `(if ,mode (,mode 1)))))) | |
5a7a545c | 219 | \f |
be22f4cc SM |
220 | ;;; |
221 | ;;; make global minor mode | |
222 | ;;; | |
223 | ||
d5b037c5 | 224 | ;;;###autoload |
be22f4cc SM |
225 | (defmacro easy-mmode-define-global-mode (global-mode mode turn-on |
226 | &rest keys) | |
bff53411 | 227 | "Make GLOBAL-MODE out of the buffer-local minor MODE. |
be22f4cc SM |
228 | TURN-ON is a function that will be called with no args in every buffer |
229 | and that should try to turn MODE on if applicable for that buffer. | |
230 | KEYS is a list of CL-style keyword arguments: | |
231 | :group to specify the custom group." | |
0a74e3bf | 232 | (let* ((global-mode-name (symbol-name global-mode)) |
be22f4cc SM |
233 | (pretty-name (easy-mmode-pretty-mode-name mode)) |
234 | (pretty-global-name (easy-mmode-pretty-mode-name global-mode)) | |
0a74e3bf SM |
235 | (group nil) |
236 | (extra-args nil) | |
be22f4cc SM |
237 | (buffers (intern (concat global-mode-name "-buffers"))) |
238 | (cmmh (intern (concat global-mode-name "-cmmh")))) | |
239 | ||
240 | ;; Check keys. | |
241 | (while (keywordp (car keys)) | |
242 | (case (pop keys) | |
0a74e3bf SM |
243 | (:extra-args (setq extra-args (pop keys))) |
244 | (:group (setq group (nconc group (list :group (pop keys))))) | |
be22f4cc SM |
245 | (t (setq keys (cdr keys))))) |
246 | ||
0a74e3bf SM |
247 | (unless group |
248 | ;; We might as well provide a best-guess default group. | |
249 | (setq group | |
250 | `(:group ',(intern (replace-regexp-in-string "-mode\\'" "" | |
251 | (symbol-name mode)))))) | |
be22f4cc | 252 | `(progn |
be22f4cc SM |
253 | ;; The actual global minor-mode |
254 | (define-minor-mode ,global-mode | |
255 | ,(format "Toggle %s in every buffer. | |
256 | With prefix ARG, turn %s on if and only if ARG is positive. | |
257 | %s is actually not turned on in every buffer but only in those | |
258 | in which `%s' turns it on." | |
259 | pretty-name pretty-global-name pretty-name turn-on) | |
0a74e3bf | 260 | :global t :extra-args ,extra-args ,@group |
be22f4cc SM |
261 | |
262 | ;; Setup hook to handle future mode changes and new buffers. | |
263 | (if ,global-mode | |
d5b037c5 SM |
264 | (progn |
265 | (add-hook 'find-file-hooks ',buffers) | |
266 | (add-hook 'change-major-mode-hook ',cmmh)) | |
267 | (remove-hook 'find-file-hooks ',buffers) | |
be22f4cc SM |
268 | (remove-hook 'change-major-mode-hook ',cmmh)) |
269 | ||
270 | ;; Go through existing buffers. | |
271 | (dolist (buf (buffer-list)) | |
272 | (with-current-buffer buf | |
34befa9a | 273 | (if ,global-mode (,turn-on) (when ,mode (,mode -1)))))) |
be22f4cc | 274 | |
1328a6df SM |
275 | ;; Autoloading easy-mmode-define-global-mode |
276 | ;; autoloads everything up-to-here. | |
277 | :autoload-end | |
278 | ||
be22f4cc SM |
279 | ;; List of buffers left to process. |
280 | (defvar ,buffers nil) | |
281 | ||
282 | ;; The function that calls TURN-ON in each buffer. | |
283 | (defun ,buffers () | |
be22f4cc | 284 | (remove-hook 'post-command-hook ',buffers) |
d5b037c5 SM |
285 | (while ,buffers |
286 | (let ((buf (pop ,buffers))) | |
287 | (when (buffer-live-p buf) | |
288 | (with-current-buffer buf (,turn-on)))))) | |
be22f4cc SM |
289 | |
290 | ;; The function that catches kill-all-local-variables. | |
291 | (defun ,cmmh () | |
292 | (add-to-list ',buffers (current-buffer)) | |
d5b037c5 | 293 | (add-hook 'post-command-hook ',buffers))))) |
be22f4cc | 294 | |
5a7a545c SM |
295 | ;;; |
296 | ;;; easy-mmode-defmap | |
297 | ;;; | |
298 | ||
299 | (if (fboundp 'set-keymap-parents) | |
300 | (defalias 'easy-mmode-set-keymap-parents 'set-keymap-parents) | |
301 | (defun easy-mmode-set-keymap-parents (m parents) | |
302 | (set-keymap-parent | |
303 | m | |
304 | (cond | |
305 | ((not (consp parents)) parents) | |
306 | ((not (cdr parents)) (car parents)) | |
307 | (t (let ((m (copy-keymap (pop parents)))) | |
308 | (easy-mmode-set-keymap-parents m parents) | |
309 | m)))))) | |
310 | ||
5d78d57d | 311 | ;;;###autoload |
5a7a545c SM |
312 | (defun easy-mmode-define-keymap (bs &optional name m args) |
313 | "Return a keymap built from bindings BS. | |
314 | BS must be a list of (KEY . BINDING) where | |
3837de12 SM |
315 | KEY and BINDINGS are suitable for `define-key'. |
316 | Optional NAME is passed to `make-sparse-keymap'. | |
317 | Optional map M can be used to modify an existing map. | |
165958d2 | 318 | ARGS is a list of additional keyword arguments." |
5a7a545c SM |
319 | (let (inherit dense suppress) |
320 | (while args | |
321 | (let ((key (pop args)) | |
322 | (val (pop args))) | |
be22f4cc | 323 | (case key |
165958d2 | 324 | (:name (setq name val)) |
be22f4cc SM |
325 | (:dense (setq dense val)) |
326 | (:inherit (setq inherit val)) | |
327 | (:group) | |
5a7a545c SM |
328 | ;;((eq key :suppress) (setq suppress val)) |
329 | (t (message "Unknown argument %s in defmap" key))))) | |
330 | (unless (keymapp m) | |
331 | (setq bs (append m bs)) | |
332 | (setq m (if dense (make-keymap name) (make-sparse-keymap name)))) | |
333 | (dolist (b bs) | |
334 | (let ((keys (car b)) | |
335 | (binding (cdr b))) | |
336 | (dolist (key (if (consp keys) keys (list keys))) | |
337 | (cond | |
338 | ((symbolp key) | |
339 | (substitute-key-definition key binding m global-map)) | |
340 | ((null binding) | |
341 | (unless (keymapp (lookup-key m key)) (define-key m key binding))) | |
342 | ((let ((o (lookup-key m key))) | |
343 | (or (null o) (numberp o) (eq o 'undefined))) | |
344 | (define-key m key binding)))))) | |
345 | (cond | |
346 | ((keymapp inherit) (set-keymap-parent m inherit)) | |
347 | ((consp inherit) (easy-mmode-set-keymap-parents m inherit))) | |
348 | m)) | |
349 | ||
350 | ;;;###autoload | |
351 | (defmacro easy-mmode-defmap (m bs doc &rest args) | |
5d78d57d SM |
352 | `(defconst ,m |
353 | (easy-mmode-define-keymap ,bs nil (if (boundp ',m) ,m) ,(cons 'list args)) | |
354 | ,doc)) | |
5a7a545c SM |
355 | |
356 | \f | |
357 | ;;; | |
358 | ;;; easy-mmode-defsyntax | |
359 | ;;; | |
360 | ||
361 | (defun easy-mmode-define-syntax (css args) | |
e4fe3460 SM |
362 | (let ((st (make-syntax-table (plist-get args :copy))) |
363 | (parent (plist-get args :inherit))) | |
5a7a545c SM |
364 | (dolist (cs css) |
365 | (let ((char (car cs)) | |
366 | (syntax (cdr cs))) | |
367 | (if (sequencep char) | |
e4ad5f9e | 368 | (mapcar (lambda (c) (modify-syntax-entry c syntax st)) char) |
5a7a545c | 369 | (modify-syntax-entry char syntax st)))) |
e4fe3460 SM |
370 | (if parent (set-char-table-parent |
371 | st (if (symbolp parent) (symbol-value parent) parent))) | |
5a7a545c SM |
372 | st)) |
373 | ||
374 | ;;;###autoload | |
375 | (defmacro easy-mmode-defsyntax (st css doc &rest args) | |
e4fe3460 SM |
376 | "Define variable ST as a syntax-table. |
377 | CSS contains a list of syntax specifications of the form (CHAR . SYNTAX). | |
378 | " | |
e4ad5f9e SM |
379 | `(progn |
380 | (autoload 'easy-mmode-define-syntax "easy-mmode") | |
381 | (defconst ,st (easy-mmode-define-syntax ,css ,(cons 'list args)) doc))) | |
5a7a545c SM |
382 | |
383 | ||
384 | \f | |
c7ea3acc SM |
385 | ;;; |
386 | ;;; easy-mmode-define-navigation | |
387 | ;;; | |
388 | ||
389 | (defmacro easy-mmode-define-navigation (base re &optional name endfun) | |
390 | "Define BASE-next and BASE-prev to navigate in the buffer. | |
391 | RE determines the places the commands should move point to. | |
eed083e6 | 392 | NAME should describe the entities matched by RE. It is used to build |
c7ea3acc SM |
393 | the docstrings of the two functions. |
394 | BASE-next also tries to make sure that the whole entry is visible by | |
395 | searching for its end (by calling ENDFUN if provided or by looking for | |
396 | the next entry) and recentering if necessary. | |
397 | ENDFUN should return the end position (with or without moving point)." | |
398 | (let* ((base-name (symbol-name base)) | |
399 | (prev-sym (intern (concat base-name "-prev"))) | |
400 | (next-sym (intern (concat base-name "-next")))) | |
36a5b60e | 401 | (unless name (setq name (symbol-name base-name))) |
c7ea3acc | 402 | `(progn |
b5bbbb76 SM |
403 | (add-to-list 'debug-ignored-errors |
404 | ,(concat "^No \\(previous\\|next\\) " (regexp-quote name))) | |
c7ea3acc | 405 | (defun ,next-sym (&optional count) |
36a5b60e | 406 | ,(format "Go to the next COUNT'th %s." name) |
c7ea3acc SM |
407 | (interactive) |
408 | (unless count (setq count 1)) | |
409 | (if (< count 0) (,prev-sym (- count)) | |
410 | (if (looking-at ,re) (incf count)) | |
eed083e6 SM |
411 | (if (not (re-search-forward ,re nil t count)) |
412 | (if (looking-at ,re) | |
413 | (goto-char (or ,(if endfun `(,endfun)) (point-max))) | |
414 | (error ,(format "No next %s" name))) | |
415 | (goto-char (match-beginning 0)) | |
416 | (when (eq (current-buffer) (window-buffer (selected-window))) | |
417 | (let ((endpt (or (save-excursion | |
418 | ,(if endfun `(,endfun) | |
419 | `(re-search-forward ,re nil t 2))) | |
420 | (point-max)))) | |
421 | (unless (pos-visible-in-window-p endpt nil t) | |
422 | (recenter '(0)))))))) | |
c7ea3acc SM |
423 | (defun ,prev-sym (&optional count) |
424 | ,(format "Go to the previous COUNT'th %s" (or name base-name)) | |
425 | (interactive) | |
426 | (unless count (setq count 1)) | |
427 | (if (< count 0) (,next-sym (- count)) | |
36a5b60e | 428 | (unless (re-search-backward ,re nil t count) |
c8c21615 | 429 | (error ,(format "No previous %s" name)))))))) |
5a7a545c | 430 | |
6b279740 RS |
431 | (provide 'easy-mmode) |
432 | ||
433 | ;;; easy-mmode.el ends here |