1 This is ../info/xemacs.info, produced by makeinfo version 4.0b 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: Regexps, Next: Search Case, Prev: Regexp Search, Up: Search
35 Syntax of Regular Expressions
36 =============================
38 Regular expressions have a syntax in which a few characters are
39 special constructs and the rest are "ordinary". An ordinary character
40 is a simple regular expression that matches that character and nothing
41 else. The special characters are `.', `*', `+', `?', `[', `]', `^',
42 `$', and `\'; no new special characters will be defined in the future.
43 Any other character appearing in a regular expression is ordinary,
44 unless a `\' precedes it.
46 For example, `f' is not a special character, so it is ordinary, and
47 therefore `f' is a regular expression that matches the string `f' and
48 no other string. (It does _not_ match the string `ff'.) Likewise, `o'
49 is a regular expression that matches only `o'.
51 Any two regular expressions A and B can be concatenated. The result
52 is a regular expression that matches a string if A matches some amount
53 of the beginning of that string and B matches the rest of the string.
55 As a simple example, we can concatenate the regular expressions `f'
56 and `o' to get the regular expression `fo', which matches only the
57 string `fo'. Still trivial. To do something more powerful, you need
58 to use one of the special characters. Here is a list of them:
61 is a special character that matches any single character except a
62 newline. Using concatenation, we can make regular expressions
63 like `a.b', which matches any three-character string that begins
64 with `a' and ends with `b'.
67 is not a construct by itself; it is a quantifying suffix operator
68 that means to repeat the preceding regular expression as many
69 times as possible. In `fo*', the `*' applies to the `o', so `fo*'
70 matches one `f' followed by any number of `o's. The case of zero
71 `o's is allowed: `fo*' does match `f'.
73 `*' always applies to the _smallest_ possible preceding
74 expression. Thus, `fo*' has a repeating `o', not a repeating `fo'.
76 The matcher processes a `*' construct by matching, immediately, as
77 many repetitions as can be found; it is "greedy". Then it
78 continues with the rest of the pattern. If that fails,
79 backtracking occurs, discarding some of the matches of the
80 `*'-modified construct in case that makes it possible to match the
81 rest of the pattern. For example, in matching `ca*ar' against the
82 string `caaar', the `a*' first tries to match all three `a's; but
83 the rest of the pattern is `ar' and there is only `r' left to
84 match, so this try fails. The next alternative is for `a*' to
85 match only two `a's. With this choice, the rest of the regexp
88 Nested repetition operators can be extremely slow if they specify
89 backtracking loops. For example, it could take hours for the
90 regular expression `\(x+y*\)*a' to match the sequence
91 `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz'. The slowness is because
92 Emacs must try each imaginable way of grouping the 35 `x''s before
93 concluding that none of them can work. To make sure your regular
94 expressions run fast, check nested repetitions carefully.
97 is a quantifying suffix operator similar to `*' except that the
98 preceding expression must match at least once. It is also
99 "greedy". So, for example, `ca+r' matches the strings `car' and
100 `caaaar' but not the string `cr', whereas `ca*r' matches all three
104 is a quantifying suffix operator similar to `*', except that the
105 preceding expression can match either once or not at all. For
106 example, `ca?r' matches `car' or `cr', but does not match anything
110 works just like `*', except that rather than matching the longest
111 match, it matches the shortest match. `*?' is known as a
112 "non-greedy" quantifier, a regexp construct borrowed from Perl.
114 This construct is very useful for when you want to match the text
115 inside a pair of delimiters. For instance, `/\*.*?\*/' will match
116 C comments in a string. This could not easily be achieved without
117 the use of a non-greedy quantifier.
119 This construct has not been available prior to XEmacs 20.4. It is
120 not available in FSF Emacs.
123 is the non-greedy version of `+'.
126 is the non-greedy version of `?'.
129 serves as an interval quantifier, analogous to `*' or `+', but
130 specifies that the expression must match at least N times, but no
131 more than M times. This syntax is supported by most Unix regexp
132 utilities, and has been introduced to XEmacs for the version 20.3.
134 Unfortunately, the non-greedy version of this quantifier does not
135 exist currently, although it does in Perl.
138 `[' begins a "character set", which is terminated by a `]'. In
139 the simplest case, the characters between the two brackets form
140 the set. Thus, `[ad]' matches either one `a' or one `d', and
141 `[ad]*' matches any string composed of just `a's and `d's
142 (including the empty string), from which it follows that `c[ad]*r'
143 matches `cr', `car', `cdr', `caddaar', etc.
145 The usual regular expression special characters are not special
146 inside a character set. A completely different set of special
147 characters exists inside character sets: `]', `-' and `^'.
149 `-' is used for ranges of characters. To write a range, write two
150 characters with a `-' between them. Thus, `[a-z]' matches any
151 lower case letter. Ranges may be intermixed freely with individual
152 characters, as in `[a-z$%.]', which matches any lower case letter
153 or `$', `%', or a period.
155 To include a `]' in a character set, make it the first character.
156 For example, `[]a]' matches `]' or `a'. To include a `-', write
157 `-' as the first character in the set, or put it immediately after
158 a range. (You can replace one individual character C with the
159 range `C-C' to make a place to put the `-'.) There is no way to
160 write a set containing just `-' and `]'.
162 To include `^' in a set, put it anywhere but at the beginning of
166 `[^' begins a "complement character set", which matches any
167 character except the ones specified. Thus, `[^a-z0-9A-Z]' matches
168 all characters _except_ letters and digits.
170 `^' is not special in a character set unless it is the first
171 character. The character following the `^' is treated as if it
172 were first (thus, `-' and `]' are not special there).
174 Note that a complement character set can match a newline, unless
175 newline is mentioned as one of the characters not to match.
178 is a special character that matches the empty string, but only at
179 the beginning of a line in the text being matched. Otherwise it
180 fails to match anything. Thus, `^foo' matches a `foo' that occurs
181 at the beginning of a line.
183 When matching a string instead of a buffer, `^' matches at the
184 beginning of the string or after a newline character `\n'.
187 is similar to `^' but matches only at the end of a line. Thus,
188 `x+$' matches a string of one `x' or more at the end of a line.
190 When matching a string instead of a buffer, `$' matches at the end
191 of the string or before a newline character `\n'.
194 has two functions: it quotes the special characters (including
195 `\'), and it introduces additional special constructs.
197 Because `\' quotes special characters, `\$' is a regular
198 expression that matches only `$', and `\[' is a regular expression
199 that matches only `[', and so on.
201 *Please note:* For historical compatibility, special characters are
202 treated as ordinary ones if they are in contexts where their special
203 meanings make no sense. For example, `*foo' treats `*' as ordinary
204 since there is no preceding expression on which the `*' can act. It is
205 poor practice to depend on this behavior; quote the special character
206 anyway, regardless of where it appears.
208 For the most part, `\' followed by any character matches only that
209 character. However, there are several exceptions: characters that,
210 when preceded by `\', are special constructs. Such characters are
211 always ordinary when encountered on their own. Here is a table of `\'
215 specifies an alternative. Two regular expressions A and B with
216 `\|' in between form an expression that matches anything that
217 either A or B matches.
219 Thus, `foo\|bar' matches either `foo' or `bar' but no other string.
221 `\|' applies to the largest possible surrounding expressions.
222 Only a surrounding `\( ... \)' grouping can limit the grouping
225 Full backtracking capability exists to handle multiple uses of
229 is a grouping construct that serves three purposes:
231 1. To enclose a set of `\|' alternatives for other operations.
232 Thus, `\(foo\|bar\)x' matches either `foox' or `barx'.
234 2. To enclose an expression for a suffix operator such as `*' to
235 act on. Thus, `ba\(na\)*' matches `bananana', etc., with any
236 (zero or more) number of `na' strings.
238 3. To record a matched substring for future reference.
240 This last application is not a consequence of the idea of a
241 parenthetical grouping; it is a separate feature that happens to be
242 assigned as a second meaning to the same `\( ... \)' construct
243 because there is no conflict in practice between the two meanings.
244 Here is an explanation of this feature:
247 matches the same text that matched the DIGITth occurrence of a `\(
250 In other words, after the end of a `\( ... \)' construct. the
251 matcher remembers the beginning and end of the text matched by that
252 construct. Then, later on in the regular expression, you can use
253 `\' followed by DIGIT to match that same text, whatever it may
256 The strings matching the first nine `\( ... \)' constructs
257 appearing in a regular expression are assigned numbers 1 through 9
258 in the order that the open parentheses appear in the regular
259 expression. So you can use `\1' through `\9' to refer to the text
260 matched by the corresponding `\( ... \)' constructs.
262 For example, `\(.*\)\1' matches any newline-free string that is
263 composed of two identical halves. The `\(.*\)' matches the first
264 half, which may be anything, but the `\1' that follows must match
268 is called a "shy" grouping operator, and it is used just like `\(
269 ... \)', except that it does not cause the matched substring to be
270 recorded for future reference.
272 This is useful when you need a lot of grouping `\( ... \)'
273 constructs, but only want to remember one or two - or if you have
274 more than nine groupings and need to use backreferences to refer to
275 the groupings at the end.
277 Using `\(?: ... \)' rather than `\( ... \)' when you don't need
278 the captured substrings ought to speed up your programs some,
279 since it shortens the code path followed by the regular expression
280 engine, as well as the amount of memory allocation and string
281 copying it must do. The actual performance gain to be observed
282 has not been measured or quantified as of this writing.
284 The shy grouping operator has been borrowed from Perl, and has not
285 been available prior to XEmacs 20.3, nor is it available in FSF
289 matches any word-constituent character. The editor syntax table
290 determines which characters these are. *Note Syntax::.
293 matches any character that is not a word constituent.
296 matches any character whose syntax is CODE. Here CODE is a
297 character that represents a syntax code: thus, `w' for word
298 constituent, `-' for whitespace, `(' for open parenthesis, etc.
299 *Note Syntax::, for a list of syntax codes and the characters that
303 matches any character whose syntax is not CODE.
305 The following regular expression constructs match the empty
306 string--that is, they don't use up any characters--but whether they
307 match depends on the context.
310 matches the empty string, but only at the beginning of the buffer
311 or string being matched against.
314 matches the empty string, but only at the end of the buffer or
315 string being matched against.
318 matches the empty string, but only at point. (This construct is
319 not defined when matching against a string.)
322 matches the empty string, but only at the beginning or end of a
323 word. Thus, `\bfoo\b' matches any occurrence of `foo' as a
324 separate word. `\bballs?\b' matches `ball' or `balls' as a
328 matches the empty string, but _not_ at the beginning or end of a
332 matches the empty string, but only at the beginning of a word.
335 matches the empty string, but only at the end of a word.
337 Here is a complicated regexp used by Emacs to recognize the end of a
338 sentence together with any whitespace that follows. It is given in Lisp
339 syntax to enable you to distinguish the spaces from the tab characters.
340 In Lisp syntax, the string constant begins and ends with a
341 double-quote. `\"' stands for a double-quote as part of the regexp,
342 `\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for
345 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
347 This regexp contains four parts: a character set matching period, `?'
348 or `!'; a character set matching close-brackets, quotes or parentheses,
349 repeated any number of times; an alternative in backslash-parentheses
350 that matches end-of-line, a tab or two spaces; and a character set
351 matching whitespace characters, repeated any number of times.
354 File: xemacs.info, Node: Search Case, Next: Replace, Prev: Regexps, Up: Search
359 All searches in Emacs normally ignore the case of the text they are
360 searching through; if you specify searching for `FOO', `Foo' and `foo'
361 are also considered a match. Regexps, and in particular character
362 sets, are included: `[aB]' matches `a' or `A' or `b' or `B'.
364 If you want a case-sensitive search, set the variable
365 `case-fold-search' to `nil'. Then all letters must match exactly,
366 including case. `case-fold-search' is a per-buffer variable; altering
367 it affects only the current buffer, but there is a default value which
368 you can change as well. *Note Locals::. You can also use Case
369 Sensitive Search from the Options menu on your screen.
372 File: xemacs.info, Node: Replace, Next: Other Repeating Search, Prev: Search Case, Up: Search
377 Global search-and-replace operations are not needed as often in
378 Emacs as they are in other editors, but they are available. In
379 addition to the simple `replace-string' command which is like that
380 found in most editors, there is a `query-replace' command which asks
381 you, for each occurrence of a pattern, whether to replace it.
383 The replace commands all replace one string (or regexp) with one
384 replacement string. It is possible to perform several replacements in
385 parallel using the command `expand-region-abbrevs'. *Note Expanding
390 * Unconditional Replace:: Replacing all matches for a string.
391 * Regexp Replace:: Replacing all matches for a regexp.
392 * Replacement and Case:: How replacements preserve case of letters.
393 * Query Replace:: How to use querying.
396 File: xemacs.info, Node: Unconditional Replace, Next: Regexp Replace, Prev: Replace, Up: Replace
398 Unconditional Replacement
399 -------------------------
401 `M-x replace-string <RET> STRING <RET> NEWSTRING <RET>'
402 Replace every occurrence of STRING with NEWSTRING.
404 `M-x replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
405 Replace every match for REGEXP with NEWSTRING.
407 To replace every instance of `foo' after point with `bar', use the
408 command `M-x replace-string' with the two arguments `foo' and `bar'.
409 Replacement occurs only after point: if you want to cover the whole
410 buffer you must go to the beginning first. By default, all occurrences
411 up to the end of the buffer are replaced. To limit replacement to part
412 of the buffer, narrow to that part of the buffer before doing the
413 replacement (*note Narrowing::).
415 When `replace-string' exits, point is left at the last occurrence
416 replaced. The value of point when the `replace-string' command was
417 issued is remembered on the mark ring; `C-u C-<SPC>' moves back there.
419 A numeric argument restricts replacement to matches that are
420 surrounded by word boundaries.
423 File: xemacs.info, Node: Regexp Replace, Next: Replacement and Case, Prev: Unconditional Replace, Up: Replace
428 `replace-string' replaces exact matches for a single string. The
429 similar command `replace-regexp' replaces any match for a specified
432 In `replace-regexp', the NEWSTRING need not be constant. It can
433 refer to all or part of what is matched by the REGEXP. `\&' in
434 NEWSTRING stands for the entire text being replaced. `\D' in
435 NEWSTRING, where D is a digit, stands for whatever matched the D'th
436 parenthesized grouping in REGEXP. For example,
438 M-x replace-regexp <RET> c[ad]+r <RET> \&-safe <RET>
440 would replace (for example) `cadr' with `cadr-safe' and `cddr' with
443 M-x replace-regexp <RET> \(c[ad]+r\)-safe <RET> \1 <RET>
445 would perform exactly the opposite replacements. To include a `\' in
446 the text to replace with, you must give `\\'.
449 File: xemacs.info, Node: Replacement and Case, Next: Query Replace, Prev: Regexp Replace, Up: Replace
451 Replace Commands and Case
452 -------------------------
454 If the arguments to a replace command are in lower case, the command
455 preserves case when it makes a replacement. Thus, the following
458 M-x replace-string <RET> foo <RET> bar <RET>
460 replaces a lower-case `foo' with a lower case `bar', `FOO' with `BAR',
461 and `Foo' with `Bar'. If upper-case letters are used in the second
462 argument, they remain upper-case every time that argument is inserted.
463 If upper-case letters are used in the first argument, the second
464 argument is always substituted exactly as given, with no case
465 conversion. Likewise, if the variable `case-replace' is set to `nil',
466 replacement is done without case conversion. If `case-fold-search' is
467 set to `nil', case is significant in matching occurrences of `foo' to
468 replace; also, case conversion of the replacement string is not done.
471 File: xemacs.info, Node: Query Replace, Prev: Replacement and Case, Up: Replace
476 `M-% STRING <RET> NEWSTRING <RET>'
477 `M-x query-replace <RET> STRING <RET> NEWSTRING <RET>'
478 Replace some occurrences of STRING with NEWSTRING.
480 `M-x query-replace-regexp <RET> REGEXP <RET> NEWSTRING <RET>'
481 Replace some matches for REGEXP with NEWSTRING.
483 If you want to change only some of the occurrences of `foo' to
484 `bar', not all of them, you can use `query-replace' instead of `M-%'.
485 This command finds occurrences of `foo' one by one, displays each
486 occurrence, and asks you whether to replace it. A numeric argument to
487 `query-replace' tells it to consider only occurrences that are bounded
488 by word-delimiter characters.
490 Aside from querying, `query-replace' works just like
491 `replace-string', and `query-replace-regexp' works just like
494 The things you can type when you are shown an occurrence of STRING
495 or a match for REGEXP are:
498 to replace the occurrence with NEWSTRING. This preserves case,
499 just like `replace-string', provided `case-replace' is non-`nil',
503 to skip to the next occurrence without replacing this one.
506 to replace this occurrence and display the result. You are then
507 prompted for another input character. However, since the
508 replacement has already been made, <DEL> and <SPC> are equivalent.
509 At this point, you can type `C-r' (see below) to alter the
510 replaced text. To undo the replacement, you can type `C-x u'.
511 This exits the `query-replace'. If you want to do further
512 replacement you must use `C-x ESC' to restart (*note Repetition::).
515 to exit without doing any more replacements.
518 to replace this occurrence and then exit.
521 to replace all remaining occurrences without asking again.
524 to go back to the location of the previous occurrence (or what
525 used to be an occurrence), in case you changed it by mistake.
526 This works by popping the mark ring. Only one `^' in a row is
527 allowed, because only one previous replacement location is kept
528 during `query-replace'.
531 to enter a recursive editing level, in case the occurrence needs
532 to be edited rather than just replaced with NEWSTRING. When you
533 are done, exit the recursive editing level with `C-M-c' and the
534 next occurrence will be displayed. *Note Recursive Edit::.
537 to delete the occurrence, and then enter a recursive editing level
538 as in `C-r'. Use the recursive edit to insert text to replace the
539 deleted occurrence of STRING. When done, exit the recursive
540 editing level with `C-M-c' and the next occurrence will be
544 to redisplay the screen and then give another answer.
547 to display a message summarizing these options, then give another
550 If you type any other character, Emacs exits the `query-replace', and
551 executes the character as a command. To restart the `query-replace',
552 use `C-x <ESC>', which repeats the `query-replace' because it used the
553 minibuffer to read its arguments. *Note C-x ESC: Repetition.
556 File: xemacs.info, Node: Other Repeating Search, Prev: Replace, Up: Search
558 Other Search-and-Loop Commands
559 ==============================
561 Here are some other commands that find matches for a regular
562 expression. They all operate from point to the end of the buffer.
565 Print each line that follows point and contains a match for the
566 specified regexp. A numeric argument specifies the number of
567 context lines to print before and after each matching line; the
570 The buffer `*Occur*' containing the output serves as a menu for
571 finding occurrences in their original context. Find an occurrence
572 as listed in `*Occur*', position point there, and type `C-c C-c';
573 this switches to the buffer that was searched and moves point to
574 the original of the same occurrence.
576 `M-x list-matching-lines'
577 Synonym for `M-x occur'.
580 Print the number of matches following point for the specified
583 `M-x delete-non-matching-lines'
584 Delete each line that follows point and does not contain a match
585 for the specified regexp.
587 `M-x delete-matching-lines'
588 Delete each line that follows point and contains a match for the
592 File: xemacs.info, Node: Fixit, Next: Files, Prev: Search, Up: Top
594 Commands for Fixing Typos
595 *************************
597 This chapter describes commands that are especially useful when you
598 catch a mistake in your text just after you have made it, or when you
599 change your mind while composing text on line.
603 * Kill Errors:: Commands to kill a batch of recently entered text.
604 * Transpose:: Exchanging two characters, words, lines, lists...
605 * Fixing Case:: Correcting case of last word entered.
606 * Spelling:: Apply spelling checker to a word, or a whole file.
609 File: xemacs.info, Node: Kill Errors, Next: Transpose, Prev: Fixit, Up: Fixit
611 Killing Your Mistakes
612 =====================
615 Delete last character (`delete-backward-char').
618 Kill last word (`backward-kill-word').
621 Kill to beginning of sentence (`backward-kill-sentence').
623 The <DEL> character (`delete-backward-char') is the most important
624 correction command. When used among graphic (self-inserting)
625 characters, it can be thought of as canceling the last character typed.
627 When your mistake is longer than a couple of characters, it might be
628 more convenient to use `M-<DEL>' or `C-x <DEL>'. `M-<DEL>' kills back
629 to the start of the last word, and `C-x <DEL>' kills back to the start
630 of the last sentence. `C-x <DEL>' is particularly useful when you are
631 thinking of what to write as you type it, in case you change your mind
632 about phrasing. `M-<DEL>' and `C-x <DEL>' save the killed text for
633 `C-y' and `M-y' to retrieve. *Note Yanking::.
635 `M-<DEL>' is often useful even when you have typed only a few
636 characters wrong, if you know you are confused in your typing and aren't
637 sure exactly what you typed. At such a time, you cannot correct with
638 <DEL> except by looking at the screen to see what you did. It requires
639 less thought to kill the whole word and start over.
642 File: xemacs.info, Node: Transpose, Next: Fixing Case, Prev: Kill Errors, Up: Fixit
648 Transpose two characters (`transpose-chars').
651 Transpose two words (`transpose-words').
654 Transpose two balanced expressions (`transpose-sexps').
657 Transpose two lines (`transpose-lines').
659 The common error of transposing two adjacent characters can be fixed
660 with the `C-t' command (`transpose-chars'). Normally, `C-t' transposes
661 the two characters on either side of point. When given at the end of a
662 line, `C-t' transposes the last two characters on the line, rather than
663 transposing the last character of the line with the newline, which
664 would be useless. If you catch a transposition error right away, you
665 can fix it with just `C-t'. If you catch the error later, move the
666 cursor back to between the two transposed characters. If you
667 transposed a space with the last character of the word before it, the
668 word motion commands are a good way of getting there. Otherwise, a
669 reverse search (`C-r') is often the best way. *Note Search::.
671 `Meta-t' (`transpose-words') transposes the word before point with
672 the word after point. It moves point forward over a word, dragging the
673 word preceding or containing point forward as well. The punctuation
674 characters between the words do not move. For example, `FOO, BAR'
675 transposes into `BAR, FOO' rather than `BAR FOO,'.
677 `C-M-t' (`transpose-sexps') is a similar command for transposing two
678 expressions (*note Lists::), and `C-x C-t' (`transpose-lines')
679 exchanges lines. It works like `M-t' but in determines the division of
680 the text into syntactic units differently.
682 A numeric argument to a transpose command serves as a repeat count:
683 it tells the transpose command to move the character (word, sexp, line)
684 before or containing point across several other characters (words,
685 sexps, lines). For example, `C-u 3 C-t' moves the character before
686 point forward across three other characters. This is equivalent to
687 repeating `C-t' three times. `C-u - 4 M-t' moves the word before point
688 backward across four words. `C-u - C-M-t' would cancel the effect of
691 A numeric argument of zero transposes the character (word, sexp,
692 line) ending after point with the one ending after the mark (otherwise a
693 command with a repeat count of zero would do nothing).
696 File: xemacs.info, Node: Fixing Case, Next: Spelling, Prev: Transpose, Up: Fixit
702 Convert last word to lower case. Note that `Meta--' is
706 Convert last word to all upper case.
709 Convert last word to lower case with capital initial.
711 A common error is to type words in the wrong case. Because of this,
712 the word case-conversion commands `M-l', `M-u', and `M-c' do not move
713 the cursor when used with a negative argument. As soon as you see you
714 have mistyped the last word, you can simply case-convert it and
715 continue typing. *Note Case::.
718 File: xemacs.info, Node: Spelling, Prev: Fixing Case, Up: Fixit
720 Checking and Correcting Spelling
721 ================================
724 Check and correct spelling of word (`spell-word').
727 Check and correct spelling of each word in the buffer.
730 Check and correct spelling of each word in the region.
733 Check spelling of specified word.
735 To check the spelling of the word before point, and optionally
736 correct it, use the command `M-$' (`spell-word'). This command runs an
737 inferior process containing the `spell' program to see whether the word
738 is correct English. If it is not, it asks you to edit the word (in the
739 minibuffer) into a corrected spelling, and then performs a
740 `query-replace' to substitute the corrected spelling for the old one
741 throughout the buffer.
743 If you exit the minibuffer without altering the original spelling, it
744 means you do not want to do anything to that word. In that case, the
745 `query-replace' is not done.
747 `M-x spell-buffer' checks each word in the buffer the same way that
748 `spell-word' does, doing a `query-replace' for every incorrect word if
751 `M-x spell-region' is similar to `spell-buffer' but operates only on
752 the region, not the entire buffer.
754 `M-x spell-string' reads a string as an argument and checks whether
755 that is a correctly spelled English word. It prints a message giving
756 the answer in the echo area.
759 File: xemacs.info, Node: Files, Next: Buffers, Prev: Fixit, Up: Top
764 The basic unit of stored data in Unix is the "file". To edit a file,
765 you must tell Emacs to examine the file and prepare a buffer containing
766 a copy of the file's text. This is called "visiting" the file. Editing
767 commands apply directly to text in the buffer; that is, to the copy
768 inside Emacs. Your changes appear in the file itself only when you
769 "save" the buffer back into the file.
771 In addition to visiting and saving files, Emacs can delete, copy,
772 rename, and append to files, and operate on file directories.
776 * File Names:: How to type and edit file name arguments.
777 * Visiting:: Visiting a file prepares Emacs to edit the file.
778 * Saving:: Saving makes your changes permanent.
779 * Reverting:: Reverting cancels all the changes not saved.
780 * Auto Save:: Auto Save periodically protects against loss of data.
781 * Version Control:: Version control systems (RCS and SCCS).
782 * ListDir:: Listing the contents of a file directory.
783 * Comparing Files:: Finding where two files differ.
784 * Dired:: ``Editing'' a directory to delete, rename, etc.
786 * Misc File Ops:: Other things you can do on files.
789 File: xemacs.info, Node: File Names, Next: Visiting, Prev: Files, Up: Files
794 Most Emacs commands that operate on a file require you to specify the
795 file name. (Saving and reverting are exceptions; the buffer knows which
796 file name to use for them.) File names are specified in the minibuffer
797 (*note Minibuffer::). "Completion" is available, to make it easier to
798 specify long file names. *Note Completion::.
800 There is always a "default file name" which is used if you enter an
801 empty argument by typing just <RET>. Normally the default file name is
802 the name of the file visited in the current buffer; this makes it easy
803 to operate on that file with any of the Emacs file commands.
805 Each buffer has a default directory, normally the same as the
806 directory of the file visited in that buffer. When Emacs reads a file
807 name, the default directory is used if you do not specify a directory.
808 If you specify a directory in a relative fashion, with a name that does
809 not start with a slash, it is interpreted with respect to the default
810 directory. The default directory of the current buffer is kept in the
811 variable `default-directory', which has a separate value in every
812 buffer. The value of the variable should end with a slash.
814 For example, if the default file name is `/u/rms/gnu/gnu.tasks' then
815 the default directory is `/u/rms/gnu/'. If you type just `foo', which
816 does not specify a directory, it is short for `/u/rms/gnu/foo'.
817 `../.login' would stand for `/u/rms/.login'. `new/foo' would stand for
818 the filename `/u/rms/gnu/new/foo'.
820 The variable `default-directory-alist' takes an alist of major modes
821 and their opinions on `default-directory' as a Lisp expression to
822 evaluate. A resulting value of `nil' is ignored in favor of
825 You can create a new directory with the function `make-directory',
826 which takes as an argument a file name string. The current directory is
827 displayed in the minibuffer when the function is called; you can delete
828 the old directory name and supply a new directory name. For example, if
829 the current directory is `/u/rms/gnu', you can delete `gnu' and type
830 `oryx' and <RET> to create `/u/rms/oryx'. Removing a directory is
831 similar to creating one. To remove a directory, use
832 `remove-directory'; it takes one argument, a file name string.
834 The command `M-x pwd' prints the current buffer's default directory,
835 and the command `M-x cd' sets it (to a value read using the
836 minibuffer). A buffer's default directory changes only when the `cd'
837 command is used. A file-visiting buffer's default directory is
838 initialized to the directory of the file that is visited there. If a
839 buffer is created with `C-x b', its default directory is copied from
840 that of the buffer that was current at the time.
842 The default directory name actually appears in the minibuffer when
843 the minibuffer becomes active to read a file name. This serves two
844 purposes: it shows you what the default is, so that you can type a
845 relative file name and know with certainty what it will mean, and it
846 allows you to edit the default to specify a different directory. To
847 inhibit the insertion of the default directory, set the variable
848 `insert-default-directory' to `nil'.
850 Note that it is legitimate to type an absolute file name after you
851 enter the minibuffer, ignoring the presence of the default directory
852 name. The final minibuffer contents may look invalid, but that is not
853 so. *Note Minibuffer File::.
855 `$' in a file name is used to substitute environment variables. For
856 example, if you have used the shell command `setenv FOO rms/hacks' to
857 set up an environment variable named `FOO', then you can use
858 `/u/$FOO/test.c' or `/u/${FOO}/test.c' as an abbreviation for
859 `/u/rms/hacks/test.c'. The environment variable name consists of all
860 the alphanumeric characters after the `$'; alternatively, it may be
861 enclosed in braces after the `$'. Note that the `setenv' command
862 affects Emacs only if done before Emacs is started.
864 To access a file with `$' in its name, type `$$'. This pair is
865 converted to a single `$' at the same time variable substitution is
866 performed for single `$'. The Lisp function that performs the
867 substitution is called `substitute-in-file-name'. The substitution is
868 performed only on filenames read as such using the minibuffer.
871 File: xemacs.info, Node: Visiting, Next: Saving, Prev: File Names, Up: Files
877 Visit a file (`find-file').
880 Visit a different file instead of the one visited last
881 (`find-alternate-file').
884 Visit a file, in another window (`find-file-other-window'). Don't
888 Visit a file, in another frame (`find-file-other-frame'). Don't
889 change this window or frame.
891 "Visiting" a file means copying its contents into an Emacs buffer so
892 you can edit it. Emacs creates a new buffer for each file you visit.
893 We say that the buffer is visiting the file that it was created to
894 hold. Emacs constructs the buffer name from the file name by throwing
895 away the directory and keeping just the file name. For example, a file
896 named `/usr/rms/emacs.tex' is displayed in a buffer named `emacs.tex'.
897 If a buffer with that name exists, a unique name is constructed by
898 appending `<2>', `<3>',and so on, using the lowest number that makes a
899 name that is not already in use.
901 Each window's mode line shows the name of the buffer that is being
902 displayed in that window, so you can always tell what buffer you are
905 The changes you make with Emacs are made in the Emacs buffer. They
906 do not take effect in the file that you visit, or any other permanent
907 place, until you "save" the buffer. Saving the buffer means that Emacs
908 writes the current contents of the buffer into its visited file. *Note
911 If a buffer contains changes that have not been saved, the buffer is
912 said to be "modified". This is important because it implies that some
913 changes will be lost if the buffer is not saved. The mode line displays
914 two stars near the left margin if the buffer is modified.
916 To visit a file, use the command `C-x C-f' (`find-file'). Follow
917 the command with the name of the file you wish to visit, terminated by a
918 <RET>. If you are using XEmacs under X, you can also use the Open...
919 command from the File menu bar item.
921 The file name is read using the minibuffer (*note Minibuffer::), with
922 defaulting and completion in the standard manner (*note File Names::).
923 While in the minibuffer, you can abort `C-x C-f' by typing `C-g'.
925 `C-x C-f' has completed successfully when text appears on the screen
926 and a new buffer name appears in the mode line. If the specified file
927 does not exist and could not be created or cannot be read, an error
928 results. The error message is printed in the echo area, and includes
929 the name of the file that Emacs was trying to visit.
931 If you visit a file that is already in Emacs, `C-x C-f' does not make
932 another copy. It selects the existing buffer containing that file.
933 However, before doing so, it checks that the file itself has not changed
934 since you visited or saved it last. If the file has changed, Emacs
935 prints a warning message. *Note Simultaneous Editing: Interlocking.
937 You can switch to a specific file called out in the current buffer by
938 calling the function `find-this-file'. By providing a prefix argument,
939 this function calls `filename-at-point' and switches to a buffer
940 visiting the file FILENAME. It creates one if none already exists. You
941 can use this function to edit the file mentioned in the buffer you are
942 working in or to test if the file exists. You can do that by using the
943 minibuffer completion after snatching the all or part of the filename.
945 If the variable `find-file-use-truenames''s value is non-`nil', a
946 buffer's visited filename will always be traced back to the real file.
947 The filename will never be a symbolic link, and there will never be a
948 symbolic link anywhere in its directory path. In other words, the
949 `buffer-file-name' and `buffer-file-truename' will be equal.
951 If the variable `find-file-compare-truenames' value is non-`nil',
952 the `find-file' command will check the `buffer-file-truename' of all
953 visited files when deciding whether a given file is already in a
954 buffer, instead of just `buffer-file-name'. If you attempt to visit
955 another file which is a symbolic link to a file that is already in a
956 buffer, the existing buffer will be found instead of a newly created
957 one. This works if any component of the pathname (including a
958 non-terminal component) is a symbolic link as well, but doesn't work
959 with hard links (nothing does).
961 If you want to create a file, just visit it. Emacs prints `(New
962 File)' in the echo area, but in other respects behaves as if you had
963 visited an existing empty file. If you make any changes and save them,
966 If you visit a nonexistent file unintentionally (because you typed
967 the wrong file name), use the `C-x C-v' (`find-alternate-file') command
968 to visit the file you wanted. `C-x C-v' is similar to `C-x C-f', but
969 it kills the current buffer (after first offering to save it if it is
970 modified). `C-x C-v' is allowed even if the current buffer is not
973 If the file you specify is actually a directory, Dired is called on
974 that directory (*note Dired::). To inhibit this, set the variable
975 `find-file-run-dired' to `nil'; then it is an error to try to visit a
978 `C-x 4 f' (`find-file-other-window') is like `C-x C-f' except that
979 the buffer containing the specified file is selected in another window.
980 The window that was selected before `C-x 4 f' continues to show the
981 same buffer it was already showing. If you use this command when only
982 one window is being displayed, that window is split in two, with one
983 window showing the same buffer as before, and the other one showing the
984 newly requested file. *Note Windows::.
986 `C-x 5 C-f' (`find-file-other-frame') is like `C-x C-f' except that
987 it creates a new frame in which the file is displayed.
989 Use the function `find-this-file-other-window' to edit a file
990 mentioned in the buffer you are editing or to test if that file exists.
991 To do this, use the minibuffer completion after snatching the part or
992 all of the filename. By providing a prefix argument, the function calls
993 `filename-at-point' and switches you to a buffer visiting the file
994 FILENAME in another window. The function creates a buffer if none
995 already exists. This function is similar to `find-file-other-window'.
997 There are two hook variables that allow extensions to modify the
998 operation of visiting files. Visiting a file that does not exist runs
999 the functions in the list `find-file-not-found-hooks'; the value of this
1000 variable is expected to be a list of functions which are called one by
1001 one until one of them returns non-`nil'. Any visiting of a file,
1002 whether extant or not, expects `find-file-hooks' to contain list of
1003 functions and calls them all, one by one. In both cases the functions
1004 receive no arguments. Visiting a nonexistent file runs the
1005 `find-file-not-found-hooks' first.
1008 File: xemacs.info, Node: Saving, Next: Reverting, Prev: Visiting, Up: Files
1013 "Saving" a buffer in Emacs means writing its contents back into the
1014 file that was visited in the buffer.
1017 Save the current buffer in its visited file (`save-buffer').
1020 Save any or all buffers in their visited files
1021 (`save-some-buffers').
1024 Forget that the current buffer has been changed (`not-modified').
1027 Save the current buffer in a specified file, and record that file
1028 as the one visited in the buffer (`write-file').
1030 `M-x set-visited-file-name'
1031 Change file the name under which the current buffer will be saved.
1033 To save a file and make your changes permanent, type `C-x C-s'
1034 (`save-buffer'). After saving is finished, `C-x C-s' prints a message
1037 Wrote /u/rms/gnu/gnu.tasks
1039 If the selected buffer is not modified (no changes have been made in it
1040 since the buffer was created or last saved), Emacs does not save it
1041 because it would have no effect. Instead, `C-x C-s' prints a message
1042 in the echo area saying:
1044 (No changes need to be saved)
1046 The command `C-x s' (`save-some-buffers') can save any or all
1047 modified buffers. First it asks, for each modified buffer, whether to
1048 save it. The questions should be answered with `y' or `n'. `C-x C-c',
1049 the key that kills Emacs, invokes `save-some-buffers' and therefore
1050 asks the same questions.
1052 If you have changed a buffer and do not want the changes to be saved,
1053 you should take some action to prevent it. Otherwise, you are liable to
1054 save it by mistake each time you use `save-some-buffers' or a related
1055 command. One thing you can do is type `M-~' (`not-modified'), which
1056 removes the indication that the buffer is modified. If you do this,
1057 none of the save commands will believe that the buffer needs to be
1058 saved. (`~' is often used as a mathematical symbol for `not'; thus
1059 `Meta-~' is `not', metafied.) You could also use
1060 `set-visited-file-name' (see below) to mark the buffer as visiting a
1061 different file name, not in use for anything important.
1063 You can also undo all the changes made since the file was visited or
1064 saved, by reading the text from the file again. This is called
1065 "reverting". *Note Reverting::. Alternatively, you can undo all the
1066 changes by repeating the undo command `C-x u'; but this only works if
1067 you have not made more changes than the undo mechanism can remember.
1069 `M-x set-visited-file-name' alters the name of the file that the
1070 current buffer is visiting. It prompts you for the new file name in the
1071 minibuffer. You can also use `set-visited-file-name' on a buffer that
1072 is not visiting a file. The buffer's name is changed to correspond to
1073 the file it is now visiting unless the new name is already used by a
1074 different buffer; in that case, the buffer name is not changed.
1075 `set-visited-file-name' does not save the buffer in the newly visited
1076 file; it just alters the records inside Emacs so that it will save the
1077 buffer in that file. It also marks the buffer as "modified" so that
1078 `C-x C-s' will save.
1080 If you wish to mark a buffer as visiting a different file and save it
1081 right away, use `C-x C-w' (`write-file'). It is precisely equivalent
1082 to `set-visited-file-name' followed by `C-x C-s'. `C-x C-s' used on a
1083 buffer that is not visiting a file has the same effect as `C-x C-w';
1084 that is, it reads a file name, marks the buffer as visiting that file,
1085 and saves it there. The default file name in a buffer that is not
1086 visiting a file is made by combining the buffer name with the buffer's
1089 If Emacs is about to save a file and sees that the date of the latest
1090 version on disk does not match what Emacs last read or wrote, Emacs
1091 notifies you of this fact, because it probably indicates a problem
1092 caused by simultaneous editing and requires your immediate attention.
1093 *Note Simultaneous Editing: Interlocking.
1095 If the variable `require-final-newline' is non-`nil', Emacs puts a
1096 newline at the end of any file that doesn't already end in one, every
1097 time a file is saved or written.
1099 Use the hook variable `write-file-hooks' to implement other ways to
1100 write files, and specify things to be done before files are written.
1101 The value of this variable should be a list of Lisp functions. When a
1102 file is to be written, the functions in the list are called, one by
1103 one, with no arguments. If one of them returns a non-`nil' value, Emacs
1104 takes this to mean that the file has been written in some suitable
1105 fashion; the rest of the functions are not called, and normal writing is
1106 not done. Use the hook variable `after-save-hook' to list all the
1107 functions to be called after writing out a buffer to a file.
1111 * Backup:: How Emacs saves the old version of your file.
1112 * Interlocking:: How Emacs protects against simultaneous editing
1113 of one file by two users.
1116 File: xemacs.info, Node: Backup, Next: Interlocking, Prev: Saving, Up: Saving
1121 Because Unix does not provide version numbers in file names,
1122 rewriting a file in Unix automatically destroys all record of what the
1123 file used to contain. Thus, saving a file from Emacs throws away the
1124 old contents of the file--or it would, except that Emacs carefully
1125 copies the old contents to another file, called the "backup" file,
1126 before actually saving. (Make sure that the variable
1127 `make-backup-files' is non-`nil'. Backup files are not written if this
1130 At your option, Emacs can keep either a single backup file or a
1131 series of numbered backup files for each file you edit.
1133 Emacs makes a backup for a file only the first time a file is saved
1134 from one buffer. No matter how many times you save a file, its backup
1135 file continues to contain the contents from before the file was visited.
1136 Normally this means that the backup file contains the contents from
1137 before the current editing session; however, if you kill the buffer and
1138 then visit the file again, a new backup file is made by the next save.
1142 * Names: Backup Names. How backup files are named;
1143 Choosing single or numbered backup files.
1144 * Deletion: Backup Deletion. Emacs deletes excess numbered backups.
1145 * Copying: Backup Copying. Backups can be made by copying or renaming.
1148 File: xemacs.info, Node: Backup Names, Next: Backup Deletion, Prev: Backup, Up: Backup
1150 Single or Numbered Backups
1151 ..........................
1153 If you choose to have a single backup file (the default), the backup
1154 file's name is constructed by appending `~' to the file name being
1155 edited; thus, the backup file for `eval.c' is `eval.c~'.
1157 If you choose to have a series of numbered backup files, backup file
1158 names are made by appending `.~', the number, and another `~' to the
1159 original file name. Thus, the backup files of `eval.c' would be called
1160 `eval.c.~1~', `eval.c.~2~', and so on, through names like
1161 `eval.c.~259~' and beyond.
1163 If protection stops you from writing backup files under the usual
1164 names, the backup file is written as `%backup%~' in your home directory.
1165 Only one such file can exist, so only the most recently made backup is
1168 The choice of single backup or numbered backups is controlled by the
1169 variable `version-control'. Its possible values are:
1172 Make numbered backups.
1175 Make numbered backups for files that have numbered backups already.
1176 Otherwise, make single backups.
1179 Never make numbered backups; always make single backups.
1181 `version-control' may be set locally in an individual buffer to control
1182 the making of backups for that buffer's file. For example, Rmail mode
1183 locally sets `version-control' to `never' to make sure that there is
1184 only one backup for an Rmail file. *Note Locals::.