Remove unnecessary leading-star in docstrings.
[emacs.git] / lisp / hi-lock.el
blob4c61be5529e9946559197eb9fb7f2933ca546867
1 ;;; hi-lock.el --- minor mode for interactive automatic highlighting
3 ;; Copyright (C) 2000, 2001, 2002, 2003, 2004,
4 ;; 2005 Free Software Foundation, Inc.
6 ;; Author: David M. Koppelman, koppel@ee.lsu.edu
7 ;; Keywords: faces, minor-mode, matching, display
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software; you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation; either version 2, or (at your option)
14 ;; any later version.
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs; see the file COPYING. If not, write to the
23 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
24 ;; Boston, MA 02110-1301, USA.
26 ;;; Commentary:
28 ;; With the hi-lock commands text matching interactively entered
29 ;; regexp's can be highlighted. For example, `M-x highlight-regexp
30 ;; RET clearly RET RET' will highlight all occurrences of `clearly'
31 ;; using a yellow background face. New occurrences of `clearly' will
32 ;; be highlighted as they are typed. `M-x unhighlight-regexp RET'
33 ;; will remove the highlighting. Any existing face can be used for
34 ;; highlighting and a set of appropriate faces is provided. The
35 ;; regexps can be written into the current buffer in a form that will
36 ;; be recognized the next time the corresponding file is read.
38 ;; Applications:
40 ;; In program source code highlight a variable to quickly see all
41 ;; places it is modified or referenced:
42 ;; M-x highlight-regexp ground_contact_switches_closed RET RET
44 ;; In a shell or other buffer that is showing lots of program
45 ;; output, highlight the parts of the output you're interested in:
46 ;; M-x highlight-regexp Total execution time [0-9]+ RET hi-blue-b RET
48 ;; In buffers displaying tables, highlight the lines you're interested in:
49 ;; M-x highlight-lines-matching-regexp January 2000 RET hi-black-b RET
51 ;; When writing text, highlight personal cliches. This can be
52 ;; amusing.
53 ;; M-x highlight-phrase as can be seen RET RET
55 ;; Setup:
57 ;; Put the following code in your .emacs file. This turns on
58 ;; hi-lock mode and adds a "Regexp Highlighting" entry
59 ;; to the edit menu.
61 ;; (hi-lock-mode 1)
63 ;; You might also want to bind the hi-lock commands to more
64 ;; finger-friendly sequences:
66 ;; (define-key hi-lock-map "\C-z\C-h" 'highlight-lines-matching-regexp)
67 ;; (define-key hi-lock-map "\C-zi" 'hi-lock-find-patterns)
68 ;; (define-key hi-lock-map "\C-zh" 'highlight-regexp)
69 ;; (define-key hi-lock-map "\C-zp" 'highlight-phrase)
70 ;; (define-key hi-lock-map "\C-zr" 'unhighlight-regexp)
71 ;; (define-key hi-lock-map "\C-zb" 'hi-lock-write-interactive-patterns))
73 ;; See the documentation for hi-lock-mode `C-h f hi-lock-mode' for
74 ;; additional instructions.
76 ;; Sample file patterns:
78 ; Hi-lock: (("^;;; .*" (0 (quote hi-black-hb) t)))
79 ; Hi-lock: ( ("make-variable-buffer-\\(local\\)" (0 font-lock-keyword-face)(1 'italic append)))))
80 ; Hi-lock: end
82 ;;; Code:
84 (eval-and-compile
85 (require 'font-lock))
87 (defgroup hi-lock nil
88 "Interactively add and remove font-lock patterns for highlighting text."
89 :link '(custom-manual "(emacs)Highlight Interactively")
90 :group 'font-lock)
92 (defcustom hi-lock-file-patterns-range 10000
93 "Limit of search in a buffer for hi-lock patterns.
94 When a file is visited and hi-lock mode is on patterns starting
95 up to this limit are added to font-lock's patterns. See documentation
96 of functions `hi-lock-mode' and `hi-lock-find-patterns'."
97 :type 'integer
98 :group 'hi-lock)
100 (defcustom hi-lock-exclude-modes
101 '(rmail-mode mime/viewer-mode gnus-article-mode)
102 "List of major modes in which hi-lock will not run.
103 For security reasons since font lock patterns can specify function
104 calls."
105 :type '(repeat symbol)
106 :group 'hi-lock)
109 (defgroup hi-lock-faces nil
110 "Faces for hi-lock."
111 :group 'hi-lock
112 :group 'faces)
114 (defface hi-yellow
115 '((((min-colors 88) (background dark))
116 (:background "yellow1" :foreground "black"))
117 (((background dark)) (:background "yellow" :foreground "black"))
118 (((min-colors 88)) (:background "yellow1"))
119 (t (:background "yellow")))
120 "Default face for hi-lock mode."
121 :group 'hi-lock-faces)
123 (defface hi-pink
124 '((((background dark)) (:background "pink" :foreground "black"))
125 (t (:background "pink")))
126 "Face for hi-lock mode."
127 :group 'hi-lock-faces)
129 (defface hi-green
130 '((((min-colors 88) (background dark))
131 (:background "green1" :foreground "black"))
132 (((background dark)) (:background "green" :foreground "black"))
133 (((min-colors 88)) (:background "green1"))
134 (t (:background "green")))
135 "Face for hi-lock mode."
136 :group 'hi-lock-faces)
138 (defface hi-blue
139 '((((background dark)) (:background "light blue" :foreground "black"))
140 (t (:background "light blue")))
141 "Face for hi-lock mode."
142 :group 'hi-lock-faces)
144 (defface hi-black-b
145 '((t (:weight bold)))
146 "Face for hi-lock mode."
147 :group 'hi-lock-faces)
149 (defface hi-blue-b
150 '((((min-colors 88)) (:weight bold :foreground "blue1"))
151 (t (:weight bold :foreground "blue")))
152 "Face for hi-lock mode."
153 :group 'hi-lock-faces)
155 (defface hi-green-b
156 '((((min-colors 88)) (:weight bold :foreground "green1"))
157 (t (:weight bold :foreground "green")))
158 "Face for hi-lock mode."
159 :group 'hi-lock-faces)
161 (defface hi-red-b
162 '((((min-colors 88)) (:weight bold :foreground "red1"))
163 (t (:weight bold :foreground "red")))
164 "Face for hi-lock mode."
165 :group 'hi-lock-faces)
167 (defface hi-black-hb
168 '((t (:weight bold :height 1.67 :inherit variable-pitch)))
169 "Face for hi-lock mode."
170 :group 'hi-lock-faces)
172 (defvar hi-lock-file-patterns nil
173 "Patterns found in file for hi-lock. Should not be changed.")
175 (defvar hi-lock-interactive-patterns nil
176 "Patterns provided to hi-lock by user. Should not be changed.")
178 (defvar hi-lock-face-history
179 (list "hi-yellow" "hi-pink" "hi-green" "hi-blue" "hi-black-b"
180 "hi-blue-b" "hi-red-b" "hi-green-b" "hi-black-hb")
181 "History list of faces for hi-lock interactive functions.")
183 ;(dolist (f hi-lock-face-history) (unless (facep f) (error "%s not a face" f)))
185 (defvar hi-lock-regexp-history nil
186 "History of regexps used for interactive fontification.")
188 (defvar hi-lock-file-patterns-prefix "Hi-lock"
189 "Regexp for finding hi-lock patterns at top of file.")
191 (make-variable-buffer-local 'hi-lock-interactive-patterns)
192 (put 'hi-lock-interactive-patterns 'permanent-local t)
193 (make-variable-buffer-local 'hi-lock-regexp-history)
194 (put 'hi-lock-regexp-history 'permanent-local t)
195 (make-variable-buffer-local 'hi-lock-file-patterns)
196 (put 'hi-lock-file-patterns 'permanent-local t)
198 (defvar hi-lock-menu (make-sparse-keymap "Hi Lock")
199 "Menu for hi-lock mode.")
201 (define-key-after hi-lock-menu [highlight-regexp]
202 '(menu-item "Highlight Regexp..." highlight-regexp
203 :help "Highlight text matching PATTERN (a regexp)."))
205 (define-key-after hi-lock-menu [highlight-phrase]
206 '(menu-item "Highlight Phrase..." highlight-phrase
207 :help "Highlight text matching PATTERN (a regexp processed to match phrases)."))
209 (define-key-after hi-lock-menu [highlight-lines-matching-regexp]
210 '(menu-item "Highlight Lines..." highlight-lines-matching-regexp
211 :help "Highlight lines containing match of PATTERN (a regexp).."))
213 (define-key-after hi-lock-menu [unhighlight-regexp]
214 '(menu-item "Remove Highlighting..." unhighlight-regexp
215 :help "Remove previously entered highlighting pattern."
216 :enable hi-lock-interactive-patterns))
218 (define-key-after hi-lock-menu [hi-lock-write-interactive-patterns]
219 '(menu-item "Patterns to Buffer" hi-lock-write-interactive-patterns
220 :help "Insert interactively added REGEXPs into buffer at point."
221 :enable hi-lock-interactive-patterns))
223 (define-key-after hi-lock-menu [hi-lock-find-patterns]
224 '(menu-item "Patterns from Buffer" hi-lock-find-patterns
225 :help "Use patterns (if any) near top of buffer."))
227 (defvar hi-lock-map (make-sparse-keymap "Hi Lock")
228 "Key map for hi-lock.")
230 (define-key hi-lock-map "\C-xwi" 'hi-lock-find-patterns)
231 (define-key hi-lock-map "\C-xwl" 'highlight-lines-matching-regexp)
232 (define-key hi-lock-map "\C-xwp" 'highlight-phrase)
233 (define-key hi-lock-map "\C-xwh" 'highlight-regexp)
234 (define-key hi-lock-map "\C-xwr" 'unhighlight-regexp)
235 (define-key hi-lock-map "\C-xwb" 'hi-lock-write-interactive-patterns)
237 ;; Visible Functions
240 ;;;###autoload
241 (define-minor-mode hi-lock-buffer-mode
242 "Toggle minor mode for interactively adding font-lock highlighting patterns.
244 If ARG positive turn hi-lock on. Issuing a hi-lock command will also
245 turn hi-lock on. When hi-lock is turned on, a \"Regexp Highlighting\"
246 submenu is added to the \"Edit\" menu. The commands in the submenu,
247 which can be called interactively, are:
249 \\[highlight-regexp] REGEXP FACE
250 Highlight matches of pattern REGEXP in current buffer with FACE.
252 \\[highlight-phrase] PHRASE FACE
253 Highlight matches of phrase PHRASE in current buffer with FACE.
254 (PHRASE can be any REGEXP, but spaces will be replaced by matches
255 to whitespace and initial lower-case letters will become case insensitive.)
257 \\[highlight-lines-matching-regexp] REGEXP FACE
258 Highlight lines containing matches of REGEXP in current buffer with FACE.
260 \\[unhighlight-regexp] REGEXP
261 Remove highlighting on matches of REGEXP in current buffer.
263 \\[hi-lock-write-interactive-patterns]
264 Write active REGEXPs into buffer as comments (if possible). They will
265 be read the next time file is loaded or when the \\[hi-lock-find-patterns] command
266 is issued. The inserted regexps are in the form of font lock keywords.
267 (See `font-lock-keywords') They may be edited and re-loaded with \\[hi-lock-find-patterns],
268 any valid `font-lock-keywords' form is acceptable.
270 \\[hi-lock-find-patterns]
271 Re-read patterns stored in buffer (in the format produced by \\[hi-lock-write-interactive-patterns]).
273 When hi-lock is started and if the mode is not excluded, the
274 beginning of the buffer is searched for lines of the form:
275 Hi-lock: FOO
276 where FOO is a list of patterns. These are added to the font lock keywords
277 already present. The patterns must start before position (number
278 of characters into buffer) `hi-lock-file-patterns-range'. Patterns
279 will be read until
280 Hi-lock: end
281 is found. A mode is excluded if it's in the list `hi-lock-exclude-modes'."
282 :group 'hi-lock
283 :lighter " H"
284 :global nil
285 :keymap hi-lock-map
286 (if hi-lock-buffer-mode
287 ;; Turned on.
288 (progn
289 (unless font-lock-mode (font-lock-mode 1))
290 (define-key-after menu-bar-edit-menu [hi-lock]
291 (cons "Regexp Highlighting" hi-lock-menu))
292 (hi-lock-find-patterns)
293 (add-hook 'font-lock-mode-hook 'hi-lock-font-lock-hook nil t))
294 ;; Turned off.
295 (when (or hi-lock-interactive-patterns
296 hi-lock-file-patterns)
297 (when hi-lock-interactive-patterns
298 (font-lock-remove-keywords nil hi-lock-interactive-patterns)
299 (setq hi-lock-interactive-patterns nil))
300 (when hi-lock-file-patterns
301 (font-lock-remove-keywords nil hi-lock-file-patterns)
302 (setq hi-lock-file-patterns nil))
303 (if font-lock-mode
304 (font-lock-fontify-buffer)))
305 (define-key-after menu-bar-edit-menu [hi-lock] nil)
306 (remove-hook 'font-lock-mode-hook 'hi-lock-font-lock-hook t)))
308 ;;;###autoload
309 (define-global-minor-mode hi-lock-mode
310 hi-lock-buffer-mode turn-on-hi-lock-if-enabled
311 :group 'hi-lock)
313 (defun turn-on-hi-lock-if-enabled ()
314 (unless (memq major-mode hi-lock-exclude-modes)
315 (hi-lock-buffer-mode 1)))
317 ;;;###autoload
318 (defalias 'highlight-lines-matching-regexp 'hi-lock-line-face-buffer)
319 ;;;###autoload
320 (defun hi-lock-line-face-buffer (regexp &optional face)
321 "Set face of all lines containing a match of REGEXP to FACE.
323 Interactively, prompt for REGEXP then FACE. Buffer-local history
324 list maintained for regexps, global history maintained for faces.
325 \\<minibuffer-local-map>Use \\[next-history-element] and \\[previous-history-element] to retrieve next or previous history item.
326 \(See info node `Minibuffer History')"
327 (interactive
328 (list
329 (hi-lock-regexp-okay
330 (read-from-minibuffer "Regexp to highlight line: "
331 (cons (or (car hi-lock-regexp-history) "") 1 )
332 nil nil 'hi-lock-regexp-history))
333 (hi-lock-read-face-name)))
334 (or (facep face) (setq face 'hi-yellow))
335 (unless hi-lock-buffer-mode (hi-lock-buffer-mode 1))
336 (hi-lock-set-pattern
337 ;; The \\(?:...\\) grouping construct ensures that a leading ^, +, * or ?
338 ;; or a trailing $ in REGEXP will be interpreted correctly.
339 (concat "^.*\\(?:" regexp "\\).*$") face))
342 ;;;###autoload
343 (defalias 'highlight-regexp 'hi-lock-face-buffer)
344 ;;;###autoload
345 (defun hi-lock-face-buffer (regexp &optional face)
346 "Set face of each match of REGEXP to FACE.
348 Interactively, prompt for REGEXP then FACE. Buffer-local history
349 list maintained for regexps, global history maintained for faces.
350 \\<minibuffer-local-map>Use \\[next-history-element] and \\[previous-history-element] to retrieve next or previous history item.
351 \(See info node `Minibuffer History')"
352 (interactive
353 (list
354 (hi-lock-regexp-okay
355 (read-from-minibuffer "Regexp to highlight: "
356 (cons (or (car hi-lock-regexp-history) "") 1 )
357 nil nil 'hi-lock-regexp-history))
358 (hi-lock-read-face-name)))
359 (or (facep face) (setq face 'hi-yellow))
360 (unless hi-lock-buffer-mode (hi-lock-buffer-mode 1))
361 (hi-lock-set-pattern regexp face))
363 ;;;###autoload
364 (defalias 'highlight-phrase 'hi-lock-face-phrase-buffer)
365 ;;;###autoload
366 (defun hi-lock-face-phrase-buffer (regexp &optional face)
367 "Set face of each match of phrase REGEXP to FACE.
369 Whitespace in REGEXP converted to arbitrary whitespace and initial
370 lower-case letters made case insensitive."
371 (interactive
372 (list
373 (hi-lock-regexp-okay
374 (hi-lock-process-phrase
375 (read-from-minibuffer "Phrase to highlight: "
376 (cons (or (car hi-lock-regexp-history) "") 1 )
377 nil nil 'hi-lock-regexp-history)))
378 (hi-lock-read-face-name)))
379 (or (facep face) (setq face 'hi-yellow))
380 (unless hi-lock-buffer-mode (hi-lock-buffer-mode 1))
381 (hi-lock-set-pattern regexp face))
383 ;;;###autoload
384 (defalias 'unhighlight-regexp 'hi-lock-unface-buffer)
385 ;;;###autoload
386 (defun hi-lock-unface-buffer (regexp)
387 "Remove highlighting of each match to REGEXP set by hi-lock.
389 Interactively, prompt for REGEXP. Buffer-local history of inserted
390 regexp's maintained. Will accept only regexps inserted by hi-lock
391 interactive functions. \(See `hi-lock-interactive-patterns'.\)
392 \\<minibuffer-local-must-match-map>Use \\[minibuffer-complete] to complete a partially typed regexp.
393 \(See info node `Minibuffer History'.\)"
394 (interactive
395 (if (and (display-popup-menus-p) (vectorp (this-command-keys)))
396 (catch 'snafu
398 (x-popup-menu
400 (cons
401 `keymap
402 (cons "Select Pattern to Unhighlight"
403 (mapcar (lambda (pattern)
404 (list (car pattern)
405 (format
406 "%s (%s)" (car pattern)
407 (symbol-name
408 (car
409 (cdr (car (cdr (car (cdr pattern))))))))
410 (cons nil nil)
411 (car pattern)))
412 hi-lock-interactive-patterns))))
413 ;; If the user clicks outside the menu, meaning that they
414 ;; change their mind, x-popup-menu returns nil, and
415 ;; interactive signals a wrong number of arguments error.
416 ;; To prevent that, we return an empty string, which will
417 ;; effectively disable the rest of the function.
418 (throw 'snafu '(""))))
419 (let ((history-list (mapcar (lambda (p) (car p))
420 hi-lock-interactive-patterns)))
421 (unless hi-lock-interactive-patterns
422 (error "No highlighting to remove"))
423 (list
424 (completing-read "Regexp to unhighlight: "
425 hi-lock-interactive-patterns nil t
426 (car (car hi-lock-interactive-patterns))
427 (cons 'history-list 1))))))
428 (let ((keyword (assoc regexp hi-lock-interactive-patterns)))
429 (when keyword
430 (font-lock-remove-keywords nil (list keyword))
431 (setq hi-lock-interactive-patterns
432 (delq keyword hi-lock-interactive-patterns))
433 (font-lock-fontify-buffer))))
435 ;;;###autoload
436 (defun hi-lock-write-interactive-patterns ()
437 "Write interactively added patterns, if any, into buffer at point.
439 Interactively added patterns are those normally specified using
440 `highlight-regexp' and `highlight-lines-matching-regexp'; they can
441 be found in variable `hi-lock-interactive-patterns'."
442 (interactive)
443 (if (null hi-lock-interactive-patterns)
444 (error "There are no interactive patterns"))
445 (let ((beg (point)))
446 (mapcar
447 (lambda (pattern)
448 (insert (format "Hi-lock: (%s)\n" (prin1-to-string pattern))))
449 hi-lock-interactive-patterns)
450 (comment-region beg (point)))
451 (when (> (point) hi-lock-file-patterns-range)
452 (warn "Inserted keywords not close enough to top of file")))
454 ;; Implementation Functions
456 (defun hi-lock-process-phrase (phrase)
457 "Convert regexp PHRASE to a regexp that matches phrases.
459 Blanks in PHRASE replaced by regexp that matches arbitrary whitespace
460 and initial lower-case letters made case insensitive."
461 (let ((mod-phrase nil))
462 (setq mod-phrase
463 (replace-regexp-in-string
464 "\\<[a-z]" (lambda (m) (format "[%s%s]" (upcase m) m)) phrase))
465 (setq mod-phrase
466 (replace-regexp-in-string
467 "\\s-+" "[ \t\n]+" mod-phrase nil t))))
469 (defun hi-lock-regexp-okay (regexp)
470 "Return REGEXP if it appears suitable for a font-lock pattern.
472 Otherwise signal an error. A pattern that matches the null string is
473 not suitable."
474 (if (string-match regexp "")
475 (error "Regexp cannot match an empty string")
476 regexp))
478 (defun hi-lock-read-face-name ()
479 "Read face name from minibuffer with completion and history."
480 (intern (completing-read
481 "Highlight using face: "
482 obarray 'facep t
483 (cons (car hi-lock-face-history)
484 (let ((prefix
485 (try-completion
486 (substring (car hi-lock-face-history) 0 1)
487 (mapcar (lambda (f) (cons f f))
488 hi-lock-face-history))))
489 (if (and (stringp prefix)
490 (not (equal prefix (car hi-lock-face-history))))
491 (length prefix) 0)))
492 '(hi-lock-face-history . 0))))
494 (defun hi-lock-set-pattern (regexp face)
495 "Highlight REGEXP with face FACE."
496 (let ((pattern (list regexp (list 0 (list 'quote face) t))))
497 (unless (member pattern hi-lock-interactive-patterns)
498 (font-lock-add-keywords nil (list pattern))
499 (push pattern hi-lock-interactive-patterns)
500 (let ((buffer-undo-list t)
501 (inhibit-read-only t)
502 (mod (buffer-modified-p)))
503 (save-excursion
504 (goto-char (point-min))
505 (while (re-search-forward regexp (point-max) t)
506 (put-text-property
507 (match-beginning 0) (match-end 0) 'face face)
508 (goto-char (match-end 0))))
509 (set-buffer-modified-p mod)))))
511 (defun hi-lock-set-file-patterns (patterns)
512 "Replace file patterns list with PATTERNS and refontify."
513 (when (or hi-lock-file-patterns patterns)
514 (font-lock-remove-keywords nil hi-lock-file-patterns)
515 (setq hi-lock-file-patterns patterns)
516 (font-lock-add-keywords nil hi-lock-file-patterns)
517 (font-lock-fontify-buffer)))
519 (defun hi-lock-find-patterns ()
520 "Find patterns in current buffer for hi-lock."
521 (interactive)
522 (unless (memq major-mode hi-lock-exclude-modes)
523 (let ((all-patterns nil)
524 (target-regexp (concat "\\<" hi-lock-file-patterns-prefix ":")))
525 (save-excursion
526 (save-restriction
527 (widen)
528 (goto-char (point-min))
529 (re-search-forward target-regexp
530 (+ (point) hi-lock-file-patterns-range) t)
531 (beginning-of-line)
532 (while (and (re-search-forward target-regexp (+ (point) 100) t)
533 (not (looking-at "\\s-*end")))
534 (condition-case nil
535 (setq all-patterns (append (read (current-buffer)) all-patterns))
536 (error (message "Invalid pattern list expression at %d"
537 (line-number-at-pos)))))))
538 (when hi-lock-buffer-mode (hi-lock-set-file-patterns all-patterns))
539 (if (interactive-p)
540 (message "Hi-lock added %d patterns." (length all-patterns))))))
542 (defun hi-lock-font-lock-hook ()
543 "Add hi lock patterns to font-lock's."
544 (if font-lock-mode
545 (progn (font-lock-add-keywords nil hi-lock-file-patterns)
546 (font-lock-add-keywords nil hi-lock-interactive-patterns))
547 (hi-lock-buffer-mode -1)))
549 (provide 'hi-lock)
551 ;; arch-tag: d2e8fd07-4cc9-4c6f-a200-1e729bc54066
552 ;;; hi-lock.el ends here