![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to emacs-7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / GNUtools / emacs / info|
Return to emacs-7 CVS log | Up to [Apple XNU] / GNUtools / emacs / info |
1.1 root 1: This is Info file ../info/emacs, produced by Makeinfo-1.49 from the
2: input file emacs.texi.
3:
4: This file documents the GNU Emacs editor.
5:
6: Copyright (C) 1985, 1986, 1988, 1992 Richard M. Stallman.
7:
8: Permission is granted to make and distribute verbatim copies of this
9: manual provided the copyright notice and this permission notice are
10: preserved on all copies.
11:
12: Permission is granted to copy and distribute modified versions of
13: this manual under the conditions for verbatim copying, provided also
14: that the sections entitled "The GNU Manifesto", "Distribution" and "GNU
15: General Public License" are included exactly as in the original, and
16: provided that the entire resulting derived work is distributed under the
17: terms of a permission notice identical to this one.
18:
19: Permission is granted to copy and distribute translations of this
20: manual into another language, under the above conditions for modified
21: versions, except that the sections entitled "The GNU Manifesto",
22: "Distribution" and "GNU General Public License" may be included in a
23: translation approved by the author instead of in the original English.
24:
25:
26: File: emacs, Node: Words, Next: Sentences, Prev: Text Mode, Up: Text
27:
28: Words
29: =====
30:
31: Emacs has commands for moving over or operating on words. By
32: convention, the keys for them are all `Meta-' characters.
33:
34: `M-f'
35: Move forward over a word (`forward-word').
36:
37: `M-b'
38: Move backward over a word (`backward-word').
39:
40: `M-d'
41: Kill up to the end of a word (`kill-word').
42:
43: `M-DEL'
44: Kill back to the beginning of a word (`backward-kill-word').
45:
46: `M-@'
47: Mark the end of the next word (`mark-word').
48:
49: `M-t'
50: Transpose two words; drag a word forward or backward across other
51: words (`transpose-words').
52:
53: Notice how these keys form a series that parallels the
54: character-based `C-f', `C-b', `C-d', `C-t' and DEL. `M-@' is related
55: to `C-@', which is an alias for `C-SPC'.
56:
57: The commands `Meta-f' (`forward-word') and `Meta-b'
58: (`backward-word') move forward and backward over words. They are thus
59: analogous to `Control-f' and `Control-b', which move over single
60: characters. Like their `Control-' analogues, `Meta-f' and `Meta-b'
61: move several words if given an argument. `Meta-f' with a negative
62: argument moves backward, and `Meta-b' with a negative argument moves
63: forward. Forward motion stops right after the last letter of the word,
64: while backward motion stops right before the first letter.
65:
66: `Meta-d' (`kill-word') kills the word after point. To be precise,
67: it kills everything from point to the place `Meta-f' would move to.
68: Thus, if point is in the middle of a word, `Meta-d' kills just the part
69: after point. If some punctuation comes between point and the next
70: word, it is killed along with the word. (If you wish to kill only the
71: next word but not the punctuation before it, simply do `Meta-f' to get
72: the end, and kill the word backwards with `Meta-DEL'.) `Meta-d' takes
73: arguments just like `Meta-f'.
74:
75: `Meta-DEL' (`backward-kill-word') kills the word before point. It
76: kills everything from point back to where `Meta-b' would move to. If
77: point is after the space in `FOO, BAR', then `FOO, ' is killed. (If
78: you wish to kill just `FOO', do `Meta-b Meta-d' instead of `Meta-DEL'.)
79:
80: `Meta-t' (`transpose-words') exchanges the word before or containing
81: point with the following word. The delimiter characters between the
82: words do not move. For example, `FOO, BAR' transposes into `BAR, FOO'
83: rather than `BAR FOO,'. *Note Transpose::, for more on transposition
84: and on arguments to transposition commands.
85:
86: To operate on the next N words with an operation which applies
87: between point and mark, you can either set the mark at point and then
88: move over the words, or you can use the command `Meta-@' (`mark-word')
89: which does not move point, but sets the mark where `Meta-f' would move
90: to. It can be given arguments just like `Meta-f'.
91:
92: The word commands' understanding of syntax is completely controlled
93: by the syntax table. Any character can, for example, be declared to be
94: a word delimiter. *Note Syntax::.
95:
96:
97: File: emacs, Node: Sentences, Next: Paragraphs, Prev: Words, Up: Text
98:
99: Sentences
100: =========
101:
102: The Emacs commands for manipulating sentences and paragraphs are
103: mostly on `Meta-' keys, so as to be like the word-handling commands.
104:
105: `M-a'
106: Move back to the beginning of the sentence
107: (`backward-sentence').
108:
109: `M-e'
110: Move forward to the end of the sentence (`forward-sentence').
111:
112: `M-k'
113: Kill forward to the end of the sentence (`kill-sentence').
114:
115: `C-x DEL'
116: Kill back to the beginning of the sentence
117: (`backward-kill-sentence').
118:
119: The commands `Meta-a' and `Meta-e' (`backward-sentence' and
120: `forward-sentence') move to the beginning and end of the current
121: sentence, respectively. They were chosen to resemble `Control-a' and
122: `Control-e', which move to the beginning and end of a line. Unlike
123: them, `Meta-a' and `Meta-e' if repeated or given numeric arguments move
124: over successive sentences. Emacs assumes that the typist's convention
125: is followed, and thus considers a sentence to end wherever there is a
126: `.', `?' or `!' followed by the end of a line or two spaces, with any
127: number of `)', `]', `'', or `"' characters allowed in between. A
128: sentence also begins or ends wherever a paragraph begins or ends.
129:
130: Neither `M-a' nor `M-e' moves past the newline or spaces beyond the
131: sentence edge at which it is stopping.
132:
133: Just as `C-a' and `C-e' have a kill command, `C-k', to go with them,
134: so `M-a' and `M-e' have a corresponding kill command `M-k'
135: (`kill-sentence') which kills from point to the end of the sentence.
136: With minus one as an argument it kills back to the beginning of the
137: sentence. Larger arguments serve as a repeat count.
138:
139: There is a special command, `C-x DEL' (`backward-kill-sentence') for
140: killing back to the beginning of a sentence, because this is useful
141: when you change your mind in the middle of composing text.
142:
143: The variable `sentence-end' controls recognition of the end of a
144: sentence. It is a regexp that matches the last few characters of a
145: sentence, together with the whitespace following the sentence. Its
146: normal value is
147:
148: "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
149:
150: This example is explained in the section on regexps. *Note Regexps::.
151:
152:
153: File: emacs, Node: Paragraphs, Next: Pages, Prev: Sentences, Up: Text
154:
155: Paragraphs
156: ==========
157:
158: The Emacs commands for manipulating paragraphs are also `Meta-' keys.
159:
160: `M-['
161: Move back to previous paragraph beginning
162: (`backward-paragraph').
163:
164: `M-]'
165: Move forward to next paragraph end (`forward-paragraph').
166:
167: `M-h'
168: Put point and mark around this or next paragraph
169: (`mark-paragraph').
170:
171: `Meta-[' moves to the beginning of the current or previous paragraph,
172: while `Meta-]' moves to the end of the current or next paragraph. Blank
173: lines and text formatter command lines separate paragraphs and are not
174: part of any paragraph. Also, an indented line starts a new paragraph.
175:
176: In major modes for programs (as opposed to Text mode), paragraphs
177: begin and end only at blank lines. This makes the paragraph commands
178: continue to be useful even though there are no paragraphs per se.
179:
180: When there is a fill prefix, then paragraphs are delimited by all
181: lines which don't start with the fill prefix. *Note Filling::.
182:
183: When you wish to operate on a paragraph, you can use the command
184: `Meta-h' (`mark-paragraph') to set the region around it. This command
185: puts point at the beginning and mark at the end of the paragraph point
186: was in. If point is between paragraphs (in a run of blank lines, or at
187: a boundary), the paragraph following point is surrounded by point and
188: mark. If there are blank lines preceding the first line of the
189: paragraph, one of these blank lines is included in the region. Thus,
190: for example, `M-h C-w' kills the paragraph around or after point.
191:
192: The precise definition of a paragraph boundary is controlled by the
193: two variables `paragraph-separate' and `paragraph-start'. The value of
194: `paragraph-start' is a regexp that should match any line that either
195: starts or separates paragraphs. The value of `paragraph-separate' is
196: another regexp that should match only lines that separate paragraphs
197: without being part of any paragraph. Lines that start a new paragraph
198: and are contained in it must match both regexps. For example, normally
199: `paragraph-start' is `"^[ \t\n\f]"' and `paragraph-separate' is
200: `"^[ \t\f]*$"'.
201:
202: Normally it is desirable for page boundaries to separate paragraphs.
203: The default values of these variables recognize the usual separator for
204: pages.
205:
206:
207: File: emacs, Node: Pages, Next: Filling, Prev: Paragraphs, Up: Text
208:
209: Pages
210: =====
211:
212: Files are often thought of as divided into "pages" by the "formfeed"
213: character (ASCII Control-L, octal code 014). For example, if a file is
214: printed on a line printer, each page of the file, in this sense, will
215: start on a new page of paper. Emacs treats a page-separator character
216: just like any other character. It can be inserted with `C-q C-l', or
217: deleted with DEL. Thus, you are free to paginate your file or not.
218: However, since pages are often meaningful divisions of the file,
219: commands are provided to move over them and operate on them.
220:
221: `C-x ['
222: Move point to previous page boundary (`backward-page').
223:
224: `C-x ]'
225: Move point to next page boundary (`forward-page').
226:
227: `C-x C-p'
228: Put point and mark around this page (or another page)
229: (`mark-page').
230:
231: `C-x l'
232: Count the lines in this page (`count-lines-page').
233:
234: The `C-x [' (`backward-page') command moves point to immediately
235: after the previous page delimiter. If point is already right after a
236: page delimiter, it skips that one and stops at the previous one. A
237: numeric argument serves as a repeat count. The `C-x ]' (`forward-page')
238: command moves forward past the next page delimiter.
239:
240: The `C-x C-p' command (`mark-page') puts point at the beginning of
241: the current page and the mark at the end. The page delimiter at the end
242: is included (the mark follows it). The page delimiter at the front is
243: excluded (point follows it). This command can be followed by `C-w' to
244: kill a page which is to be moved elsewhere. If it is inserted after a
245: page delimiter, at a place where `C-x ]' or `C-x [' would take you, then
246: the page will be properly delimited before and after once again.
247:
248: A numeric argument to `C-x C-p' is used to specify which page to go
249: to, relative to the current one. Zero means the current page. One
250: means the next page, and -1 means the previous one.
251:
252: The `C-x l' command (`count-lines-page') is good for deciding where
253: to break a page in two. It prints in the echo area the total number of
254: lines in the current page, and then divides it up into those preceding
255: the current line and those following, as in
256:
257: Page has 96 (72+25) lines
258:
259: Notice that the sum is off by one; this is correct if point is not at
260: the beginning of a line.
261:
262: The variable `page-delimiter' should have as its value a regexp that
263: matches the beginning of a line that separates pages. This is what
264: defines where pages begin. The normal value of this variable is
265: `"^\f"', which matches a formfeed character at the beginning of a line.
266:
267:
268: File: emacs, Node: Filling, Next: Case, Prev: Pages, Up: Text
269:
270: Filling Text
271: ============
272:
273: With Auto Fill mode, text can be "filled" (broken up into lines that
274: fit in a specified width) as you insert it. If you alter existing text
275: it may no longer be properly filled; then explicit commands for filling
276: can be used. (Filling is sometimes called "wrapping" in the
277: terminology used for other text editors, but we don't use that term,
278: because it could just as well refer to the continuation of long lines
279: which happens in Emacs if you *don't* fill them.)
280:
281: * Menu:
282:
283: * Auto Fill:: Auto Fill mode breaks long lines automatically.
284: * Fill Commands:: Commands to refill paragraphs and center lines.
285: * Fill Prefix:: Filling when every line is indented or in a comment, etc.
286:
287:
288: File: emacs, Node: Auto Fill, Next: Fill Commands, Prev: Filling, Up: Filling
289:
290: Auto Fill Mode
291: --------------
292:
293: "Auto Fill" mode is a minor mode in which lines are broken
294: automatically when they become too wide. Breaking happens only when
295: you type a SPC or RET.
296:
297: `M-x auto-fill-mode'
298: Enable or disable Auto Fill mode.
299:
300: `SPC'
301: `RET'
302: In Auto Fill mode, break lines when appropriate.
303:
304: `M-x auto-fill-mode' turns Auto Fill mode on if it was off, or off if
305: it was on. With a positive numeric argument it always turns Auto Fill
306: mode on, and with a negative argument always turns it off. You can see
307: when Auto Fill mode is in effect by the presence of the word `Fill' in
308: the mode line, inside the parentheses. Auto Fill mode is a minor mode,
309: turned on or off for each buffer individually. *Note Minor Modes::.
310:
311: In Auto Fill mode, lines are broken automatically at spaces when
312: they get longer than the desired width. Line breaking and
313: rearrangement takes place only when you type SPC or RET. If you wish
314: to insert a space or newline without permitting line-breaking, type
315: `C-q SPC' or `C-q LFD' (recall that a newline is really a linefeed).
316: Also, `C-o' inserts a newline without line breaking.
317:
318: Auto Fill mode works well with Lisp mode, because when it makes a new
319: line in Lisp mode it indents that line with TAB. If a line ending in a
320: comment gets too long, the text of the comment is split into two
321: comment lines. Optionally new comment delimiters are inserted at the
322: end of the first line and the beginning of the second so that each line
323: is a separate comment; the variable `comment-multi-line' controls the
324: choice (*note Comments::.).
325:
326: Auto Fill mode does not refill entire paragraphs. It can break
327: lines but cannot merge lines. So editing in the middle of a paragraph
328: can result in a paragraph that is not correctly filled. The easiest
329: way to make the paragraph properly filled again is usually with the
330: explicit fill commands.
331:
332: Many users like Auto Fill mode and want to use it in all text files.
333: The section on init files says how to arrange this permanently for
334: yourself. *Note Init File::.
335:
336:
337: File: emacs, Node: Fill Commands, Next: Fill Prefix, Prev: Auto Fill, Up: Filling
338:
339: Explicit Fill Commands
340: ----------------------
341:
342: `M-q'
343: Fill current paragraph (`fill-paragraph').
344:
345: `M-g'
346: Fill each paragraph in the region (`fill-region').
347:
348: `C-x f'
349: Set the fill column (`set-fill-column').
350:
351: `M-x fill-region-as-paragraph.'
352: Fill the region, considering it as one paragraph.
353:
354: `M-s'
355: Center a line.
356:
357: To refill a paragraph, use the command `Meta-q' (`fill-paragraph').
358: It causes the paragraph that point is inside, or the one after point if
359: point is between paragraphs, to be refilled. All the line-breaks are
360: removed, and then new ones are inserted where necessary. `M-q' can be
361: undone with `C-_'. *Note Undo::.
362:
363: To refill many paragraphs, use `M-g' (`fill-region'), which divides
364: the region into paragraphs and fills each of them.
365:
366: `Meta-q' and `Meta-g' use the same criteria as `Meta-h' for finding
367: paragraph boundaries (*note Paragraphs::.). For more control, you can
368: use `M-x fill-region-as-paragraph', which refills everything between
369: point and mark. This command recognizes no paragraph separators; it
370: deletes any blank lines found within the region to be filled.
371:
372: A numeric argument to `M-g' or `M-q' causes it to "justify" the text
373: as well as filling it. This means that extra spaces are inserted to
374: make the right margin line up exactly at the fill column. To remove the
375: extra spaces, use `M-q' or `M-g' with no argument.
376:
377: The command `Meta-s' (`center-line') centers the current line within
378: the current fill column. With an argument, it centers several lines
379: individually and moves past them.
380:
381: The maximum line width for filling is in the variable `fill-column'.
382: Altering the value of `fill-column' makes it local to the current
383: buffer; until that time, the default value is in effect. The default is
384: initially 70. *Note Locals::.
385:
386: The easiest way to set `fill-column' is to use the command `C-x f'
387: (`set-fill-column'). With no argument, it sets `fill-column' to the
388: current horizontal position of point. With a numeric argument, it uses
389: that as the new fill column.
390:
391:
392: File: emacs, Node: Fill Prefix, Prev: Fill Commands, Up: Filling
393:
394: The Fill Prefix
395: ---------------
396:
397: To fill a paragraph in which each line starts with a special marker
398: (which might be a few spaces, giving an indented paragraph), use the
399: "fill prefix" feature. The fill prefix is a string which Emacs expects
400: every line to start with, and which is not included in filling.
401:
402: `C-x .'
403: Set the fill prefix (`set-fill-prefix').
404:
405: `M-q'
406: Fill a paragraph using current fill prefix (`fill-paragraph').
407:
408: `M-x fill-individual-paragraphs'
409: Fill the region, considering each change of indentation as
410: starting a new paragraph.
411:
412: To specify a fill prefix, move to a line that starts with the desired
413: prefix, put point at the end of the prefix, and give the command
414: `C-x .' (`set-fill-prefix'). That's a period after the `C-x'. To turn
415: off the fill prefix, specify an empty prefix: type `C-x .' with point
416: at the beginning of a line.
417:
418: When a fill prefix is in effect, the fill commands remove the fill
419: prefix from each line before filling and insert it on each line after
420: filling. The fill prefix is also inserted on new lines made
421: automatically by Auto Fill mode. Lines that do not start with the fill
422: prefix are considered to start paragraphs, both in `M-q' and the
423: paragraph commands; this is just right if you are using paragraphs with
424: hanging indentation (every line indented except the first one). Lines
425: which are blank or indented once the prefix is removed also separate or
426: start paragraphs; this is what you want if you are writing
427: multi-paragraph comments with a comment delimiter on each line.
428:
429: The fill prefix is stored in the variable `fill-prefix'. Its value
430: is a string, or `nil' when there is no fill prefix. This is a
431: per-buffer variable; altering the variable affects only the current
432: buffer, but there is a default value which you can change as well.
433: *Note Locals::.
434:
435: Another way to use fill prefixes is through `M-x
436: fill-individual-paragraphs'. This function divides the region into
437: groups of consecutive lines with the same amount and kind of
438: indentation and fills each group as a paragraph using its indentation
439: as a fill prefix.
440:
441:
442: File: emacs, Node: Case, Prev: Filling, Up: Text
443:
444: Case Conversion Commands
445: ========================
446:
447: Emacs has commands for converting either a single word or any
448: arbitrary range of text to upper case or to lower case.
449:
450: `M-l'
451: Convert following word to lower case (`downcase-word').
452:
453: `M-u'
454: Convert following word to upper case (`upcase-word').
455:
456: `M-c'
457: Capitalize the following word (`capitalize-word').
458:
459: `C-x C-l'
460: Convert region to lower case (`downcase-region').
461:
462: `C-x C-u'
463: Convert region to upper case (`upcase-region').
464:
465: The word conversion commands are the most useful. `Meta-l'
466: (`downcase-word') converts the word after point to lower case, moving
467: past it. Thus, repeating `Meta-l' converts successive words. `Meta-u'
468: (`upcase-word') converts to all capitals instead, while `Meta-c'
469: (`capitalize-word') puts the letter following point into upper case and
470: the rest of the letters in the word into lower case. All these
471: commands convert several words at once if given an argument. They are
472: especially convenient for converting a large amount of text from all
473: upper case to mixed case, because you can move through the text using
474: `M-l', `M-u' or `M-c' on each word as appropriate, occasionally using
475: `M-f' instead to skip a word.
476:
477: When given a negative argument, the word case conversion commands
478: apply to the appropriate number of words before point, but do not move
479: point. This is convenient when you have just typed a word in the wrong
480: case: you can give the case conversion command and continue typing.
481:
482: If a word case conversion command is given in the middle of a word,
483: it applies only to the part of the word which follows point. This is
484: just like what `Meta-d' (`kill-word') does. With a negative argument,
485: case conversion applies only to the part of the word before point.
486:
487: The other case conversion commands are `C-x C-u' (`upcase-region')
488: and `C-x C-l' (`downcase-region'), which convert everything between
489: point and mark to the specified case. Point and mark do not move.
490:
491:
492: File: emacs, Node: Programs, Next: Compiling/Testing, Prev: Text, Up: Top
493:
494: Editing Programs
495: ****************
496:
497: Emacs has many commands designed to understand the syntax of
498: programming languages such as Lisp and C. These commands can
499:
500: * Move over or kill balanced expressions or "sexps" (*note Lists::.).
501:
502: * Move over or mark top-level balanced expressions ("defuns", in
503: Lisp; functions, in C).
504:
505: * Show how parentheses balance (*note Matching::.).
506:
507: * Insert, kill or align comments (*note Comments::.).
508:
509: * Follow the usual indentation conventions of the language (*note
510: Grinding::.).
511:
512: The commands for words, sentences and paragraphs are very useful in
513: editing code even though their canonical application is for editing
514: human language text. Most symbols contain words (*note Words::.);
515: sentences can be found in strings and comments (*note Sentences::.).
516: Paragraphs per se are not present in code, but the paragraph commands
517: are useful anyway, because Lisp mode and C mode define paragraphs to
518: begin and end at blank lines (*note Paragraphs::.). Judicious use of
519: blank lines to make the program clearer will also provide interesting
520: chunks of text for the paragraph commands to work on.
521:
522: The selective display feature is useful for looking at the overall
523: structure of a function (*note Selective Display::.). This feature
524: causes only the lines that are indented less than a specified amount to
525: appear on the screen.
526:
527: * Menu:
528:
529: * Program Modes:: Major modes for editing programs.
530: * Lists:: Expressions with balanced parentheses.
531: There are editing commands to operate on them.
532: * Defuns:: Each program is made up of separate functions.
533: There are editing commands to operate on them.
534: * Grinding:: Adjusting indentation to show the nesting.
535: * Matching:: Insertion of a close-delimiter flashes matching open.
536: * Comments:: Inserting, killing and aligning comments.
537: * Macro Expansion:: How to see the results of C macro expansion.
538: * Balanced Editing:: Inserting two matching parentheses at once, etc.
539: * Lisp Completion:: Completion on symbol names in Lisp code.
540: * Documentation:: Getting documentation of functions you plan to call.
541: * Change Log:: Maintaining a change history for your program.
542: * Tags:: Go direct to any function in your program in one
543: command. Tags remembers which file it is in.
544: * Fortran:: Fortran mode and its special features.
545:
546:
547: File: emacs, Node: Program Modes, Next: Lists, Prev: Programs, Up: Programs
548:
549: Major Modes for Programming Languages
550: =====================================
551:
552: Emacs has major modes for the programming languages Lisp, Scheme (a
553: variant of Lisp), C, Fortran and Muddle. Ideally, a major mode should
554: be implemented for each programming language that you might want to
555: edit with Emacs; but often the mode for one language can serve for other
556: syntactically similar languages. The language modes that exist are
557: those that someone decided to take the trouble to write.
558:
559: There are several forms of Lisp mode, which differ in the way they
560: interface to Lisp execution. *Note Lisp Modes::.
561:
562: Each of the programming language modes defines the TAB key to run an
563: indentation function that knows the indentation conventions of that
564: language and updates the current line's indentation accordingly. For
565: example, in C mode TAB is bound to `c-indent-line'. LFD is normally
566: defined to do RET followed by TAB; thus, it too indents in a
567: mode-specific fashion.
568:
569: In most programming languages, indentation is likely to vary from
570: line to line. So the major modes for those languages rebind DEL to
571: treat a tab as if it were the equivalent number of spaces (using the
572: command `backward-delete-char-untabify'). This makes it possible to
573: rub out indentation one column at a time without worrying whether it is
574: made up of spaces or tabs. Use `C-b C-d' to delete a tab character
575: before point, in these modes.
576:
577: Programming language modes define paragraphs to be separated only by
578: blank lines, so that the paragraph commands remain useful. Auto Fill
579: mode, if enabled in a programming language major mode, indents the new
580: lines which it creates.
581:
582: Turning on a major mode calls a user-supplied function called the
583: "mode hook", which is the value of a Lisp variable. For example,
584: turning on C mode calls the value of the variable `c-mode-hook' if that
585: value exists and is non-`nil'. Mode hook variables for other
586: programming language modes include `lisp-mode-hook',
587: `emacs-lisp-mode-hook', `lisp-interaction-mode-hook',
588: `scheme-mode-hook' and `muddle-mode-hook'. The mode hook function
589: receives no arguments.
590:
591:
592: File: emacs, Node: Lists, Next: Defuns, Prev: Program Modes, Up: Programs
593:
594: Lists and Sexps
595: ===============
596:
597: By convention, Emacs keys for dealing with balanced expressions are
598: usually `Control-Meta-' characters. They tend to be analogous in
599: function to their `Control-' and `Meta-' equivalents. These commands
600: are usually thought of as pertaining to expressions in programming
601: languages, but can be useful with any language in which some sort of
602: parentheses exist (including English).
603:
604: These commands fall into two classes. Some deal only with "lists"
605: (parenthetical groupings). They see nothing except parentheses,
606: brackets, braces (whichever ones must balance in the language you are
607: working with), and escape characters that might be used to quote those.
608:
609: The other commands deal with expressions or "sexps". The word `sexp'
610: is derived from "s-expression", the ancient term for an expression in
611: Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It
612: refers to an expression in whatever language your program is written in.
613: Each programming language has its own major mode, which customizes the
614: syntax tables so that expressions in that language count as sexps.
615:
616: Sexps typically include symbols, numbers, and string constants, as
617: well as anything contained in parentheses, brackets or braces.
618:
619: In languages that use prefix and infix operators, such as C, it is
620: not possible for all expressions to be sexps. For example, C mode does
621: not recognize `foo + bar' as a sexp, even though it is a C expression;
622: it recognizes `foo' as one sexp and `bar' as another, with the `+' as
623: punctuation between them. This is a fundamental ambiguity: both `foo +
624: bar' and `foo' are legitimate choices for the sexp to move over if
625: point is at the `f'. Note that `(foo + bar)' is a sexp in C mode.
626:
627: Some languages have obscure forms of syntax for expressions that
628: nobody has bothered to make Emacs understand properly.
629:
630: `C-M-f'
631: Move forward over a sexp (`forward-sexp').
632:
633: `C-M-b'
634: Move backward over a sexp (`backward-sexp').
635:
636: `C-M-k'
637: Kill sexp forward (`kill-sexp').
638:
639: `C-M-u'
640: Move up and backward in list structure (`backward-up-list').
641:
642: `C-M-d'
643: Move down and forward in list structure (`down-list').
644:
645: `C-M-n'
646: Move forward over a list (`forward-list').
647:
648: `C-M-p'
649: Move backward over a list (`backward-list').
650:
651: `C-M-t'
652: Transpose expressions (`transpose-sexps').
653:
654: `C-M-@'
655: Put mark after following expression (`mark-sexp').
656:
657: To move forward over a sexp, use `C-M-f' (`forward-sexp'). If the
658: first significant character after point is an opening delimiter (`(' in
659: Lisp; `(', `[' or `{' in C), `C-M-f' moves past the matching closing
660: delimiter. If the character begins a symbol, string, or number,
661: `C-M-f' moves over that. If the character after point is a closing
662: delimiter, `C-M-f' gets an error.
663:
664: The command `C-M-b' (`backward-sexp') moves backward over a sexp.
665: The detailed rules are like those above for `C-M-f', but with
666: directions reversed. If there are any prefix characters (singlequote,
667: backquote and comma, in Lisp) preceding the sexp, `C-M-b' moves back
668: over them as well.
669:
670: `C-M-f' or `C-M-b' with an argument repeats that operation the
671: specified number of times; with a negative argument, it moves in the
672: opposite direction.
673:
674: The sexp commands move across comments as if they were whitespace, in
675: languages such as C where the comment-terminator can be recognized. In
676: Lisp, and other languages where comments run until the end of a line,
677: it is very difficult to ignore comments when parsing backwards;
678: therefore, in such languages the sexp commands treat the text of
679: comments as if it were code.
680:
681: Killing a sexp at a time can be done with `C-M-k' (`kill-sexp').
682: `C-M-k' kills the characters that `C-M-f' would move over.
683:
684: The "list commands" move over lists like the sexp commands but skip
685: blithely over any number of other kinds of sexps (symbols, strings,
686: etc). They are `C-M-n' (`forward-list') and `C-M-p' (`backward-list').
687: The main reason they are useful is that they usually ignore comments
688: (since the comments usually do not contain any lists).
689:
690: `C-M-n' and `C-M-p' stay at the same level in parentheses, when
691: that's possible. To move up one (or N) levels, use `C-M-u'
692: (`backward-up-list'). `C-M-u' moves backward up past one unmatched
693: opening delimiter. A positive argument serves as a repeat count; a
694: negative argument reverses direction of motion and also requests
695: repetition, so it moves forward and up one or more levels.
696:
697: To move down in list structure, use `C-M-d' (`down-list'). In Lisp
698: mode, where `(' is the only opening delimiter, this is nearly the same
699: as searching for a `('. An argument specifies the number of levels of
700: parentheses to go down.
701:
702: A somewhat random-sounding command which is nevertheless easy to use
703: is `C-M-t' (`transpose-sexps'), which drags the previous sexp across
704: the next one. An argument serves as a repeat count, and a negative
705: argument drags backwards (thus canceling out the effect of `C-M-t' with
706: a positive argument). An argument of zero, rather than doing nothing,
707: transposes the sexps ending after point and the mark.
708:
709: To make the region be the next sexp in the buffer, use `C-M-@'
710: (`mark-sexp') which sets mark at the same place that `C-M-f' would move
711: to. `C-M-@' takes arguments like `C-M-f'. In particular, a negative
712: argument is useful for putting the mark at the beginning of the
713: previous sexp.
714:
715: The list and sexp commands' understanding of syntax is completely
716: controlled by the syntax table. Any character can, for example, be
717: declared to be an opening delimiter and act like an open parenthesis.
718: *Note Syntax::.
719:
720:
721: File: emacs, Node: Defuns, Next: Grinding, Prev: Lists, Up: Programs
722:
723: Defuns
724: ======
725:
726: In Emacs, a parenthetical grouping at the top level in the buffer is
727: called a "defun". The name derives from the fact that most top-level
728: lists in a Lisp file are instances of the special form `defun', but any
729: top-level parenthetical grouping counts as a defun in Emacs parlance
730: regardless of what its contents are, and regardless of the programming
731: language in use. For example, in C, the body of a function definition
732: is a defun.
733:
734: `C-M-a'
735: Move to beginning of current or preceding defun
736: (`beginning-of-defun').
737:
738: `C-M-e'
739: Move to end of current or following defun (`end-of-defun').
740:
741: `C-M-h'
742: Put region around whole current or following defun (`mark-defun').
743:
744: The commands to move to the beginning and end of the current defun
745: are `C-M-a' (`beginning-of-defun') and `C-M-e' (`end-of-defun').
746:
747: If you wish to operate on the current defun, use `C-M-h'
748: (`mark-defun') which puts point at the beginning and mark at the end of
749: the current or next defun. For example, this is the easiest way to get
750: ready to move the defun to a different place in the text. In C mode,
751: `C-M-h' runs the function `mark-c-function', which is almost the same
752: as `mark-defun'; the difference is that it backs up over the argument
753: declarations, function name and returned data type so that the entire C
754: function is inside the region.
755:
756: Emacs assumes that any open-parenthesis found in the leftmost column
757: is the start of a defun. Therefore, never put an open-parenthesis at
758: the left margin in a Lisp file unless it is the start of a top level
759: list. Never put an open-brace or other opening delimiter at the
760: beginning of a line of C code unless it starts the body of a function.
761: The most likely problem case is when you want an opening delimiter at
762: the start of a line inside a string. To avoid trouble, put an escape
763: character (`\', in C and Emacs Lisp, `/' in some other Lisp dialects)
764: before the opening delimiter. It will not affect the contents of the
765: string.
766:
767: In the remotest past, the original Emacs found defuns by moving
768: upward a level of parentheses until there were no more levels to go up.
769: This always required scanning all the way back to the beginning of the
770: buffer, even for a small function. To speed up the operation, Emacs
771: was changed to assume that any `(' (or other character assigned the
772: syntactic class of opening-delimiter) at the left margin is the start
773: of a defun. This heuristic was nearly always right and avoided the
774: costly scan; however, it mandated the convention described above.
775:
776:
777: File: emacs, Node: Grinding, Next: Matching, Prev: Defuns, Up: Programs
778:
779: Indentation for Programs
780: ========================
781:
782: The best way to keep a program properly indented ("ground") is to use
783: Emacs to re-indent it as you change it. Emacs has commands to indent
784: properly either a single line, a specified number of lines, or all of
785: the lines inside a single parenthetical grouping.
786:
787: * Menu:
788:
789: * Basic Indent::
790: * Multi-line Indent:: Commands to reindent many lines at once.
791: * Lisp Indent:: Specifying how each Lisp function should be indented.
792: * C Indent:: Choosing an indentation style for C code.
793:
794:
795: File: emacs, Node: Basic Indent, Next: Multi-line Indent, Prev: Grinding, Up: Grinding
796:
797: Basic Program Indentation Commands
798: ----------------------------------
799:
800: `TAB'
801: Adjust indentation of current line.
802:
803: `LFD'
804: Equivalent to RET followed by TAB (`newline-and-indent').
805:
806: The basic indentation command is TAB, which gives the current line
807: the correct indentation as determined from the previous lines. The
808: function that TAB runs depends on the major mode; it is
809: `lisp-indent-line' in Lisp mode, `c-indent-line' in C mode, etc. These
810: functions understand different syntaxes for different languages, but
811: they all do about the same thing. TAB in any programming language
812: major mode inserts or deletes whitespace at the beginning of the
813: current line, independent of where point is in the line. If point is
814: inside the whitespace at the beginning of the line, TAB leaves it at
815: the end of that whitespace; otherwise, TAB leaves point fixed with
816: respect to the characters around it.
817:
818: Use `C-q TAB' to insert a tab at point.
819:
820: When entering a large amount of new code, use LFD
821: (`newline-and-indent'), which is equivalent to a RET followed by a TAB.
822: LFD creates a blank line, and then gives it the appropriate
823: indentation.
824:
825: TAB indents the second and following lines of the body of a
826: parenthetical grouping each under the preceding one; therefore, if you
827: alter one line's indentation to be nonstandard, the lines below will
828: tend to follow it. This is the right behavior in cases where the
829: standard result of TAB is unaesthetic.
830:
831: Remember that an open-parenthesis, open-brace or other opening
832: delimiter at the left margin is assumed by Emacs (including the
833: indentation routines) to be the start of a function. Therefore, you
834: must never have an opening delimiter in column zero that is not the
835: beginning of a function, not even inside a string. This restriction is
836: vital for making the indentation commands fast; you must simply accept
837: it. *Note Defuns::, for more information on this.
838:
839:
840: File: emacs, Node: Multi-line Indent, Next: Lisp Indent, Prev: Basic Indent, Up: Grinding
841:
842: Indenting Several Lines
843: -----------------------
844:
845: When you wish to re-indent several lines of code which have been
846: altered or moved to a different level in the list structure, you have
847: several commands available.
848:
849: `C-M-q'
850: Re-indent all the lines within one list (`indent-sexp').
851:
852: `C-u TAB'
853: Shift an entire list rigidly sideways so that its first line is
854: properly indented.
855:
856: `C-M-\'
857: Re-indent all lines in the region (`indent-region').
858:
859: You can re-indent the contents of a single list by positioning point
860: before the beginning of it and typing `C-M-q' (`indent-sexp' in Lisp
861: mode, `indent-c-exp' in C mode; also bound to other suitable functions
862: in other modes). The indentation of the line the sexp starts on is not
863: changed; therefore, only the relative indentation within the list, and
864: not its position, is changed. To correct the position as well, type a
865: TAB before the `C-M-q'.
866:
867: If the relative indentation within a list is correct but the
868: indentation of its beginning is not, go to the line the list begins on
869: and type `C-u TAB'. When TAB is given a numeric argument, it moves all
870: the lines in the grouping starting on the current line sideways the
871: same amount that the current line moves. It is clever, though, and
872: does not move lines that start inside strings, or C preprocessor lines
873: when in C mode.
874:
875: Another way to specify the range to be re-indented is with point and
876: mark. The command `C-M-\' (`indent-region') applies TAB to every line
877: whose first character is between point and mark.
878:
879:
880: File: emacs, Node: Lisp Indent, Next: C Indent, Prev: Multi-line Indent, Up: Grinding
881:
882: Customizing Lisp Indentation
883: ----------------------------
884:
885: The indentation pattern for a Lisp expression can depend on the
886: function called by the expression. For each Lisp function, you can
887: choose among several predefined patterns of indentation, or define an
888: arbitrary one with a Lisp program.
889:
890: The standard pattern of indentation is as follows: the second line
891: of the expression is indented under the first argument, if that is on
892: the same line as the beginning of the expression; otherwise, the second
893: line is indented underneath the function name. Each following line is
894: indented under the previous line whose nesting depth is the same.
895:
896: If the variable `lisp-indent-offset' is non-`nil', it overrides the
897: usual indentation pattern for the second line of an expression, so that
898: such lines are always indented `lisp-indent-offset' more columns than
899: the containing list.
900:
901: The standard pattern is overridden for certain functions. Functions
902: whose names start with `def' always indent the second line by
903: `lisp-body-indention' extra columns beyond the open-parenthesis
904: starting the expression.
905:
906: The standard pattern can be overridden in various ways for individual
907: functions, according to the `lisp-indent-hook' property of the function
908: name. There are four possibilities for this property:
909:
910: `nil'
911: This is the same as no property; the standard indentation pattern
912: is used.
913:
914: `defun'
915: The pattern used for function names that start with `def' is used
916: for this function also.
917:
918: a number, NUMBER
919: The first NUMBER arguments of the function are "distinguished"
920: arguments; the rest are considered the "body" of the expression.
921: A line in the expression is indented according to whether the
922: first argument on it is distinguished or not. If the argument is
923: part of the body, the line is indented `lisp-body-indent' more
924: columns than the open-parenthesis starting the containing
925: expression. If the argument is distinguished and is either the
926: first or second argument, it is indented twice that many extra
927: columns. If the argument is distinguished and not the first or
928: second argument, the standard pattern is followed for that line.
929:
930: a symbol, SYMBOL
931: SYMBOL should be a function name; that function is called to
932: calculate the indentation of a line within this expression. The
933: function receives two arguments:
934: STATE
935: The value returned by `parse-partial-sexp' (a Lisp primitive
936: for indentation and nesting computation) when it parses up to
937: the beginning of this line.
938:
939: POS
940: The position at which the line being indented begins.
941:
942: It should return either a number, which is the number of columns of
943: indentation for that line, or a list whose CAR is such a number.
944: The difference between returning a number and returning a list is
945: that a number says that all following lines at the same nesting
946: level should be indented just like this one; a list says that
947: following lines might call for different indentations. This makes
948: a difference when the indentation is being computed by `C-M-q'; if
949: the value is a number, `C-M-q' need not recalculate indentation
950: for the following lines until the end of the list.
951:
952:
953: File: emacs, Node: C Indent, Prev: Lisp Indent, Up: Grinding
954:
955: Customizing C Indentation
956: -------------------------
957:
958: Two variables control which commands perform C indentation and when.
959:
960: If `c-auto-newline' is non-`nil', newlines are inserted both before
961: and after braces that you insert, and after colons and semicolons.
962: Correct C indentation is done on all the lines that are made this way.
963:
964: If `c-tab-always-indent' is `nil', the TAB command in C mode does
965: indentation only if point is at the left margin or within the line's
966: indentation. If there is non-whitespace to the left of point, then TAB
967: just inserts a tab character in the buffer. Normally, this variable is
968: `t', and TAB always reindents the current line.
969:
970: C does not have anything analogous to particular function names for
971: which special forms of indentation are desirable. However, it has a
972: different need for customization facilities: many different styles of C
973: indentation are in common use.
974:
975: There are six variables you can set to control the style that Emacs C
976: mode will use.
977:
978: `c-indent-level'
979: Indentation of C statements within surrounding block. The
980: surrounding block's indentation is the indentation of the line on
981: which the open-brace appears.
982:
983: `c-continued-statement-offset'
984: Extra indentation given to a substatement, such as the then-clause
985: of an if or body of a while.
986:
987: `c-brace-offset'
988: Extra indentation for line if it starts with an open brace.
989:
990: `c-brace-imaginary-offset'
991: An open brace following other text is treated as if it were this
992: far to the right of the start of its line.
993:
994: `c-argdecl-indent'
995: Indentation level of declarations of C function arguments.
996:
997: `c-label-offset'
998: Extra indentation for line that is a label, or case or default.
999:
1000: The variable `c-indent-level' controls the indentation for C
1001: statements with respect to the surrounding block. In the example
1002:
1003: {
1004: foo ();
1005:
1006: the difference in indentation between the lines is `c-indent-level'.
1007: Its standard value is 2.
1008:
1009: If the open-brace beginning the compound statement is not at the
1010: beginning of its line, the `c-indent-level' is added to the indentation
1011: of the line, not the column of the open-brace. For example,
1012:
1013: if (losing) {
1014: do_this ();
1015:
1016: One popular indentation style is that which results from setting
1017: `c-indent-level' to 8 and putting open-braces at the end of a line in
1018: this way. I prefer to put the open-brace on a separate line.
1019:
1020: In fact, the value of the variable `c-brace-imaginary-offset' is
1021: also added to the indentation of such a statement. Normally this
1022: variable is zero. Think of this variable as the imaginary position of
1023: the open brace, relative to the first nonblank character on the line.
1024: By setting this variable to 4 and `c-indent-level' to 0, you can get
1025: this style:
1026:
1027: if (x == y) {
1028: do_it ();
1029: }
1030:
1031: When `c-indent-level' is zero, the statements inside most braces
1032: will line up right under the open brace. But there is an exception made
1033: for braces in column zero, such as surrounding a function's body. The
1034: statements just inside it do not go at column zero. Instead,
1035: `c-brace-offset' and `c-continued-statement-offset' (see below) are
1036: added to produce a typical offset between brace levels, and the
1037: statements are indented that far.
1038:
1039: `c-continued-statement-offset' controls the extra indentation for a
1040: line that starts within a statement (but not within parentheses or
1041: brackets). These lines are usually statements that are within other
1042: statements, such as the then-clauses of `if' statements and the bodies
1043: of `while' statements. This parameter is the difference in indentation
1044: between the two lines in
1045:
1046: if (x == y)
1047: do_it ();
1048:
1049: Its standard value is 2. Some popular indentation styles correspond to
1050: a value of zero for `c-continued-statement-offset'.
1051:
1052: `c-brace-offset' is the extra indentation given to a line that
1053: starts with an open-brace. Its standard value is zero; compare
1054:
1055: if (x == y)
1056: {
1057:
1058: with
1059:
1060: if (x == y)
1061: do_it ();
1062:
1063: if `c-brace-offset' were set to 4, the first example would become
1064:
1065: if (x == y)
1066: {
1067:
1068: `c-argdecl-indent' controls the indentation of declarations of the
1069: arguments of a C function. It is absolute: argument declarations
1070: receive exactly `c-argdecl-indent' spaces. The standard value is 5,
1071: resulting in code like this:
1072:
1073: char *
1074: index (string, c)
1075: char *string;
1076: int c;
1077:
1078: `c-label-offset' is the extra indentation given to a line that
1079: contains a label, a case statement, or a `default:' statement. Its
1080: standard value is -2, resulting in code like this
1081:
1082: switch (c)
1083: {
1084: case 'x':
1085:
1086: If `c-label-offset' were zero, the same code would be indented as
1087:
1088: switch (c)
1089: {
1090: case 'x':
1091:
1092: This example assumes that the other variables above also have their
1093: standard values.
1094:
1095: I strongly recommend that you try out the indentation style produced
1096: by the standard settings of these variables, together with putting open
1097: braces on separate lines. You can see how it looks in all the C source
1098: files of GNU Emacs.
1099:
1100:
1101: File: emacs, Node: Matching, Next: Comments, Prev: Grinding, Up: Programs
1102:
1103: Automatic Display Of Matching Parentheses
1104: =========================================
1105:
1106: The Emacs parenthesis-matching feature is designed to show
1107: automatically how parentheses match in the text. Whenever a
1108: self-inserting character that is a closing delimiter is typed, the
1109: cursor moves momentarily to the location of the matching opening
1110: delimiter, provided that is on the screen. If it is not on the screen,
1111: some text starting with that opening delimiter is displayed in the echo
1112: area. Either way, you can tell what grouping is being closed off.
1113:
1114: In Lisp, automatic matching applies only to parentheses. In C, it
1115: applies to braces and brackets too. Emacs knows which characters to
1116: regard as matching delimiters based on the syntax table, which is set
1117: by the major mode. *Note Syntax::.
1118:
1119: If the opening delimiter and closing delimiter are mismatched--such
1120: as in `[x)'--a warning message is displayed in the echo area. The
1121: correct matches are specified in the syntax table.
1122:
1123: Two variables control parenthesis match display.
1124: `blink-matching-paren' turns the feature on or off; `nil' turns it off,
1125: but the default is `t' to turn match display on.
1126: `blink-matching-paren-distance' specifies how many characters back to
1127: search to find the matching opening delimiter. If the match is not
1128: found in that far, scanning stops, and nothing is displayed. This is
1129: to prevent scanning for the matching delimiter from wasting lots of
1130: time when there is no match. The default is 4000.
1131:
1132:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.