replace.el 59.8 KB
Newer Older
1
;;; replace.el --- replace commands for Emacs
Eric S. Raymond's avatar
Eric S. Raymond committed
2

3 4
;; Copyright (C) 1985, 1986, 1987, 1992, 1994, 1996, 1997, 2000, 2001, 2002,
;;   2003, 2004  Free Software Foundation, Inc.
Eric S. Raymond's avatar
Eric S. Raymond committed
5

Pavel Janík's avatar
Pavel Janík committed
6 7
;; Maintainer: FSF

Richard M. Stallman's avatar
Richard M. Stallman committed
8 9 10 11
;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
Jim Blandy's avatar
Jim Blandy committed
12
;; the Free Software Foundation; either version 2, or (at your option)
Richard M. Stallman's avatar
Richard M. Stallman committed
13 14 15 16 17 18 19 20
;; any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
Erik Naggum's avatar
Erik Naggum committed
21 22 23
;; along with GNU Emacs; see the file COPYING.  If not, write to the
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.
Richard M. Stallman's avatar
Richard M. Stallman committed
24

25 26 27 28 29
;;; Commentary:

;; This package supplies the string and regular-expression replace functions
;; documented in the Emacs user's manual.

Eric S. Raymond's avatar
Eric S. Raymond committed
30
;;; Code:
Richard M. Stallman's avatar
Richard M. Stallman committed
31

