1 This is ../info/xemacs.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * XEmacs: (xemacs). XEmacs Editor.
9 This file documents the XEmacs editor.
11 Copyright (C) 1985, 1986, 1988 Richard M. Stallman. Copyright (C)
12 1991, 1992, 1993, 1994 Lucid, Inc. Copyright (C) 1993, 1994 Sun
13 Microsystems, Inc. Copyright (C) 1995 Amdahl Corporation.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice are
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided also
21 that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
22 General Public License" are included exactly as in the original, and
23 provided that the entire resulting derived work is distributed under the
24 terms of a permission notice identical to this one.
26 Permission is granted to copy and distribute translations of this
27 manual into another language, under the above conditions for modified
28 versions, except that the sections entitled "The GNU Manifesto",
29 "Distribution" and "GNU General Public License" may be included in a
30 translation approved by the author instead of in the original English.
33 File: xemacs.info, Node: Display Vars, Prev: Selective Display, Up: Display
35 Variables Controlling Display
36 =============================
38 This section contains information for customization only. Beginning
41 When you reenter XEmacs after suspending, XEmacs normally clears the
42 screen and redraws the entire display. On some terminals with more than
43 one page of memory, it is possible to arrange the termcap entry so that
44 the `ti' and `te' strings (output to the terminal when XEmacs is
45 entered and exited, respectively) switch between pages of memory so as
46 to use one page for XEmacs and another page for other output. In that
47 case, you might want to set the variable `no-redraw-on-reenter' to
48 non-`nil' so that XEmacs will assume, when resumed, that the screen
49 page it is using still contains what XEmacs last wrote there.
51 The variable `echo-keystrokes' controls the echoing of
52 multi-character keys; its value is the number of seconds of pause
53 required to cause echoing to start, or zero, meaning don't echo at all.
56 If the variable `ctl-arrow' is `nil', control characters in the
57 buffer are displayed with octal escape sequences, all except newline and
58 tab. If its value is `t', then control characters will be printed with
59 an up-arrow, for example `^A'.
61 If its value is not `t' and not `nil', then characters whose code is
62 greater than 160 (that is, the space character (32) with its high bit
63 set) will be assumed to be printable, and will be displayed without
64 alteration. This is the default when running under X Windows, since
65 XEmacs assumes an ISO/8859-1 character set (also known as "Latin1").
66 The `ctl-arrow' variable may also be set to an integer, in which case
67 all characters whose codes are greater than or equal to that value will
68 be assumed to be printable.
70 Altering the value of `ctl-arrow' makes it local to the current
71 buffer; until that time, the default value is in effect. *Note
74 Normally, a tab character in the buffer is displayed as whitespace
75 which extends to the next display tab stop position, and display tab
76 stops come at intervals equal to eight spaces. The number of spaces
77 per tab is controlled by the variable `tab-width', which is made local
78 by changing it, just like `ctl-arrow'. Note that how the tab character
79 in the buffer is displayed has nothing to do with the definition of
82 If you set the variable `selective-display-ellipses' to `nil', the
83 three dots at the end of a line that precedes invisible lines do not
84 appear. There is no visible indication of the invisible lines. This
85 variable becomes local automatically when set.
88 File: xemacs.info, Node: Search, Next: Fixit, Prev: Display, Up: Top
90 Searching and Replacement
91 *************************
93 Like other editors, Emacs has commands for searching for occurrences
94 of a string. The principal search command is unusual in that it is
95 "incremental": it begins to search before you have finished typing the
96 search string. There are also non-incremental search commands more like
97 those of other editors.
99 Besides the usual `replace-string' command that finds all
100 occurrences of one string and replaces them with another, Emacs has a
101 fancy replacement command called `query-replace' which asks
102 interactively which occurrences to replace.
106 * Incremental Search:: Search happens as you type the string.
107 * Non-Incremental Search:: Specify entire string and then search.
108 * Word Search:: Search for sequence of words.
109 * Regexp Search:: Search for match for a regexp.
110 * Regexps:: Syntax of regular expressions.
111 * Search Case:: To ignore case while searching, or not.
112 * Replace:: Search, and replace some or all matches.
113 * Other Repeating Search:: Operating on all matches for some regexp.
116 File: xemacs.info, Node: Incremental Search, Next: Non-Incremental Search, Prev: Search, Up: Search
121 An incremental search begins searching as soon as you type the first
122 character of the search string. As you type in the search string, Emacs
123 shows you where the string (as you have typed it so far) is found.
124 When you have typed enough characters to identify the place you want,
125 you can stop. Depending on what you do next, you may or may not need to
126 terminate the search explicitly with a <RET>.
129 Incremental search forward (`isearch-forward').
132 Incremental search backward (`isearch-backward').
134 `C-s' starts an incremental search. `C-s' reads characters from the
135 keyboard and positions the cursor at the first occurrence of the
136 characters that you have typed. If you type `C-s' and then `F', the
137 cursor moves right after the first `F'. Type an `O', and see the
138 cursor move to after the first `FO'. After another `O', the cursor is
139 after the first `FOO' after the place where you started the search.
140 Meanwhile, the search string `FOO' has been echoed in the echo area.
142 The echo area display ends with three dots when actual searching is
143 going on. When search is waiting for more input, the three dots are
144 removed. (On slow terminals, the three dots are not displayed.)
146 If you make a mistake in typing the search string, you can erase
147 characters with <DEL>. Each <DEL> cancels the last character of the
148 search string. This does not happen until Emacs is ready to read
149 another input character; first it must either find, or fail to find,
150 the character you want to erase. If you do not want to wait for this
151 to happen, use `C-g' as described below.
153 When you are satisfied with the place you have reached, you can type
154 <RET> (or <C-m>), which stops searching, leaving the cursor where the
155 search brought it. Any command not specially meaningful in searches
156 also stops the search and is then executed. Thus, typing `C-a' exits
157 the search and then moves to the beginning of the line. <RET> is
158 necessary only if the next command you want to type is a printing
159 character, <DEL>, <ESC>, or another control character that is special
160 within searches (`C-q', `C-w', `C-r', `C-s', or `C-y').
162 Sometimes you search for `FOO' and find it, but were actually
163 looking for a different occurance of it. To move to the next occurrence
164 of the search string, type another `C-s'. Do this as often as
165 necessary. If you overshoot, you can cancel some `C-s' characters with
168 After you exit a search, you can search for the same string again by
169 typing just `C-s C-s': the first `C-s' is the key that invokes
170 incremental search, and the second `C-s' means "search again".
172 If the specified string is not found at all, the echo area displays
173 the text `Failing I-Search'. The cursor is after the place where Emacs
174 found as much of your string as it could. Thus, if you search for
175 `FOOT', and there is no `FOOT', the cursor may be after the `FOO' in
176 `FOOL'. At this point there are several things you can do. If you
177 mistyped the search string, correct it. If you like the place you have
178 found, you can type <RET> or some other Emacs command to "accept what
179 the search offered". Or you can type `C-g', which removes from the
180 search string the characters that could not be found (the `T' in
181 `FOOT'), leaving those that were found (the `FOO' in `FOOT'). A second
182 `C-g' at that point cancels the search entirely, returning point to
183 where it was when the search started.
185 If a search is failing and you ask to repeat it by typing another
186 `C-s', it starts again from the beginning of the buffer. Repeating a
187 failing backward search with `C-r' starts again from the end. This is
188 called "wrapping around". `Wrapped' appears in the search prompt once
191 The `C-g' "quit" character does special things during searches; just
192 what it does depends on the status of the search. If the search has
193 found what you specified and is waiting for input, `C-g' cancels the
194 entire search. The cursor moves back to where you started the search.
195 If `C-g' is typed when there are characters in the search string that
196 have not been found--because Emacs is still searching for them, or
197 because it has failed to find them--then the search string characters
198 which have not been found are discarded from the search string. The
199 search is now successful and waiting for more input, so a second `C-g'
200 cancels the entire search.
202 To search for a control character such as `C-s' or <DEL> or <ESC>,
203 you must quote it by typing `C-q' first. This function of `C-q' is
204 analogous to its meaning as an Emacs command: it causes the following
205 character to be treated the way a graphic character would normally be
206 treated in the same context.
208 To search backwards, you can use `C-r' instead of `C-s' to start the
209 search; `C-r' is the key that runs the command (`isearch-backward') to
210 search backward. You can also use `C-r' to change from searching
211 forward to searching backwards. Do this if a search fails because the
212 place you started was too far down in the file. Repeated `C-r' keeps
213 looking for more occurrences backwards. `C-s' starts going forward
214 again. You can cancel `C-r' in a search with <DEL>.
216 The characters `C-y' and `C-w' can be used in incremental search to
217 grab text from the buffer into the search string. This makes it
218 convenient to search for another occurrence of text at point. `C-w'
219 copies the word after point as part of the search string, advancing
220 point over that word. Another `C-s' to repeat the search will then
221 search for a string including that word. `C-y' is similar to `C-w' but
222 copies the rest of the current line into the search string.
224 The characters `M-p' and `M-n' can be used in an incremental search
225 to recall things which you have searched for in the past. A list of
226 the last 16 things you have searched for is retained, and `M-p' and
227 `M-n' let you cycle through that ring.
229 The character `M-<TAB>' does completion on the elements in the
230 search history ring. For example, if you know that you have recently
231 searched for the string `POTATOE', you could type `C-s P O M-<TAB>'.
232 If you had searched for other strings beginning with `PO' then you
233 would be shown a list of them, and would need to type more to select
236 You can change any of the special characters in incremental search
237 via the normal keybinding mechanism: simply add a binding to the
238 `isearch-mode-map'. For example, to make the character `C-b' mean
239 "search backwards" while in isearch-mode, do this:
241 (define-key isearch-mode-map "\C-b" 'isearch-repeat-backward)
243 These are the default bindings of isearch-mode:
246 Delete a character from the incremental search string
247 (`isearch-delete-char').
250 Exit incremental search (`isearch-exit').
253 Quote special characters for incremental search
254 (`isearch-quote-char').
257 Repeat incremental search forward (`isearch-repeat-forward').
260 Repeat incremental search backward (`isearch-repeat-backward').
263 Pull rest of line from buffer into search string
264 (`isearch-yank-line').
267 Pull next word from buffer into search string
268 (`isearch-yank-word').
271 Cancels input back to what has been found successfully, or aborts
272 the isearch (`isearch-abort').
275 Recall the previous element in the isearch history ring
276 (`isearch-ring-retreat').
279 Recall the next element in the isearch history ring
280 (`isearch-ring-advance').
283 Do completion on the elements in the isearch history ring
284 (`isearch-complete').
286 Any other character which is normally inserted into a buffer when
287 typed is automatically added to the search string in isearch-mode.
289 Slow Terminal Incremental Search
290 --------------------------------
292 Incremental search on a slow terminal uses a modified style of
293 display that is designed to take less time. Instead of redisplaying
294 the buffer at each place the search gets to, it creates a new
295 single-line window and uses that to display the line the search has
296 found. The single-line window appears as soon as point gets outside of
297 the text that is already on the screen.
299 When the search is terminated, the single-line window is removed.
300 Only at this time the window in which the search was done is
301 redisplayed to show its new value of point.
303 The three dots at the end of the search string, normally used to
304 indicate that searching is going on, are not displayed in slow style
307 The slow terminal style of display is used when the terminal baud
308 rate is less than or equal to the value of the variable
309 `search-slow-speed', initially 1200.
311 The number of lines to use in slow terminal search display is
312 controlled by the variable `search-slow-window-lines'. Its normal
316 File: xemacs.info, Node: Non-Incremental Search, Next: Word Search, Prev: Incremental Search, Up: Search
318 Non-Incremental Search
319 ======================
321 Emacs also has conventional non-incremental search commands, which
322 require you type the entire search string before searching begins.
324 `C-s <RET> STRING <RET>'
327 `C-r <RET> STRING <RET>'
328 Search backward for STRING.
330 To do a non-incremental search, first type `C-s <RET>' (or `C-s
331 C-m'). This enters the minibuffer to read the search string.
332 Terminate the string with <RET> to start the search. If the string is
333 not found, the search command gets an error.
335 By default, `C-s' invokes incremental search, but if you give it an
336 empty argument, which would otherwise be useless, it invokes
337 non-incremental search. Therefore, `C-s <RET>' invokes non-incremental
338 search. `C-r <RET>' also works this way.
340 Forward and backward non-incremental searches are implemented by the
341 commands `search-forward' and `search-backward'. You can bind these
342 commands to keys. The reason that incremental search is programmed to
343 invoke them as well is that `C-s <RET>' is the traditional sequence of
344 characters used in Emacs to invoke non-incremental search.
346 Non-incremental searches performed using `C-s <RET>' do not call
347 `search-forward' right away. They first check if the next character is
348 `C-w', which requests a word search. *Note Word Search::.
351 File: xemacs.info, Node: Word Search, Next: Regexp Search, Prev: Non-Incremental Search, Up: Search
356 Word search looks for a sequence of words without regard to how the
357 words are separated. More precisely, you type a string of many words,
358 using single spaces to separate them, and the string is found even if
359 there are multiple spaces, newlines or other punctuation between the
362 Word search is useful in editing documents formatted by text
363 formatters. If you edit while looking at the printed, formatted
364 version, you can't tell where the line breaks are in the source file.
365 Word search, allows you to search without having to know the line
368 `C-s <RET> C-w WORDS <RET>'
369 Search for WORDS, ignoring differences in punctuation.
371 `C-r <RET> C-w WORDS <RET>'
372 Search backward for WORDS, ignoring differences in punctuation.
374 Word search is a special case of non-incremental search. It is
375 invoked with `C-s <RET> C-w' followed by the search string, which must
376 always be terminated with another <RET>. Being non-incremental, this
377 search does not start until the argument is terminated. It works by
378 constructing a regular expression and searching for that. *Note Regexp
381 You can do a backward word search with `C-r <RET> C-w'.
383 Forward and backward word searches are implemented by the commands
384 `word-search-forward' and `word-search-backward'. You can bind these
385 commands to keys. The reason that incremental search is programmed to
386 invoke them as well is that `C-s <RET> C-w' is the traditional Emacs
387 sequence of keys for word search.
390 File: xemacs.info, Node: Regexp Search, Next: Regexps, Prev: Word Search, Up: Search
392 Regular Expression Search
393 =========================
395 A "regular expression" ("regexp", for short) is a pattern that
396 denotes a set of strings, possibly an infinite set. Searching for
397 matches for a regexp is a powerful operation that editors on Unix
398 systems have traditionally offered. In XEmacs, you can search for the
399 next match for a regexp either incrementally or not.
401 Incremental search for a regexp is done by typing `M-C-s'
402 (`isearch-forward-regexp'). This command reads a search string
403 incrementally just like `C-s', but it treats the search string as a
404 regexp rather than looking for an exact match against the text in the
405 buffer. Each time you add text to the search string, you make the
406 regexp longer, and the new regexp is searched for. A reverse regexp
407 search command `isearch-backward-regexp' also exists, but no key runs
410 All of the control characters that do special things within an
411 ordinary incremental search have the same functionality in incremental
412 regexp search. Typing `C-s' or `C-r' immediately after starting a
413 search retrieves the last incremental search regexp used: incremental
414 regexp and non-regexp searches have independent defaults.
416 Non-incremental search for a regexp is done by the functions
417 `re-search-forward' and `re-search-backward'. You can invoke them with
418 `M-x' or bind them to keys. You can also call `re-search-forward' by
419 way of incremental regexp search with `M-C-s <RET>'.
422 File: xemacs.info, Node: Regexps, Next: Search Case, Prev: Regexp Search, Up: Search
424 Syntax of Regular Expressions
425 =============================
427 Regular expressions have a syntax in which a few characters are
428 special constructs and the rest are "ordinary". An ordinary character
429 is a simple regular expression which matches that character and nothing
430 else. The special characters are `$', `^', `.', `*', `+', `?', `[',
431 `]' and `\'; no new special characters will be defined. Any other
432 character appearing in a regular expression is ordinary, unless a `\'
435 For example, `f' is not a special character, so it is ordinary, and
436 therefore `f' is a regular expression that matches the string `f' and
437 no other string. (It does not match the string `ff'.) Likewise, `o'
438 is a regular expression that matches only `o'.
440 Any two regular expressions A and B can be concatenated. The result
441 is a regular expression which matches a string if A matches some amount
442 of the beginning of that string and B matches the rest of the string.
444 As a simple example, you can concatenate the regular expressions `f'
445 and `o' to get the regular expression `fo', which matches only the
446 string `fo'. To do something nontrivial, you need to use one of the
447 following special characters:
450 is a special character that matches any single character except a
451 newline. Using concatenation, you can make regular expressions
452 like `a.b', which matches any three-character string which begins
453 with `a' and ends with `b'.
456 is not a construct by itself; it is a suffix, which means the
457 preceding regular expression is to be repeated as many times as
458 possible. In `fo*', the `*' applies to the `o', so `fo*' matches
459 one `f' followed by any number of `o's. The case of zero `o's is
460 allowed: `fo*' does match `f'.
462 `*' always applies to the smallest possible preceding expression.
463 Thus, `fo*' has a repeating `o', not a repeating `fo'.
465 The matcher processes a `*' construct by immediately matching as
466 many repetitions as it can find. Then it continues with the rest
467 of the pattern. If that fails, backtracking occurs, discarding
468 some of the matches of the `*'-modified construct in case that
469 makes it possible to match the rest of the pattern. For example,
470 matching `ca*ar' against the string `caaar', the `a*' first tries
471 to match all three `a's; but the rest of the pattern is `ar' and
472 there is only `r' left to match, so this try fails. The next
473 alternative is for `a*' to match only two `a's. With this choice,
474 the rest of the regexp matches successfully.
477 is a suffix character similar to `*' except that it requires that
478 the preceding expression be matched at least once. For example,
479 `ca+r' will match the strings `car' and `caaaar' but not the
480 string `cr', whereas `ca*r' would match all three strings.
483 is a suffix character similar to `*' except that it can match the
484 preceding expression either once or not at all. For example,
485 `ca?r' will match `car' or `cr'; nothing else.
488 `[' begins a "character set", which is terminated by a `]'. In
489 the simplest case, the characters between the two form the set.
490 Thus, `[ad]' matches either one `a' or one `d', and `[ad]*'
491 matches any string composed of just `a's and `d's (including the
492 empty string), from which it follows that `c[ad]*r' matches `cr',
493 `car', `cdr', `caddaar', etc.
495 You can include character ranges in a character set by writing two
496 characters with a `-' between them. Thus, `[a-z]' matches any
497 lower-case letter. Ranges may be intermixed freely with individual
498 characters, as in `[a-z$%.]', which matches any lower-case letter
499 or `$', `%', or period.
501 Note that inside a character set the usual special characters are
502 not special any more. A completely different set of special
503 characters exists inside character sets: `]', `-', and `^'.
505 To include a `]' in a character set, you must make it the first
506 character. For example, `[]a]' matches `]' or `a'. To include a
507 `-', write `---', which is a range containing only `-'. To
508 include `^', make it other than the first character in the set.
511 `[^' begins a "complement character set", which matches any
512 character except the ones specified. Thus, `[^a-z0-9A-Z]' matches
513 all characters except letters and digits.
515 `^' is not special in a character set unless it is the first
516 character. The character following the `^' is treated as if it
517 were first (`-' and `]' are not special there).
519 Note that a complement character set can match a newline, unless
520 newline is mentioned as one of the characters not to match.
523 is a special character that matches the empty string, but only if
524 at the beginning of a line in the text being matched. Otherwise,
525 it fails to match anything. Thus, `^foo' matches a `foo' that
526 occurs at the beginning of a line.
529 is similar to `^' but matches only at the end of a line. Thus,
530 `xx*$' matches a string of one `x' or more at the end of a line.
533 does two things: it quotes the special characters (including `\'),
534 and it introduces additional special constructs.
536 Because `\' quotes special characters, `\$' is a regular
537 expression that matches only `$', and `\[' is a regular expression
538 that matches only `[', and so on.
540 Note: for historical compatibility, special characters are treated as
541 ordinary ones if they are in contexts where their special meanings make
542 no sense. For example, `*foo' treats `*' as ordinary since there is no
543 preceding expression on which the `*' can act. It is poor practice to
544 depend on this behavior; better to quote the special character anyway,
545 regardless of where is appears.
547 Usually, `\' followed by any character matches only that character.
548 However, there are several exceptions: characters which, when preceded
549 by `\', are special constructs. Such characters are always ordinary
550 when encountered on their own. Here is a table of `\' constructs.
553 specifies an alternative. Two regular expressions A and B with
554 `\|' in between form an expression that matches anything A or B
557 Thus, `foo\|bar' matches either `foo' or `bar' but no other string.
559 `\|' applies to the largest possible surrounding expressions.
560 Only a surrounding `\( ... \)' grouping can limit the grouping
563 Full backtracking capability exists to handle multiple uses of
567 is a grouping construct that serves three purposes:
569 1. To enclose a set of `\|' alternatives for other operations.
570 Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
572 2. To enclose a complicated expression for the postfix `*' to
573 operate on. Thus, `ba\(na\)*' matches `bananana', etc., with
574 any (zero or more) number of `na' strings.
576 3. To mark a matched substring for future reference.
579 This last application is not a consequence of the idea of a
580 parenthetical grouping; it is a separate feature which happens to
581 be assigned as a second meaning to the same `\( ... \)' construct
582 because in practice there is no conflict between the two meanings.
583 Here is an explanation:
586 after the end of a `\( ... \)' construct, the matcher remembers the
587 beginning and end of the text matched by that construct. Then,
588 later on in the regular expression, you can use `\' followed by
589 DIGIT to mean "match the same text matched the DIGIT'th time by the
590 `\( ... \)' construct."
592 The strings matching the first nine `\( ... \)' constructs
593 appearing in a regular expression are assigned numbers 1 through 9
594 in order that the open-parentheses appear in the regular
595 expression. `\1' through `\9' may be used to refer to the text
596 matched by the corresponding `\( ... \)' construct.
598 For example, `\(.*\)\1' matches any newline-free string that is
599 composed of two identical halves. The `\(.*\)' matches the first
600 half, which may be anything, but the `\1' that follows must match
604 matches the empty string, provided it is at the beginning of the
608 matches the empty string, provided it is at the end of the buffer.
611 matches the empty string, provided it is at the beginning or end
612 of a word. Thus, `\bfoo\b' matches any occurrence of `foo' as a
613 separate word. `\bballs?\b' matches `ball' or `balls' as a
617 matches the empty string, provided it is not at the beginning or
621 matches the empty string, provided it is at the beginning of a
625 matches the empty string, provided it is at the end of a word.
628 matches any word-constituent character. The editor syntax table
629 determines which characters these are.
632 matches any character that is not a word-constituent.
635 matches any character whose syntax is CODE. CODE is a character
636 which represents a syntax code: thus, `w' for word constituent,
637 `-' for whitespace, `(' for open-parenthesis, etc. *Note Syntax::.
640 matches any character whose syntax is not CODE.
642 Here is a complicated regexp used by Emacs to recognize the end of a
643 sentence together with any whitespace that follows. It is given in Lisp
644 syntax to enable you to distinguish the spaces from the tab characters.
645 In Lisp syntax, the string constant begins and ends with a
646 double-quote. `\"' stands for a double-quote as part of the regexp,
647 `\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for
650 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
652 This regexp contains four parts: a character set matching period, `?'
653 or `!'; a character set matching close-brackets, quotes or parentheses,
654 repeated any number of times; an alternative in backslash-parentheses
655 that matches end-of-line, a tab or two spaces; and a character set
656 matching whitespace characters, repeated any number of times.
659 File: xemacs.info, Node: Search Case, Next: Replace, Prev: Regexps, Up: Search
664 All searches in Emacs normally ignore the case of the text they are
665 searching through; if you specify searching for `FOO', `Foo' and `foo'
666 are also considered a match. Regexps, and in particular character
667 sets, are included: `[aB]' matches `a' or `A' or `b' or `B'.
669 If you want a case-sensitive search, set the variable
670 `case-fold-search' to `nil'. Then all letters must match exactly,
671 including case. `case-fold-search' is a per-buffer variable; altering
672 it affects only the current buffer, but there is a default value which
673 you can change as well. *Note Locals::. You can also use Case
674 Sensitive Search from the Options menu on your screen.
677 File: xemacs.info, Node: Replace, Next: Other Repeating Search, Prev: Search Case, Up: Search
682 Global search-and-replace operations are not needed as often in
683 Emacs as they are in other editors, but they are available. In
684 addition to the simple `replace-string' command which is like that
685 found in most editors, there is a `query-replace' command which asks
686 you, for each occurrence of a pattern, whether to replace it.
688 The replace commands all replace one string (or regexp) with one
689 replacement string. It is possible to perform several replacements in
690 parallel using the command `expand-region-abbrevs'. *Note Expanding
695 * Unconditional Replace:: Replacing all matches for a string.
696 * Regexp Replace:: Replacing all matches for a regexp.
697 * Replacement and Case:: How replacements preserve case of letters.
698 * Query Replace:: How to use querying.
701 File: xemacs.info, Node: Unconditional Replace, Next: Regexp Replace, Prev: Replace, Up: Replace
703 Unconditional Replacement
704 -------------------------
706 `M-x replace-string <RET> STRING <RET> NEWSTRING <RET>'
707 Replace every occurrence of STRING with NEWSTRING.
709 `M-x replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
710 Replace every match for REGEXP with NEWSTRING.
712 To replace every instance of `foo' after point with `bar', use the
713 command `M-x replace-string' with the two arguments `foo' and `bar'.
714 Replacement occurs only after point: if you want to cover the whole
715 buffer you must go to the beginning first. By default, all occurrences
716 up to the end of the buffer are replaced. To limit replacement to part
717 of the buffer, narrow to that part of the buffer before doing the
718 replacement (*note Narrowing::).
720 When `replace-string' exits, point is left at the last occurrence
721 replaced. The value of point when the `replace-string' command was
722 issued is remembered on the mark ring; `C-u C-<SPC>' moves back there.
724 A numeric argument restricts replacement to matches that are
725 surrounded by word boundaries.
728 File: xemacs.info, Node: Regexp Replace, Next: Replacement and Case, Prev: Unconditional Replace, Up: Replace
733 `replace-string' replaces exact matches for a single string. The
734 similar command `replace-regexp' replaces any match for a specified
737 In `replace-regexp', the NEWSTRING need not be constant. It can
738 refer to all or part of what is matched by the REGEXP. `\&' in
739 NEWSTRING stands for the entire text being replaced. `\D' in
740 NEWSTRING, where D is a digit, stands for whatever matched the D'th
741 parenthesized grouping in REGEXP. For example,
743 M-x replace-regexp <RET> c[ad]+r <RET> \&-safe <RET>
745 would replace (for example) `cadr' with `cadr-safe' and `cddr' with
748 M-x replace-regexp <RET> \(c[ad]+r\)-safe <RET> \1 <RET>
750 would perform exactly the opposite replacements. To include a `\' in
751 the text to replace with, you must give `\\'.
754 File: xemacs.info, Node: Replacement and Case, Next: Query Replace, Prev: Regexp Replace, Up: Replace
756 Replace Commands and Case
757 -------------------------
759 If the arguments to a replace command are in lower case, the command
760 preserves case when it makes a replacement. Thus, the following
763 M-x replace-string <RET> foo <RET> bar <RET>
765 replaces a lower-case `foo' with a lower case `bar', `FOO' with `BAR',
766 and `Foo' with `Bar'. If upper-case letters are used in the second
767 argument, they remain upper-case every time that argument is inserted.
768 If upper-case letters are used in the first argument, the second
769 argument is always substituted exactly as given, with no case
770 conversion. Likewise, if the variable `case-replace' is set to `nil',
771 replacement is done without case conversion. If `case-fold-search' is
772 set to `nil', case is significant in matching occurrences of `foo' to
773 replace; also, case conversion of the replacement string is not done.
776 File: xemacs.info, Node: Query Replace, Prev: Replacement and Case, Up: Replace
781 `M-% STRING <RET> NEWSTRING <RET>'
782 `M-x query-replace <RET> STRING <RET> NEWSTRING <RET>'
783 Replace some occurrences of STRING with NEWSTRING.
785 `M-x query-replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
786 Replace some matches for REGEXP with NEWSTRING.
788 If you want to change only some of the occurrences of `foo' to
789 `bar', not all of them, you can use `query-replace' instead of `M-%'.
790 This command finds occurrences of `foo' one by one, displays each
791 occurrence, and asks you whether to replace it. A numeric argument to
792 `query-replace' tells it to consider only occurrences that are bounded
793 by word-delimiter characters.
795 Aside from querying, `query-replace' works just like
796 `replace-string', and `query-replace-regexp' works just like
799 The things you can type when you are shown an occurrence of STRING
800 or a match for REGEXP are:
803 to replace the occurrence with NEWSTRING. This preserves case,
804 just like `replace-string', provided `case-replace' is non-`nil',
808 to skip to the next occurrence without replacing this one.
811 to replace this occurrence and display the result. You are then
812 prompted for another input character. However, since the
813 replacement has already been made, <DEL> and <SPC> are equivalent.
814 At this point, you can type `C-r' (see below) to alter the
815 replaced text. To undo the replacement, you can type `C-x u'.
816 This exits the `query-replace'. If you want to do further
817 replacement you must use `C-x ESC' to restart (*note Repetition::).
820 to exit without doing any more replacements.
823 to replace this occurrence and then exit.
826 to replace all remaining occurrences without asking again.
829 to go back to the location of the previous occurrence (or what
830 used to be an occurrence), in case you changed it by mistake.
831 This works by popping the mark ring. Only one `^' in a row is
832 allowed, because only one previous replacement location is kept
833 during `query-replace'.
836 to enter a recursive editing level, in case the occurrence needs
837 to be edited rather than just replaced with NEWSTRING. When you
838 are done, exit the recursive editing level with `C-M-c' and the
839 next occurrence will be displayed. *Note Recursive Edit::.
842 to delete the occurrence, and then enter a recursive editing level
843 as in `C-r'. Use the recursive edit to insert text to replace the
844 deleted occurrence of STRING. When done, exit the recursive
845 editing level with `C-M-c' and the next occurrence will be
849 to redisplay the screen and then give another answer.
852 to display a message summarizing these options, then give another
855 If you type any other character, Emacs exits the `query-replace', and
856 executes the character as a command. To restart the `query-replace',
857 use `C-x <ESC>', which repeats the `query-replace' because it used the
858 minibuffer to read its arguments. *Note C-x ESC: Repetition.
861 File: xemacs.info, Node: Other Repeating Search, Prev: Replace, Up: Search
863 Other Search-and-Loop Commands
864 ==============================
866 Here are some other commands that find matches for a regular
867 expression. They all operate from point to the end of the buffer.
870 Print each line that follows point and contains a match for the
871 specified regexp. A numeric argument specifies the number of
872 context lines to print before and after each matching line; the
875 The buffer `*Occur*' containing the output serves as a menu for
876 finding occurrences in their original context. Find an occurrence
877 as listed in `*Occur*', position point there, and type `C-c C-c';
878 this switches to the buffer that was searched and moves point to
879 the original of the same occurrence.
881 `M-x list-matching-lines'
882 Synonym for `M-x occur'.
885 Print the number of matches following point for the specified
888 `M-x delete-non-matching-lines'
889 Delete each line that follows point and does not contain a match
890 for the specified regexp.
892 `M-x delete-matching-lines'
893 Delete each line that follows point and contains a match for the
897 File: xemacs.info, Node: Fixit, Next: Files, Prev: Search, Up: Top
899 Commands for Fixing Typos
900 *************************
902 This chapter describes commands that are especially useful when you
903 catch a mistake in your text just after you have made it, or when you
904 change your mind while composing text on line.
908 * Kill Errors:: Commands to kill a batch of recently entered text.
909 * Transpose:: Exchanging two characters, words, lines, lists...
910 * Fixing Case:: Correcting case of last word entered.
911 * Spelling:: Apply spelling checker to a word, or a whole file.
914 File: xemacs.info, Node: Kill Errors, Next: Transpose, Prev: Fixit, Up: Fixit
916 Killing Your Mistakes
917 =====================
920 Delete last character (`delete-backward-char').
923 Kill last word (`backward-kill-word').
926 Kill to beginning of sentence (`backward-kill-sentence').
928 The <DEL> character (`delete-backward-char') is the most important
929 correction command. When used among graphic (self-inserting)
930 characters, it can be thought of as canceling the last character typed.
932 When your mistake is longer than a couple of characters, it might be
933 more convenient to use `M-<DEL>' or `C-x <DEL>'. `M-<DEL>' kills back
934 to the start of the last word, and `C-x <DEL>' kills back to the start
935 of the last sentence. `C-x <DEL>' is particularly useful when you are
936 thinking of what to write as you type it, in case you change your mind
937 about phrasing. `M-<DEL>' and `C-x <DEL>' save the killed text for
938 `C-y' and `M-y' to retrieve. *Note Yanking::.
940 `M-<DEL>' is often useful even when you have typed only a few
941 characters wrong, if you know you are confused in your typing and aren't
942 sure exactly what you typed. At such a time, you cannot correct with
943 <DEL> except by looking at the screen to see what you did. It requires
944 less thought to kill the whole word and start over.
947 File: xemacs.info, Node: Transpose, Next: Fixing Case, Prev: Kill Errors, Up: Fixit
953 Transpose two characters (`transpose-chars').
956 Transpose two words (`transpose-words').
959 Transpose two balanced expressions (`transpose-sexps').
962 Transpose two lines (`transpose-lines').
964 The common error of transposing two adjacent characters can be fixed
965 with the `C-t' command (`transpose-chars'). Normally, `C-t' transposes
966 the two characters on either side of point. When given at the end of a
967 line, `C-t' transposes the last two characters on the line, rather than
968 transposing the last character of the line with the newline, which
969 would be useless. If you catch a transposition error right away, you
970 can fix it with just `C-t'. If you catch the error later, move the
971 cursor back to between the two transposed characters. If you
972 transposed a space with the last character of the word before it, the
973 word motion commands are a good way of getting there. Otherwise, a
974 reverse search (`C-r') is often the best way. *Note Search::.
976 `Meta-t' (`transpose-words') transposes the word before point with
977 the word after point. It moves point forward over a word, dragging the
978 word preceding or containing point forward as well. The punctuation
979 characters between the words do not move. For example, `FOO, BAR'
980 transposes into `BAR, FOO' rather than `BAR FOO,'.
982 `C-M-t' (`transpose-sexps') is a similar command for transposing two
983 expressions (*note Lists::), and `C-x C-t' (`transpose-lines')
984 exchanges lines. It works like `M-t' but in determines the division of
985 the text into syntactic units differently.
987 A numeric argument to a transpose command serves as a repeat count:
988 it tells the transpose command to move the character (word, sexp, line)
989 before or containing point across several other characters (words,
990 sexps, lines). For example, `C-u 3 C-t' moves the character before
991 point forward across three other characters. This is equivalent to
992 repeating `C-t' three times. `C-u - 4 M-t' moves the word before point
993 backward across four words. `C-u - C-M-t' would cancel the effect of
996 A numeric argument of zero transposes the character (word, sexp,
997 line) ending after point with the one ending after the mark (otherwise a
998 command with a repeat count of zero would do nothing).
1001 File: xemacs.info, Node: Fixing Case, Next: Spelling, Prev: Transpose, Up: Fixit
1007 Convert last word to lower case. Note that `Meta--' is
1011 Convert last word to all upper case.
1014 Convert last word to lower case with capital initial.
1016 A common error is to type words in the wrong case. Because of this,
1017 the word case-conversion commands `M-l', `M-u', and `M-c' do not move
1018 the cursor when used with a negative argument. As soon as you see you
1019 have mistyped the last word, you can simply case-convert it and
1020 continue typing. *Note Case::.
1023 File: xemacs.info, Node: Spelling, Prev: Fixing Case, Up: Fixit
1025 Checking and Correcting Spelling
1026 ================================
1029 Check and correct spelling of word (`spell-word').
1032 Check and correct spelling of each word in the buffer.
1035 Check and correct spelling of each word in the region.
1038 Check spelling of specified word.
1040 To check the spelling of the word before point, and optionally
1041 correct it, use the command `M-$' (`spell-word'). This command runs an
1042 inferior process containing the `spell' program to see whether the word
1043 is correct English. If it is not, it asks you to edit the word (in the
1044 minibuffer) into a corrected spelling, and then performs a
1045 `query-replace' to substitute the corrected spelling for the old one
1046 throughout the buffer.
1048 If you exit the minibuffer without altering the original spelling, it
1049 means you do not want to do anything to that word. In that case, the
1050 `query-replace' is not done.
1052 `M-x spell-buffer' checks each word in the buffer the same way that
1053 `spell-word' does, doing a `query-replace' for every incorrect word if
1056 `M-x spell-region' is similar to `spell-buffer' but operates only on
1057 the region, not the entire buffer.
1059 `M-x spell-string' reads a string as an argument and checks whether
1060 that is a correctly spelled English word. It prints a message giving
1061 the answer in the echo area.
1064 File: xemacs.info, Node: Files, Next: Buffers, Prev: Fixit, Up: Top
1069 The basic unit of stored data in Unix is the "file". To edit a file,
1070 you must tell Emacs to examine the file and prepare a buffer containing
1071 a copy of the file's text. This is called "visiting" the file. Editing
1072 commands apply directly to text in the buffer; that is, to the copy
1073 inside Emacs. Your changes appear in the file itself only when you
1074 "save" the buffer back into the file.
1076 In addition to visiting and saving files, Emacs can delete, copy,
1077 rename, and append to files, and operate on file directories.
1081 * File Names:: How to type and edit file name arguments.
1082 * Visiting:: Visiting a file prepares Emacs to edit the file.
1083 * Saving:: Saving makes your changes permanent.
1084 * Reverting:: Reverting cancels all the changes not saved.
1085 * Auto Save:: Auto Save periodically protects against loss of data.
1086 * Version Control:: Version control systems (RCS and SCCS).
1087 * ListDir:: Listing the contents of a file directory.
1088 * Comparing Files:: Finding where two files differ.
1089 * Dired:: ``Editing'' a directory to delete, rename, etc.
1091 * Misc File Ops:: Other things you can do on files.
1094 File: xemacs.info, Node: File Names, Next: Visiting, Prev: Files, Up: Files
1099 Most Emacs commands that operate on a file require you to specify the
1100 file name. (Saving and reverting are exceptions; the buffer knows which
1101 file name to use for them.) File names are specified in the minibuffer
1102 (*note Minibuffer::). "Completion" is available, to make it easier to
1103 specify long file names. *Note Completion::.
1105 There is always a "default file name" which is used if you enter an
1106 empty argument by typing just <RET>. Normally the default file name is
1107 the name of the file visited in the current buffer; this makes it easy
1108 to operate on that file with any of the Emacs file commands.
1110 Each buffer has a default directory, normally the same as the
1111 directory of the file visited in that buffer. When Emacs reads a file
1112 name, the default directory is used if you do not specify a directory.
1113 If you specify a directory in a relative fashion, with a name that does
1114 not start with a slash, it is interpreted with respect to the default
1115 directory. The default directory of the current buffer is kept in the
1116 variable `default-directory', which has a separate value in every
1117 buffer. The value of the variable should end with a slash.
1119 For example, if the default file name is `/u/rms/gnu/gnu.tasks' then
1120 the default directory is `/u/rms/gnu/'. If you type just `foo', which
1121 does not specify a directory, it is short for `/u/rms/gnu/foo'.
1122 `../.login' would stand for `/u/rms/.login'. `new/foo' would stand for
1123 the filename `/u/rms/gnu/new/foo'.
1125 The variable `default-directory-alist' takes an alist of major modes
1126 and their opinions on `default-directory' as a Lisp expression to
1127 evaluate. A resulting value of `nil' is ignored in favor of
1128 `default-directory'.
1130 You can create a new directory with the function `make-directory',
1131 which takes as an argument a file name string. The current directory is
1132 displayed in the minibuffer when the function is called; you can delete
1133 the old directory name and supply a new directory name. For example, if
1134 the current directory is `/u/rms/gnu', you can delete `gnu' and type
1135 `oryx' and <RET> to create `/u/rms/oryx'. Removing a directory is
1136 similar to creating one. To remove a directory, use
1137 `remove-directory'; it takes one argument, a file name string.
1139 The command `M-x pwd' prints the current buffer's default directory,
1140 and the command `M-x cd' sets it (to a value read using the
1141 minibuffer). A buffer's default directory changes only when the `cd'
1142 command is used. A file-visiting buffer's default directory is
1143 initialized to the directory of the file that is visited there. If a
1144 buffer is created with `C-x b', its default directory is copied from
1145 that of the buffer that was current at the time.
1147 The default directory name actually appears in the minibuffer when
1148 the minibuffer becomes active to read a file name. This serves two
1149 purposes: it shows you what the default is, so that you can type a
1150 relative file name and know with certainty what it will mean, and it
1151 allows you to edit the default to specify a different directory. To
1152 inhibit the insertion of the default directory, set the variable
1153 `insert-default-directory' to `nil'.
1155 Note that it is legitimate to type an absolute file name after you
1156 enter the minibuffer, ignoring the presence of the default directory
1157 name. The final minibuffer contents may look invalid, but that is not
1158 so. *Note Minibuffer File::.
1160 `$' in a file name is used to substitute environment variables. For
1161 example, if you have used the shell command `setenv FOO rms/hacks' to
1162 set up an environment variable named `FOO', then you can use
1163 `/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for
1164 `/u/rms/hacks/test.c'. The environment variable name consists of all
1165 the alphanumeric characters after the `$'; alternatively, it may be
1166 enclosed in braces after the `$'. Note that the `setenv' command
1167 affects Emacs only if done before Emacs is started.
1169 To access a file with `$' in its name, type `$$'. This pair is
1170 converted to a single `$' at the same time variable substitution is
1171 performed for single `$'. The Lisp function that performs the
1172 substitution is called `substitute-in-file-name'. The substitution is
1173 performed only on filenames read as such using the minibuffer.