32
(defcustom case-replace t
33
  "*Non-nil means `query-replace' should preserve case in replacements."
34 35
  :type 'boolean
  :group 'matching)
Roland McGrath's avatar
Roland McGrath committed
36

37 38
(defvar query-replace-history nil)

39
(defvar query-replace-interactive nil
40
  "Non-nil means `query-replace' uses the last search string.
41
That becomes the \"string to replace\".")
42

43
(defcustom query-replace-from-history-variable 'query-replace-history
44
  "History list to use for the FROM argument of `query-replace' commands.
45 46 47 48
The value of this variable should be a symbol; that symbol
is used as a variable to hold a history list for the strings
or patterns to be replaced."
  :group 'matching
Dan Nicolaescu's avatar
Dan Nicolaescu committed
49 50
  :type 'symbol
  :version "20.3")
51 52

(defcustom query-replace-to-history-variable 'query-replace-history
53
  "History list to use for the TO argument of `query-replace' commands.
54 55 56 57
The value of this variable should be a symbol; that symbol
is used as a variable to hold a history list for replacement
strings or patterns."
  :group 'matching
Dan Nicolaescu's avatar
Dan Nicolaescu committed
58 59
  :type 'symbol
  :version "20.3")
60

61 62 63 64
(defcustom query-replace-skip-read-only nil
  "*Non-nil means `query-replace' and friends ignore read-only matches."
  :type 'boolean
  :group 'matching
65
  :version "22.1")
66

67 68 69 70 71 72 73 74 75 76 77 78 79
(defcustom query-replace-highlight t
  "*Non-nil means to highlight matches during query replacement."
  :type 'boolean
  :group 'matching)

(defcustom query-replace-lazy-highlight t
  "*Controls the lazy-highlighting during query replacements.
When non-nil, all text in the buffer matching the current match
is highlighted lazily using isearch lazy highlighting (see
`lazy-highlight-initial-delay' and `lazy-highlight-interval')."
  :type 'boolean
  :group 'lazy-highlight
  :group 'matching
80
  :version "22.1")
81 82 83 84 85

(defface query-replace
  '((t (:inherit isearch)))
  "Face for highlighting query replacement matches."
  :group 'matching
86
  :version "22.1")
87

88 89 90
(defun query-replace-descr (string)
  (mapconcat 'isearch-text-char-description string ""))

91
(defun query-replace-read-from (string regexp-flag)
92 93 94
  "Query and return the `from' argument of a query-replace operation.
The return value can also be a pair (FROM . TO) indicating that the user
wants to replace FROM with TO."
95 96
  (if query-replace-interactive
      (car (if regexp-flag regexp-search-ring search-ring))
97 98 99
    (let* ((lastfrom (car (symbol-value query-replace-from-history-variable)))
	   (lastto (car (symbol-value query-replace-to-history-variable)))
	   (from
100 101 102 103
	    ;; The save-excursion here is in case the user marks and copies
	    ;; a region in order to specify the minibuffer input.
	    ;; That should not clobber the region for the query-replace itself.
	    (save-excursion
104 105 106 107
	      (when (equal lastfrom lastto)
		;; Typically, this is because the two histlists are shared.
		(setq lastfrom (cadr (symbol-value
				      query-replace-from-history-variable))))
108
	      (read-from-minibuffer
109 110 111 112 113
	       (if (and lastto lastfrom)
		   (format "%s (default %s -> %s): " string
			   (query-replace-descr lastfrom)
			   (query-replace-descr lastto))
		 (format "%s: " string))
114 115
	       nil nil nil
	       query-replace-from-history-variable
116
	       nil t t))))
117
      (if (and (zerop (length from)) lastto lastfrom)
118 119 120 121 122
	  (progn
	    (cons lastfrom
		  (query-replace-compile-replacement lastto regexp-flag))
	    (set query-replace-from-history-variable
		 (cdr (symbol-value query-replace-from-history-variable))))
123 124 125 126 127 128 129 130 131 132 133
	;; Warn if user types \n or \t, but don't reject the input.
	(and regexp-flag
	     (string-match "\\(\\`\\|[^\\]\\)\\(\\\\\\\\\\)*\\(\\\\[nt]\\)" from)
	     (let ((match (match-string 3 from)))
	       (cond
		((string= match "\\n")
		 (message "Note: `\\n' here doesn't match a newline; to do that, type C-q C-j instead"))
		((string= match "\\t")
		 (message "Note: `\\t' here doesn't match a tab; to do that, just type TAB")))
	       (sit-for 2)))
	from))))
134

David Kastrup's avatar
David Kastrup committed
135 136 137 138 139 140
(defun query-replace-compile-replacement (to regexp-flag)
  "Maybe convert a regexp replacement TO to Lisp.
Returns a list suitable for `perform-replace' if necessary,
the original string if not."
  (if (and regexp-flag
	   (string-match "\\(\\`\\|[^\\]\\)\\(\\\\\\\\\\)*\\\\[,#]" to))
141 142 143 144 145 146 147 148 149 150 151 152
      (let (pos list char)
	(while
	    (progn
	      (setq pos (match-end 0))
	      (push (substring to 0 (- pos 2)) list)
	      (setq char (aref to (1- pos))
		    to (substring to pos))
	      (cond ((eq char ?\#)
		     (push '(number-to-string replace-count) list))
		    ((eq char ?\,)
		     (setq pos (read-from-string to))
		     (push `(replace-quote ,(car pos)) list)
153 154 155 156 157 158 159
		     (let ((end
			    ;; Swallow a space after a symbol
			    ;; if there is a space.
			    (if (and (or (symbolp (car pos))
					 ;; Swallow a space after 'foo
					 ;; but not after (quote foo).
					 (and (eq (car-safe (car pos)) 'quote)
160 161 162
					      (not (= ?\( (aref to 0)))))
				     (eq (string-match " " to (cdr pos))
					 (cdr pos)))
163 164 165
				(1+ (cdr pos))
			      (cdr pos))))
		       (setq to (substring to end)))))
166
	      (string-match "\\(\\`\\|[^\\]\\)\\(\\\\\\\\\\)*\\\\[,#]" to)))
David Kastrup's avatar
David Kastrup committed
167 168 169 170 171 172
	(setq to (nreverse (delete "" (cons to list))))
	(replace-match-string-symbols to)
	(cons 'replace-eval-replacement
	      (if (cdr to)
		  (cons 'concat to)
		(car to))))
173 174
    to))

David Kastrup's avatar
David Kastrup committed
175 176 177 178 179 180 181 182

(defun query-replace-read-to (from string regexp-flag)
  "Query and return the `to' argument of a query-replace operation."
  (query-replace-compile-replacement
   (save-excursion
     (read-from-minibuffer
      (format "%s %s with: " string (query-replace-descr from))
      nil nil nil
183
      query-replace-to-history-variable from t t))
David Kastrup's avatar
David Kastrup committed
184 185
   regexp-flag))

186 187 188 189
(defun query-replace-read-args (string regexp-flag &optional noerror)
  (unless noerror
    (barf-if-buffer-read-only))
  (let* ((from (query-replace-read-from string regexp-flag))
190 191
	 (to (if (consp from) (prog1 (cdr from) (setq from (car from)))
	       (query-replace-read-to from string regexp-flag))))
192
    (list from to current-prefix-arg)))
193

194
(defun query-replace (from-string to-string &optional delimited start end)
Roland McGrath's avatar
Roland McGrath committed
195 196 197 198
  "Replace some occurrences of FROM-STRING with TO-STRING.
As each match is found, the user must type a character saying
what to do with it.  For directions, type \\[help-command] at that time.

199 200 201
In Transient Mark mode, if the mark is active, operate on the contents
of the region.  Otherwise, operate from point to the end of the buffer.

202 203 204 205
If `query-replace-interactive' is non-nil, the last incremental search
string is used as FROM-STRING--you don't have to specify it with the
minibuffer.

206 207 208 209 210 211 212
Matching is independent of case if `case-fold-search' is non-nil and
FROM-STRING has no uppercase letters.  Replacement transfers the case
pattern of the old text to the new text, if `case-replace' and
`case-fold-search' are non-nil and FROM-STRING has no uppercase
letters.  \(Transferring the case pattern means that if the old text
matched is all caps, or capitalized, then its replacement is upcased
or capitalized.)
213

Richard M. Stallman's avatar
Richard M. Stallman committed
214
Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace
215
only matches surrounded by word boundaries.
216
Fourth and fifth arg START and END specify the region to operate on.
217 218

To customize possible responses, change the \"bindings\" in `query-replace-map'."
219 220 221 222 223 224 225 226 227 228
  (interactive (let ((common
		      (query-replace-read-args "Query replace" nil)))
		 (list (nth 0 common) (nth 1 common) (nth 2 common)
		       ;; These are done separately here
		       ;; so that command-history will record these expressions
		       ;; rather than the values they had this time.
		       (if (and transient-mark-mode mark-active)
			   (region-beginning))
		       (if (and transient-mark-mode mark-active)
			   (region-end)))))
229
  (perform-replace from-string to-string t nil delimited nil nil start end))
230

Brian Preble's avatar
Brian Preble committed
231
(define-key esc-map "%" 'query-replace)
Roland McGrath's avatar
Roland McGrath committed
232

233
(defun query-replace-regexp (regexp to-string &optional delimited start end)
Roland McGrath's avatar
Roland McGrath committed
234 235 236 237
  "Replace some things after point matching REGEXP with TO-STRING.
As each match is found, the user must type a character saying
what to do with it.  For directions, type \\[help-command] at that time.

238 239 240
In Transient Mark mode, if the mark is active, operate on the contents
of the region.  Otherwise, operate from point to the end of the buffer.

241 242 243 244
If `query-replace-interactive' is non-nil, the last incremental search
regexp is used as REGEXP--you don't have to specify it with the
minibuffer.

245 246 247 248 249 250 251
Matching is independent of case if `case-fold-search' is non-nil and
REGEXP has no uppercase letters.  Replacement transfers the case
pattern of the old text to the new text, if `case-replace' and
`case-fold-search' are non-nil and REGEXP has no uppercase letters.
\(Transferring the case pattern means that if the old text matched is
all caps, or capitalized, then its replacement is upcased or
capitalized.)
252

Richard M. Stallman's avatar
Richard M. Stallman committed
253
Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace
Roland McGrath's avatar
Roland McGrath committed
254
only matches surrounded by word boundaries.
255 256
Fourth and fifth arg START and END specify the region to operate on.

Richard M. Stallman's avatar
Richard M. Stallman committed
257 258
In TO-STRING, `\\&' stands for whatever matched the whole of REGEXP,
and `\\=\\N' (where N is a digit) stands for
259
whatever what matched the Nth `\\(...\\)' in REGEXP.
260 261 262
`\\?' lets you edit the replacement text in the minibuffer
at the given position for each replacement.

263 264 265 266
In interactive calls, the replacement text can contain `\\,'
followed by a Lisp expression.  Each
replacement evaluates that expression to compute the replacement
string.  Inside of that expression, `\\&' is a string denoting the
267
whole match as a string, `\\N' for a partial match, `\\#&' and `\\#N'
268 269 270
for the whole or a partial match converted to a number with
`string-to-number', and `\\#' itself for the number of replacements
done so far (starting with zero).
271

272 273
If the replacement expression is a symbol, write a space after it
to terminate it.  One space there, if any, will be discarded.
274 275 276 277

When using those Lisp features interactively in the replacement
text, TO-STRING is actually made a list instead of a string.
Use \\[repeat-complex-command] after this command for details."
278 279 280
  (interactive
   (let ((common
	  (query-replace-read-args "Query replace regexp" t)))
281 282 283 284 285 286 287 288
     (list (nth 0 common) (nth 1 common) (nth 2 common)
	   ;; These are done separately here
	   ;; so that command-history will record these expressions
	   ;; rather than the values they had this time.
	   (if (and transient-mark-mode mark-active)
	       (region-beginning))
	   (if (and transient-mark-mode mark-active)
	       (region-end)))))
289
  (perform-replace regexp to-string t t delimited nil nil start end))
290

291
(define-key esc-map [?\C-%] 'query-replace-regexp)
Roland McGrath's avatar
Roland McGrath committed
292

293
(defun query-replace-regexp-eval (regexp to-expr &optional delimited start end)
294 295 296 297 298 299 300 301 302 303
  "Replace some things after point matching REGEXP with the result of TO-EXPR.
As each match is found, the user must type a character saying
what to do with it.  For directions, type \\[help-command] at that time.

TO-EXPR is a Lisp expression evaluated to compute each replacement.  It may
reference `replace-count' to get the number of replacements already made.
If the result of TO-EXPR is not a string, it is converted to one using
`prin1-to-string' with the NOESCAPE argument (which see).

For convenience, when entering TO-EXPR interactively, you can use `\\&' or
304 305
`\\0' to stand for whatever matched the whole of REGEXP, and `\\N' (where
N is a digit) to stand for whatever matched the Nth `\\(...\\)' in REGEXP.
306
Use `\\#&' or `\\#N' if you want a number instead of a string.
307
In interactive use, `\\#' in itself stands for `replace-count'.
308 309 310 311 312 313 314 315 316 317

In Transient Mark mode, if the mark is active, operate on the contents
of the region.  Otherwise, operate from point to the end of the buffer.

If `query-replace-interactive' is non-nil, the last incremental search
regexp is used as REGEXP--you don't have to specify it with the
minibuffer.

Preserves case in each replacement if `case-replace' and `case-fold-search'
are non-nil and REGEXP has no uppercase letters.
318

319
Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace
320
only matches that are surrounded by word boundaries.
321
Fourth and fifth arg START and END specify the region to operate on."
322
  (interactive
323
   (progn
324 325 326 327 328 329 330
   (barf-if-buffer-read-only)
   (let* ((from
	   ;; Let-bind the history var to disable the "foo -> bar" default.
	   ;; Maybe we shouldn't disable this default, but for now I'll
	   ;; leave it off.  --Stef
	   (let ((query-replace-to-history-variable nil))
	     (query-replace-read-from "Query replace regexp" t)))
331
	  (to (list (read-from-minibuffer
332 333
		     (format "Query replace regexp %s with eval: "
			     (query-replace-descr from))
334
		     nil nil t query-replace-to-history-variable from t))))
335 336 337
     ;; We make TO a list because replace-match-string-symbols requires one,
     ;; and the user might enter a single token.
     (replace-match-string-symbols to)
338 339 340 341
     (list from (car to) current-prefix-arg
	   (if (and transient-mark-mode mark-active)
	       (region-beginning))
	   (if (and transient-mark-mode mark-active)
342
	       (region-end))))))
343
  (perform-replace regexp (cons 'replace-eval-replacement to-expr)
344
		   t 'literal delimited nil nil start end))
345

346
(defun map-query-replace-regexp (regexp to-strings &optional n start end)
Roland McGrath's avatar
Roland McGrath committed
347
  "Replace some matches for REGEXP with various strings, in rotation.
Dave Love's avatar
Dave Love committed
348 349 350 351 352
The second argument TO-STRINGS contains the replacement strings,
separated by spaces.  Third arg DELIMITED (prefix arg if interactive),
if non-nil, means replace only matches surrounded by word boundaries.
This command works like `query-replace-regexp' except that each
successive replacement uses the next successive replacement string,
Roland McGrath's avatar
Roland McGrath committed
353 354
wrapping around from the last such string to the first.

355 356 357
In Transient Mark mode, if the mark is active, operate on the contents
of the region.  Otherwise, operate from point to the end of the buffer.

Roland McGrath's avatar
Roland McGrath committed
358 359
Non-interactively, TO-STRINGS may be a list of replacement strings.

360 361 362
If `query-replace-interactive' is non-nil, the last incremental search
regexp is used as REGEXP--you don't have to specify it with the minibuffer.

Roland McGrath's avatar
Roland McGrath committed
363
A prefix argument N says to use each replacement string N times
364 365
before rotating to the next.
Fourth and fifth arg START and END specify the region to operate on."
366
  (interactive
367
   (let* ((from (if query-replace-interactive
368 369 370
		    (car regexp-search-ring)
		  (read-from-minibuffer "Map query replace (regexp): "
					nil nil nil
371
					'query-replace-history nil t)))
372
	  (to (read-from-minibuffer
373
	       (format "Query replace %s with (space-separated strings): "
374
		       (query-replace-descr from))
375
	       nil nil nil
376
	       'query-replace-history from t)))
377 378 379
     (list from to
	   (and current-prefix-arg
		(prefix-numeric-value current-prefix-arg))
380 381 382 383
	   (if (and transient-mark-mode mark-active)
	       (region-beginning))
	   (if (and transient-mark-mode mark-active)
	       (region-end)))))
Roland McGrath's avatar
Roland McGrath committed
384 385 386 387 388 389 390 391 392 393 394 395 396
  (let (replacements)
    (if (listp to-strings)
	(setq replacements to-strings)
      (while (/= (length to-strings) 0)
	(if (string-match " " to-strings)
	    (setq replacements
		  (append replacements
			  (list (substring to-strings 0
					   (string-match " " to-strings))))
		  to-strings (substring to-strings
				       (1+ (string-match " " to-strings))))
	  (setq replacements (append replacements (list to-strings))
		to-strings ""))))
397
    (perform-replace regexp replacements t t nil n nil start end)))
Roland McGrath's avatar
Roland McGrath committed
398

399
(defun replace-string (from-string to-string &optional delimited start end)
Roland McGrath's avatar
Roland McGrath committed
400 401 402
  "Replace occurrences of FROM-STRING with TO-STRING.
Preserve case in each match if `case-replace' and `case-fold-search'
are non-nil and FROM-STRING has no uppercase letters.
403 404 405
\(Preserving case means that if the string matched is all caps, or capitalized,
then its replacement is upcased or capitalized.)

406 407 408
In Transient Mark mode, if the mark is active, operate on the contents
of the region.  Otherwise, operate from point to the end of the buffer.

Richard M. Stallman's avatar
Richard M. Stallman committed
409
Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace
Roland McGrath's avatar
Roland McGrath committed
410
only matches surrounded by word boundaries.
411
Fourth and fifth arg START and END specify the region to operate on.
Roland McGrath's avatar
Roland McGrath committed
412

413 414 415 416
If `query-replace-interactive' is non-nil, the last incremental search
string is used as FROM-STRING--you don't have to specify it with the
minibuffer.

Roland McGrath's avatar
Roland McGrath committed
417 418
This function is usually the wrong thing to use in a Lisp program.
What you probably want is a loop like this:
Richard M. Stallman's avatar
Richard M. Stallman committed
419 420
  (while (search-forward FROM-STRING nil t)
    (replace-match TO-STRING nil t))
421 422 423
which will run faster and will not set the mark or print anything.
\(You may need a more complex loop if FROM-STRING can match the null string
and TO-STRING is also null.)"
424 425 426 427 428 429 430 431
  (interactive
   (let ((common
	  (query-replace-read-args "Replace string" nil)))
     (list (nth 0 common) (nth 1 common) (nth 2 common)
	   (if (and transient-mark-mode mark-active)
	       (region-beginning))
	   (if (and transient-mark-mode mark-active)
	       (region-end)))))
432
  (perform-replace from-string to-string nil nil delimited nil nil start end))
Roland McGrath's avatar
Roland McGrath committed
433

434
(defun replace-regexp (regexp to-string &optional delimited start end)
Roland McGrath's avatar
Roland McGrath committed
435
  "Replace things after point matching REGEXP with TO-STRING.
Richard M. Stallman's avatar
Richard M. Stallman committed
436
Preserve case in each match if `case-replace' and `case-fold-search'
Roland McGrath's avatar
Roland McGrath committed
437
are non-nil and REGEXP has no uppercase letters.
438 439 440 441

In Transient Mark mode, if the mark is active, operate on the contents
of the region.  Otherwise, operate from point to the end of the buffer.

Richard M. Stallman's avatar
Richard M. Stallman committed
442
Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace
Roland McGrath's avatar
Roland McGrath committed
443
only matches surrounded by word boundaries.
444 445
Fourth and fifth arg START and END specify the region to operate on.

Richard M. Stallman's avatar
Richard M. Stallman committed
446 447
In TO-STRING, `\\&' stands for whatever matched the whole of REGEXP,
and `\\=\\N' (where N is a digit) stands for
448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468
whatever what matched the Nth `\\(...\\)' in REGEXP.
`\\?' lets you edit the replacement text in the minibuffer
at the given position for each replacement.

In interactive calls, the replacement text may contain `\\,'
followed by a Lisp expression used as part of the replacement
text.  Inside of that expression, `\\&' is a string denoting the
whole match, `\\N' a partial matches, `\\#&' and `\\#N' the
respective numeric values from `string-to-number', and `\\#'
itself for `replace-count', the number of replacements occured so
far.

If your Lisp expression is an identifier and the next letter in
the replacement string would be interpreted as part of it, you
can wrap it with an expression like `\\,(or \\#)'.  Incidentally,
for this particular case you may also enter `\\#' in the
replacement text directly.

When using those Lisp features interactively in the replacement
text, TO-STRING is actually made a list instead of a string.
Use \\[repeat-complex-command] after this command for details.
Roland McGrath's avatar
Roland McGrath committed
469

470 471 472
If `query-replace-interactive' is non-nil, the last incremental search
regexp is used as REGEXP--you don't have to specify it with the minibuffer.

Roland McGrath's avatar
Roland McGrath committed
473 474 475
This function is usually the wrong thing to use in a Lisp program.
What you probably want is a loop like this:
  (while (re-search-forward REGEXP nil t)
Richard M. Stallman's avatar
Richard M. Stallman committed
476
    (replace-match TO-STRING nil nil))
Roland McGrath's avatar
Roland McGrath committed
477
which will run faster and will not set the mark or print anything."
478 479 480 481 482 483 484 485
  (interactive
   (let ((common
	  (query-replace-read-args "Replace regexp" t)))
     (list (nth 0 common) (nth 1 common) (nth 2 common)
	   (if (and transient-mark-mode mark-active)
	       (region-beginning))
	   (if (and transient-mark-mode mark-active)
	       (region-end)))))
486
  (perform-replace regexp to-string nil t delimited nil nil start end))
487

488 489 490

(defvar regexp-history nil
  "History list for some commands that read regular expressions.")
Roland McGrath's avatar
Roland McGrath committed
491

492

493
(defalias 'delete-non-matching-lines 'keep-lines)
494 495 496 497 498 499 500
(defalias 'delete-matching-lines 'flush-lines)
(defalias 'count-matches 'how-many)


(defun keep-lines-read-args (prompt)
  "Read arguments for `keep-lines' and friends.
Prompt for a regexp with PROMPT.
501 502 503
Value is a list, (REGEXP)."
  (list (read-from-minibuffer prompt nil nil nil
			      'regexp-history nil t)))
504 505

(defun keep-lines (regexp &optional rstart rend)
Richard M. Stallman's avatar
Richard M. Stallman committed
506 507
  "Delete all lines except those containing matches for REGEXP.
A match split across lines preserves all the lines it lies in.
508 509 510
Applies to all lines after point.

If REGEXP contains upper case characters (excluding those preceded by `\\'),
511 512 513 514
the matching is case-sensitive.

Second and third arg RSTART and REND specify the region to operate on.

515 516 517 518
Interactively, in Transient Mark mode when the mark is active, operate
on the contents of the region.  Otherwise, operate from point to the
end of the buffer."

519
  (interactive
520 521 522
   (progn
     (barf-if-buffer-read-only)
     (keep-lines-read-args "Keep lines (containing match for regexp): ")))
523
  (if rstart
524 525 526
      (progn
	(goto-char (min rstart rend))
	(setq rend (copy-marker (max rstart rend))))
527 528 529 530 531 532
    (if (and transient-mark-mode mark-active)
	(setq rstart (region-beginning)
	      rend (copy-marker (region-end)))
      (setq rstart (point)
	    rend (point-max-marker)))
    (goto-char rstart))
Richard M. Stallman's avatar
Richard M. Stallman committed
533 534
  (save-excursion
    (or (bolp) (forward-line 1))
535 536 537
    (let ((start (point))
	  (case-fold-search  (and case-fold-search
				  (isearch-no-upper-case-p regexp t))))
538
      (while (< (point) rend)
Richard M. Stallman's avatar
Richard M. Stallman committed
539
	;; Start is first char not preserved by previous match.
540 541
	(if (not (re-search-forward regexp rend 'move))
	    (delete-region start rend)
Richard M. Stallman's avatar
Richard M. Stallman committed
542 543 544 545 546 547
	  (let ((end (save-excursion (goto-char (match-beginning 0))
				     (beginning-of-line)
				     (point))))
	    ;; Now end is first char preserved by the new match.
	    (if (< start end)
		(delete-region start end))))
548

549
	(setq start (save-excursion (forward-line 1) (point)))
Richard M. Stallman's avatar
Richard M. Stallman committed
550
	;; If the match was empty, avoid matching again at same place.
551 552
	(and (< (point) rend)
	     (= (match-beginning 0) (match-end 0))
Richard M. Stallman's avatar
Richard M. Stallman committed
553 554
	     (forward-char 1))))))

555 556

(defun flush-lines (regexp &optional rstart rend)
Richard M. Stallman's avatar
Richard M. Stallman committed
557 558
  "Delete lines containing matches for REGEXP.
If a match is split across lines, all the lines it lies in are deleted.
559 560 561
Applies to lines after point.

If REGEXP contains upper case characters (excluding those preceded by `\\'),
562 563 564 565
the matching is case-sensitive.

Second and third arg RSTART and REND specify the region to operate on.

566 567 568 569
Interactively, in Transient Mark mode when the mark is active, operate
on the contents of the region.  Otherwise, operate from point to the
end of the buffer."

570
  (interactive
571 572 573
   (progn
     (barf-if-buffer-read-only)
     (keep-lines-read-args "Flush lines (containing match for regexp): ")))
574
  (if rstart
575 576 577
      (progn
	(goto-char (min rstart rend))
	(setq rend (copy-marker (max rstart rend))))
578 579 580 581 582 583
    (if (and transient-mark-mode mark-active)
	(setq rstart (region-beginning)
	      rend (copy-marker (region-end)))
      (setq rstart (point)
	    rend (point-max-marker)))
    (goto-char rstart))
584 585 586
  (let ((case-fold-search (and case-fold-search
			       (isearch-no-upper-case-p regexp t))))
    (save-excursion
587 588
      (while (and (< (point) rend)
		  (re-search-forward regexp rend t))
589 590 591 592
	(delete-region (save-excursion (goto-char (match-beginning 0))
				       (beginning-of-line)
				       (point))
		       (progn (forward-line 1) (point)))))))
Richard M. Stallman's avatar
Richard M. Stallman committed
593

594 595

(defun how-many (regexp &optional rstart rend)
596 597 598
  "Print number of matches for REGEXP following point.

If REGEXP contains upper case characters (excluding those preceded by `\\'),
599 600 601 602
the matching is case-sensitive.

Second and third arg RSTART and REND specify the region to operate on.

603 604 605 606
Interactively, in Transient Mark mode when the mark is active, operate
on the contents of the region.  Otherwise, operate from point to the
end of the buffer."

607 608
  (interactive
   (keep-lines-read-args "How many matches for (regexp): "))
609 610 611
  (save-excursion
    (if rstart
	(goto-char (min rstart rend))
612 613 614 615 616 617
      (if (and transient-mark-mode mark-active)
	  (setq rstart (region-beginning)
		rend (copy-marker (region-end)))
	(setq rstart (point)
	      rend (point-max-marker)))
      (goto-char rstart))
618 619 620 621 622 623 624 625 626 627 628
    (let ((count 0)
	  opoint
	  (case-fold-search (and case-fold-search
				 (isearch-no-upper-case-p regexp t))))
      (while (and (< (point) rend)
		  (progn (setq opoint (point))
			 (re-search-forward regexp rend t)))
	(if (= opoint (point))
	    (forward-char 1)
	  (setq count (1+ count))))
      (message "%d occurrences" count))))
629

630

631 632 633 634 635
(defvar occur-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map [mouse-2] 'occur-mode-mouse-goto)
    (define-key map "\C-c\C-c" 'occur-mode-goto-occurrence)
    (define-key map "\C-m" 'occur-mode-goto-occurrence)
636
    (define-key map "o" 'occur-mode-goto-occurrence-other-window)
637
    (define-key map "\C-o" 'occur-mode-display-occurrence)
638 639
    (define-key map "\M-n" 'occur-next)
    (define-key map "\M-p" 'occur-prev)
640 641
    (define-key map "r" 'occur-rename-buffer)
    (define-key map "c" 'clone-buffer)
642
    (define-key map "g" 'revert-buffer)
643 644
    (define-key map "q" 'quit-window)
    (define-key map "z" 'kill-this-buffer)
645
    (define-key map "\C-c\C-f" 'next-error-follow-minor-mode)
646 647
    map)
  "Keymap for `occur-mode'.")
Richard M. Stallman's avatar
Richard M. Stallman committed
648

649 650 651
(defvar occur-revert-arguments nil
  "Arguments to pass to `occur-1' to revert an Occur mode buffer.
See `occur-revert-function'.")
Richard M. Stallman's avatar
Richard M. Stallman committed
652

653 654 655 656 657 658 659
(defcustom occur-mode-hook '(turn-on-font-lock)
  "Hook run when entering Occur mode."
  :type 'hook
  :group 'matching)

(defcustom occur-hook nil
  "Hook run when `occur' is called."
660 661 662
  :type 'hook
  :group 'matching)

663
(put 'occur-mode 'mode-class 'special)
664
(defun occur-mode ()
Richard M. Stallman's avatar
Richard M. Stallman committed
665
  "Major mode for output from \\[occur].
666 667 668 669
\\<occur-mode-map>Move point to one of the items in this buffer, then use
\\[occur-mode-goto-occurrence] to go to the occurrence that the item refers to.
Alternatively, click \\[occur-mode-mouse-goto] on an item to go to it.

Richard M. Stallman's avatar
Richard M. Stallman committed
670
\\{occur-mode-map}"
671
  (interactive)
672 673 674 675
  (kill-all-local-variables)
  (use-local-map occur-mode-map)
  (setq major-mode 'occur-mode)
  (setq mode-name "Occur")
676
  (set (make-local-variable 'revert-buffer-function) 'occur-revert-function)
677
  (make-local-variable 'occur-revert-arguments)
678
  (add-hook 'change-major-mode-hook 'font-lock-defontify nil t)
679
  (setq next-error-function 'occur-next-error)
680
  (run-hooks 'occur-mode-hook))
Richard M. Stallman's avatar
Richard M. Stallman committed
681

682
(defun occur-revert-function (ignore1 ignore2)
683
  "Handle `revert-buffer' for Occur mode buffers."
684
  (apply 'occur-1 (append occur-revert-arguments (list (buffer-name)))))
685

686 687 688
(defun occur-mode-mouse-goto (event)
  "In Occur mode, go to the occurrence whose line you click on."
  (interactive "e")
689
  (let (pos)
690 691 692 693
    (save-excursion
      (set-buffer (window-buffer (posn-window (event-end event))))
      (save-excursion
	(goto-char (posn-point (event-end event)))
694 695 696
	(setq pos (occur-mode-find-occurrence))))
    (pop-to-buffer (marker-buffer pos))
    (goto-char pos)))
697 698

(defun occur-mode-find-occurrence ()
699 700
  (let ((pos (get-text-property (point) 'occur-target)))
    (unless pos
701
      (error "No occurrence on this line"))
702 703 704
    (unless (buffer-live-p (marker-buffer pos))
      (error "Buffer for this occurrence was killed"))
    pos))
705 706 707 708

(defun occur-mode-goto-occurrence ()
  "Go to the occurrence the current line describes."
  (interactive)
709 710 711
  (let ((pos (occur-mode-find-occurrence)))
    (pop-to-buffer (marker-buffer pos))
    (goto-char pos)))
712

713 714 715
(defun occur-mode-goto-occurrence-other-window ()
  "Go to the occurrence the current line describes, in another window."
  (interactive)
716 717 718
  (let ((pos (occur-mode-find-occurrence)))
    (switch-to-buffer-other-window (marker-buffer pos))
    (goto-char pos)))
719

720 721 722
(defun occur-mode-display-occurrence ()
  "Display in another window the occurrence the current line describes."
  (interactive)
723 724 725
  (let ((pos (occur-mode-find-occurrence))
	window
	;; Bind these to ensure `display-buffer' puts it in another window.
726
	same-window-buffer-names
727 728
	same-window-regexps)
    (setq window (display-buffer (marker-buffer pos)))
729 730 731
    ;; This is the way to set point in the proper window.
    (save-selected-window
      (select-window window)
732
      (goto-char pos))))
733

734
(defun occur-find-match (n search message)
735 736 737
  (if (not n) (setq n 1))
  (let ((r))
    (while (> n 0)
738 739 740 741
      (setq r (funcall search (point) 'occur-match))
      (and r
           (get-text-property r 'occur-match)
           (setq r (funcall search r 'occur-match)))
742
      (if r
743 744
          (goto-char r)
        (error message))
745 746
      (setq n (1- n)))))

747 748 749 750 751
(defun occur-next (&optional n)
  "Move to the Nth (default 1) next match in an Occur mode buffer."
  (interactive "p")
  (occur-find-match n #'next-single-property-change "No more matches"))

752
(defun occur-prev (&optional n)
753
  "Move to the Nth (default 1) previous match in an Occur mode buffer."
754
  (interactive "p")
755
  (occur-find-match n #'previous-single-property-change "No earlier matches"))
756 757 758 759 760

(defun occur-next-error (&optional argp reset)
  "Move to the Nth (default 1) next match in an Occur mode buffer.
Compatibility function for \\[next-error] invocations."
  (interactive "p")
761
  ;; we need to run occur-find-match from within the Occur buffer
762
  (with-current-buffer
763
      ;; Choose the buffer and make it current.
764 765
      (if (next-error-buffer-p (current-buffer))
	  (current-buffer)
766 767 768
	(next-error-find-buffer nil nil
				(lambda ()
				  (eq major-mode 'occur-mode))))
769 770 771 772

    (goto-char (cond (reset (point-min))
		     ((< argp 0) (line-beginning-position))
		     ((line-end-position))))
773
    (occur-find-match
774 775
     (abs argp)
     (if (> 0 argp)
776 777 778 779 780 781
	 #'previous-single-property-change
       #'next-single-property-change)
     "No more matches")
    ;; In case the *Occur* buffer is visible in a nonselected window.
    (set-window-point (get-buffer-window (current-buffer)) (point))
    (occur-mode-goto-occurrence)))
782

Juri Linkov's avatar
Juri Linkov committed
783 784 785 786 787 788 789 790 791 792 793 794
(defface match
  '((((class color) (min-colors 88) (background light))
     :background "Tan")
    (((class color) (min-colors 88) (background dark))
     :background "RoyalBlue4")
    (((class color) (min-colors 8))
     :background "blue" :foreground "white")
    (((type tty) (class mono))
     :inverse-video t)
    (t :background "gray"))
  "Face used to highlight matches permanently."
  :group 'matching
795
  :version "22.1")
Juri Linkov's avatar
Juri Linkov committed
796

797
(defcustom list-matching-lines-default-context-lines 0
Dave Love's avatar
Dave Love committed
798 799
  "*Default number of context lines included around `list-matching-lines' matches.
A negative number means to include that many lines before the match.
800 801 802
A positive number means to include that many lines both before and after."
  :type 'integer
  :group 'matching)
Richard M. Stallman's avatar
Richard M. Stallman committed
803

804
(defalias 'list-matching-lines 'occur)
Richard M. Stallman's avatar
Richard M. Stallman committed
805

Juri Linkov's avatar
Juri Linkov committed
806
(defcustom list-matching-lines-face 'match
Dave Love's avatar
Dave Love committed
807
  "*Face used by \\[list-matching-lines] to show the text that matches.
808 809 810 811 812 813 814 815 816 817
If the value is nil, don't highlight the matching portions specially."
  :type 'face
  :group 'matching)

(defcustom list-matching-lines-buffer-name-face 'underline
  "*Face used by \\[list-matching-lines] to show the names of buffers.
If the value is nil, don't highlight the buffer names specially."
  :type 'face
  :group 'matching)

818
(defun occur-accumulate-lines (count &optional keep-props)
819 820
  (save-excursion
    (let ((forwardp (> count 0))
821
	  result beg end)
822 823 824 825
      (while (not (or (zerop count)
		      (if forwardp
			  (eobp)
			(bobp))))
826
	(setq count (+ count (if forwardp -1 1)))
827 828
	(setq beg (line-beginning-position)
	      end (line-end-position))
829
	(if (and keep-props (if (boundp 'jit-lock-mode) jit-lock-mode)
830
		 (text-property-not-all beg end 'fontified t))
831 832
	    (if (fboundp 'jit-lock-fontify-now)
		(jit-lock-fontify-now beg end)))
833
	(push
834 835 836
	 (funcall (if keep-props
		      #'buffer-substring
		    #'buffer-substring-no-properties)
837
		  beg end)
838 839 840 841 842 843 844 845 846 847
	 result)
	(forward-line (if forwardp 1 -1)))
      (nreverse result))))

(defun occur-read-primary-args ()
  (list (let* ((default (car regexp-history))
	       (input
		(read-from-minibuffer
		 (if default
		     (format "List lines matching regexp (default `%s'): "
848
			     (query-replace-descr default))
849 850 851 852
		   "List lines matching regexp: ")
		 nil
		 nil
		 nil
853 854
		 'regexp-history
		 default)))
855 856 857
	  (if (equal input "")
	      default
	    input))
858 859
	(when current-prefix-arg
	  (prefix-numeric-value current-prefix-arg))))
860

861 862 863 864 865
(defun occur-rename-buffer (&optional unique-p)
  "Rename the current *Occur* buffer to *Occur: original-buffer-name*.
Here `original-buffer-name' is the buffer name were occur was originally run.
When given the prefix argument, the renaming will not clobber the existing
buffer(s) of that name, but use `generate-new-buffer-name' instead.
866
You can add this to `occur-hook' if you always want a separate *Occur*
867 868 869 870 871 872 873 874 875 876
buffer for each buffer where you invoke `occur'."
  (interactive "P")
  (with-current-buffer
      (if (eq major-mode 'occur-mode) (current-buffer) (get-buffer "*Occur*"))
    (rename-buffer (concat "*Occur: "
                           (mapconcat #'buffer-name
                                      (car (cddr occur-revert-arguments)) "/")
                           "*")
                   unique-p)))

Richard M. Stallman's avatar
Richard M. Stallman committed
877
(defun occur (regexp &optional nlines)
878
  "Show all lines in the current buffer containing a match for REGEXP.
Roland McGrath's avatar
Roland McGrath committed
879 880

If a match spreads across multiple lines, all those lines are shown.
Richard M. Stallman's avatar
Richard M. Stallman committed
881

Roland McGrath's avatar
Roland McGrath committed
882 883 884
Each line is displayed with NLINES lines before and after, or -NLINES
before if NLINES is negative.
NLINES defaults to `list-matching-lines-default-context-lines'.
Richard M. Stallman's avatar
Richard M. Stallman committed
885 886
Interactively it is the prefix arg.

887
The lines are shown in a buffer named `*Occur*'.
Richard M. Stallman's avatar
Richard M. Stallman committed
888
It serves as a menu to find any of the occurrences in this buffer.
889
\\<occur-mode-map>\\[describe-mode] in that buffer will explain how.
890

891 892
If REGEXP contains upper case characters (excluding those preceded by `\\'),
the matching is case-sensitive."
893 894 895 896 897 898 899
  (interactive (occur-read-primary-args))
  (occur-1 regexp nlines (list (current-buffer))))

(defun multi-occur (bufs regexp &optional nlines)
  "Show all lines in buffers BUFS containing a match for REGEXP.
This function acts on multiple buffers; otherwise, it is exactly like
`occur'."
900
  (interactive
901
   (cons
902 903 904 905
    (let* ((bufs (list (read-buffer "First buffer to search: "
				    (current-buffer) t)))
	   (buf nil)
	   (ido-ignore-item-temp-list bufs))
906
      (while (not (string-equal
907
		   (setq buf (read-buffer
908 909 910 911
			      (if (eq read-buffer-function 'ido-read-buffer)
				  "Next buffer to search (C-j to end): "
				"Next buffer to search (RET to end): ")
			      nil t))
912
		   ""))
913 914
	(add-to-list 'bufs buf)
	(setq ido-ignore-item-temp-list bufs))
915 916 917 918 919
      (nreverse (mapcar #'get-buffer bufs)))
    (occur-read-primary-args)))
  (occur-1 regexp nlines bufs))

(defun multi-occur-by-filename-regexp (bufregexp regexp &optional nlines)
920
  "Show all lines matching REGEXP in buffers named by BUFREGEXP.
921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945
See also `multi-occur'."
  (interactive
   (cons
    (let* ((default (car regexp-history))
	   (input
	    (read-from-minibuffer
	     "List lines in buffers whose filename matches regexp: "
	     nil
	     nil
	     nil
	     'regexp-history)))
      (if (equal input "")
	  default
	input))
    (occur-read-primary-args)))
  (when bufregexp
    (occur-1 regexp nlines
	     (delq nil
		   (mapcar (lambda (buf)
			     (when (and (buffer-file-name buf)
					(string-match bufregexp
						      (buffer-file-name buf)))
			       buf))
			   (buffer-list))))))

946 947 948
(defun occur-1 (regexp nlines bufs &optional buf-name)
  (unless buf-name
    (setq buf-name "*Occur*"))
949
  (let (occur-buf
950 951 952 953
	(active-bufs (delq nil (mapcar #'(lambda (buf)
					   (when (buffer-live-p buf) buf))
				       bufs))))
    ;; Handle the case where one of the buffers we're searching is the
954 955 956 957 958 959 960