1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000,
3 @c 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Programs, Building, Text, Top
6 @chapter Editing Programs
9 @cindex program editing
11 Emacs provides many features to facilitate editing programs. Some
16 Find or move over top-level definitions (@pxref{Defuns}).
18 Apply the usual indentation conventions of the language
19 (@pxref{Program Indent}).
21 Balance parentheses (@pxref{Parentheses}).
23 Insert, kill or align comments (@pxref{Comments}).
25 Highlight program syntax (@pxref{Font Lock}).
28 This chapter describes these features and many more.
31 * Program Modes:: Major modes for editing programs.
32 * Defuns:: Commands to operate on major top-level parts
34 * Program Indent:: Adjusting indentation to show the nesting.
35 * Parentheses:: Commands that operate on parentheses.
36 * Comments:: Inserting, killing, and aligning comments.
37 * Documentation:: Getting documentation of functions you plan to call.
38 * Hideshow:: Displaying blocks selectively.
39 * Symbol Completion:: Completion on symbol names of your program or language.
40 * Glasses:: Making identifiersLikeThis more readable.
41 * Misc for Programs:: Other Emacs features useful for editing programs.
42 * C Modes:: Special commands of C, C++, Objective-C,
44 * Asm Mode:: Asm mode and its special features.
48 @section Major Modes for Programming Languages
49 @cindex modes for programming languages
51 Emacs has specialized major modes for various programming languages.
52 @xref{Major Modes}. A programming language major mode typically
53 specifies the syntax of expressions, the customary rules for
54 indentation, how to do syntax highlighting for the language, and how
55 to find the beginning of a function definition. It often customizes
56 or provides facilities for compiling and debugging programs as well.
58 Ideally, Emacs should provide a major mode for each programming
59 language that you might want to edit; if it doesn't have a mode for
60 your favorite language, you can contribute one. But often the mode
61 for one language can serve for other syntactically similar languages.
62 The major mode for language @var{l} is called @code{@var{l}-mode},
63 and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}.
64 @xref{Choosing Modes}.
80 @cindex Shell-script mode
82 @cindex PostScript mode
85 The existing programming language major modes include Lisp, Scheme (a
86 variant of Lisp) and the Scheme-based DSSSL expression language, Ada,
87 ASM, AWK, C, C++, Delphi (Object Pascal), Fortran (free format and fixed
88 format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s
89 companion for font creation), Modula2, Objective-C, Octave, Pascal,
90 Perl, Pike, PostScript, Prolog, Python, Simula, Tcl, and VHDL. An
91 alternative mode for Perl is called CPerl mode. Modes are available for
92 the scripting languages of the common GNU and Unix shells, VMS DCL, and
93 MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for
94 editing makefiles, DNS master files, and various sorts of configuration
97 @kindex DEL @r{(programming modes)}
98 @findex c-electric-backspace
99 In most programming languages, indentation should vary from line to
100 line to illustrate the structure of the program. So the major modes
101 for programming languages arrange for @key{TAB} to update the
102 indentation of the current line. They also rebind @key{DEL} to treat
103 a tab as if it were the equivalent number of spaces; this lets you
104 delete one column of indentation without worrying whether the
105 whitespace consists of spaces or tabs. Use @kbd{C-b C-d} to delete a
106 tab character before point, in these modes.
108 Separate manuals are available for the modes for Ada (@pxref{Top, , Ada
109 Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK
110 (@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes
111 (@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). For Fortran
112 mode, @inforef{Fortran,, emacs-xtra}.
116 @vindex lisp-mode-hook
117 @vindex emacs-lisp-mode-hook
118 @vindex lisp-interaction-mode-hook
119 @vindex scheme-mode-hook
120 Turning on a major mode runs a normal hook called the @dfn{mode
121 hook}, which is the value of a Lisp variable. Each major mode has a
122 mode hook, and the hook's name is always made from the mode command's
123 name by adding @samp{-hook}. For example, turning on C mode runs the
124 hook @code{c-mode-hook}, while turning on Lisp mode runs the hook
125 @code{lisp-mode-hook}. The purpose of the mode hook is to give you a
126 place to set up customizations for that major mode. @xref{Hooks}.
129 @section Top-Level Definitions, or Defuns
131 In Emacs, a major definition at the top level in the buffer,
132 something like a function, is called a @dfn{defun}. The name comes
133 from Lisp, but in Emacs we use it for all languages.
136 * Left Margin Paren:: An open-paren or similar opening delimiter
137 starts a defun if it is at the left margin.
138 * Moving by Defuns:: Commands to move over or mark a major definition.
139 * Imenu:: Making buffer indexes as menus.
140 * Which Function:: Which Function mode shows which function you are in.
143 @node Left Margin Paren
144 @subsection Left Margin Convention
146 @cindex open-parenthesis in leftmost column
147 @cindex ( in leftmost column
148 Emacs assumes by default that any opening delimiter found at the
149 left margin is the start of a top-level definition, or defun. You can
150 override this default by setting this user option:
152 @defvar open-paren-in-column-0-is-defun-start
153 If this user option is set to @code{t} (the default), opening
154 parentheses or braces at column zero always start defuns. When it's
155 @code{nil}, defuns are found by searching for parens or braces at the
156 outermost level. Some major modes, including C and related modes, set
157 @code{open-paren-in-column-0-is-defun-start} buffer-locally to
161 In modes where @code{open-paren-in-column-0-is-defun-start} is
162 @code{t}, @strong{don't put an opening delimiter at the left margin
163 unless it is a defun start}. For instance, never put an
164 open-parenthesis at the left margin in a Lisp file unless it is the
165 start of a top-level list.
167 If you don't follow this convention, not only will you have trouble
168 when you explicitly use the commands for motion by defuns; other
169 features that use them will also give you trouble. This includes
170 the indentation commands (@pxref{Program Indent}) and Font Lock
171 mode (@pxref{Font Lock}).
173 The most likely problem case is when you want an opening delimiter
174 at the start of a line inside a string. To avoid trouble, put an
175 escape character (@samp{\}, in Emacs Lisp, @samp{/} in some other Lisp
176 dialects) before the opening delimiter. This will not affect the
177 contents of the string, but will prevent that opening delimiter from
178 starting a defun. Here's an example:
186 To help you catch violations of this convention, Font Lock mode
187 highlights confusing opening delimiters (those that ought to be
190 In the earliest days, the original Emacs found defuns by moving
191 upward a level of parentheses or braces until there were no more
192 levels to go up. This always required scanning all the way back to
193 the beginning of the buffer, even for a small function. To speed up
194 the operation, we changed Emacs to assume that any opening delimiter
195 at the left margin is the start of a defun. This heuristic is nearly
196 always right, and avoids the need to scan back to the beginning of the
197 buffer. However, now that modern computers are so powerful, this
198 scanning is rarely slow enough to annoy, so we've provided a way to
199 disable the heuristic.
201 @node Moving by Defuns
202 @subsection Moving by Defuns
205 These commands move point or set up the region based on top-level
206 major definitions, also called @dfn{defuns}.
210 Move to beginning of current or preceding defun
211 (@code{beginning-of-defun}).
213 Move to end of current or following defun (@code{end-of-defun}).
215 Put region around whole current or following defun (@code{mark-defun}).
218 @cindex move to beginning or end of function
219 @cindex function, move to beginning or end
223 @findex beginning-of-defun
226 The commands to move to the beginning and end of the current defun
227 are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e}
228 (@code{end-of-defun}). If you repeat one of these commands, or use a
229 positive numeric argument, each repetition moves to the next defun in
230 the direction of motion.
232 @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward
233 @var{n} times to the next beginning of a defun. This is not exactly
234 the same place that @kbd{C-M-e} with argument @var{n} would move to;
235 the end of this defun is not usually exactly the same place as the
236 beginning of the following defun. (Whitespace, comments, and perhaps
237 declarations can separate them.) Likewise, @kbd{C-M-e} with a
238 negative argument moves back to an end of a defun, which is not quite
239 the same as @kbd{C-M-a} with a positive argument.
241 @kindex C-M-h @r{(C mode)}
242 @findex c-mark-function
243 To operate on the current defun, use @kbd{C-M-h} (@code{mark-defun})
244 which puts point at the beginning and mark at the end of the current
245 defun. This is the easiest way to get ready to kill the defun in
246 order to move it to a different place in the file. If you use the
247 command while point is between defuns, it uses the following defun.
248 Successive uses of @kbd{C-M-h}, or using it in Transient Mark mode
249 when the mark is active, extends the end of the region to include one
250 more defun each time.
252 In C mode, @kbd{C-M-h} runs the function @code{c-mark-function},
253 which is almost the same as @code{mark-defun}; the difference is that
254 it backs up over the argument declarations, function name and returned
255 data type so that the entire C function is inside the region. This is
256 an example of how major modes adjust the standard key bindings so that
257 they do their standard jobs in a way better fitting a particular
258 language. Other major modes may replace any or all of these key
259 bindings for that purpose.
263 @cindex index of buffer definitions
264 @cindex buffer definitions index
267 The Imenu facility offers a way to find the major definitions in
268 a file by name. It is also useful in text formatter major modes,
269 where it treats each chapter, section, etc., as a definition.
270 (@xref{Tags}, for a more powerful feature that handles multiple files
274 If you type @kbd{M-x imenu}, it reads the name of a definition using
275 the minibuffer, then moves point to that definition. You can use
276 completion to specify the name; the command always displays the whole
279 @findex imenu-add-menubar-index
280 Alternatively, you can bind the command @code{imenu} to a mouse
281 click. Then it displays mouse menus for you to select a definition
282 name. You can also add the buffer's index to the menu bar by calling
283 @code{imenu-add-menubar-index}. If you want to have this menu bar
284 item available for all buffers in a certain major mode, you can do
285 this by adding @code{imenu-add-menubar-index} to its mode hook. But
286 if you have done that, you will have to wait a little while each time
287 you visit a file in that mode, while Emacs finds all the definitions
290 @vindex imenu-auto-rescan
291 When you change the contents of a buffer, if you add or delete
292 definitions, you can update the buffer's index based on the
293 new contents by invoking the @samp{*Rescan*} item in the menu.
294 Rescanning happens automatically if you set @code{imenu-auto-rescan} to
295 a non-@code{nil} value. There is no need to rescan because of small
298 @vindex imenu-sort-function
299 You can customize the way the menus are sorted by setting the
300 variable @code{imenu-sort-function}. By default, names are ordered as
301 they occur in the buffer; if you want alphabetic sorting, use the
302 symbol @code{imenu--sort-by-name} as the value. You can also
303 define your own comparison function by writing Lisp code.
305 Imenu provides the information to guide Which Function mode
307 (@pxref{Which Function}).
312 The Speedbar can also use it (@pxref{Speedbar}).
315 @subsection Which Function Mode
316 @cindex current function name in mode line
318 Which Function mode is a minor mode that displays the current
319 function name in the mode line, updating it as you move around in a
322 @findex which-function-mode
323 @vindex which-func-modes
324 To enable (or disable) Which Function mode, use the command @kbd{M-x
325 which-function-mode}. This command is global; it applies to all
326 buffers, both existing ones and those yet to be created. However, it
327 takes effect only in certain major modes, those listed in the value of
328 @code{which-func-modes}. If the value is @code{t}, then Which Function
329 mode applies to all major modes that know how to support it---in other
330 words, all the major modes that support Imenu.
333 @section Indentation for Programs
334 @cindex indentation for programs
336 The best way to keep a program properly indented is to use Emacs to
337 reindent it as you change it. Emacs has commands to indent properly
338 either a single line, a specified number of lines, or all of the lines
339 inside a single parenthetical grouping.
342 * Basic Indent:: Indenting a single line.
343 * Multi-line Indent:: Commands to reindent many lines at once.
344 * Lisp Indent:: Specifying how each Lisp function should be indented.
345 * C Indent:: Extra features for indenting C and related modes.
346 * Custom C Indent:: Controlling indentation style for C and related modes.
349 @cindex pretty-printer
350 Emacs also provides a Lisp pretty-printer in the library @code{pp}.
351 This program reformats a Lisp object with indentation chosen to look nice.
354 @subsection Basic Program Indentation Commands
356 The basic indentation commands indent a single line according to the
357 usual conventions of the language you are editing.
361 Adjust indentation of current line.
363 Insert a newline, then adjust indentation of following line
364 (@code{newline-and-indent}).
367 @kindex TAB @r{(programming modes)}
368 @findex c-indent-command
369 @findex indent-line-function
370 @findex indent-for-tab-command
371 The basic indentation command is @key{TAB}, which gives the current line
372 the correct indentation as determined from the previous lines. The
373 function that @key{TAB} runs depends on the major mode; it is
374 @code{lisp-indent-line}
375 in Lisp mode, @code{c-indent-command} in C mode, etc. These functions
376 understand the syntax and conventions of different languages, but they all do
377 conceptually the same job: @key{TAB} in any programming-language major mode
378 inserts or deletes whitespace at the beginning of the current line,
379 independent of where point is in the line. If point was inside the
380 whitespace at the beginning of the line, @key{TAB} puts it at the end of
381 that whitespace; otherwise, @key{TAB} keeps point fixed with respect to
382 the characters around it.
384 Use @kbd{C-q @key{TAB}} to insert a tab character at point.
387 @findex newline-and-indent
388 When entering lines of new code, use @kbd{C-j}
389 (@code{newline-and-indent}), which inserts a newline and then adjusts
390 indentation after it. (It also deletes any trailing whitespace which
391 remains before the new newline.) Thus, @kbd{C-j} at the end of a line
392 creates a blank line with appropriate indentation. In programming
393 language modes, it is equivalent to @key{RET} @key{TAB}.
395 @key{TAB} indents a line that starts within a parenthetical grouping
396 under the preceding line within the grouping, or the text after the
397 parenthesis. Therefore, if you manually give one of these lines a
398 nonstandard indentation, the lines below will tend to follow it. This
399 behavior is convenient in cases where you have overridden the standard
400 result of @key{TAB} because you find it unaesthetic for a particular
403 In some modes, an open-parenthesis, open-brace or other opening
404 delimiter at the left margin is assumed by Emacs (including the
405 indentation routines) to be the start of a function. This speeds up
406 indentation commands. If you will be editing text which contains
407 opening delimiters in column zero that aren't the beginning of a
408 functions, even inside strings or comments, you must set
409 @code{open-paren-in-column-0-is-defun-start}. @xref{Left Margin
410 Paren}, for more information on this.
412 Normally, lines are indented with tabs and spaces. If you want Emacs
413 to use spaces only, set @code{indent-tabs-mode} (@pxref{Just Spaces}).
415 @node Multi-line Indent
416 @subsection Indenting Several Lines
418 When you wish to reindent several lines of code which have been
419 altered or moved to a different level in the parenthesis structure,
420 you have several commands available.
424 Reindent all the lines within one parenthetical grouping (@code{indent-pp-sexp}).
426 Reindent all lines in the region (@code{indent-region}).
428 Shift an entire parenthetical grouping rigidly sideways so that its
429 first line is properly indented.
430 @item M-x indent-code-rigidly
431 Shift all the lines in the region rigidly sideways, but do not alter
432 lines that start inside comments and strings.
436 @findex indent-pp-sexp
437 You can reindent the contents of a single parenthetical grouping by
438 positioning point before the beginning of it and typing @kbd{C-M-q}
439 (@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode; also
440 bound to other suitable commands in other modes). The indentation of
441 the line where the grouping starts is not changed; therefore this
442 changes only the relative indentation within the grouping, not its
443 overall indentation. To correct that as well, type @key{TAB} first.
445 Another way to specify the range to be reindented is with the
446 region. The command @kbd{C-M-\} (@code{indent-region}) applies
447 @key{TAB} to every line whose first character is between point and
451 If you like the relative indentation within a grouping, but not the
452 indentation of its first line, you can type @kbd{C-u @key{TAB}} to
453 reindent the whole grouping as a rigid unit. (This works in Lisp
454 modes and C and related modes.) @key{TAB} with a numeric argument
455 reindents the current line as usual, then reindents by the same amount
456 all the lines in the parenthetical grouping starting on the current
457 line. It is clever, though, and does not alter lines that start
458 inside strings. Neither does it alter C preprocessor lines when in C
459 mode, but it does reindent any continuation lines that may be attached
462 @findex indent-code-rigidly
463 You can also perform this operation on the region, using the command
464 @kbd{M-x indent-code-rigidly}. It rigidly shifts all the lines in the
465 region sideways, like @code{indent-rigidly} does (@pxref{Indentation
466 Commands}). It doesn't alter the indentation of lines that start
467 inside a string, unless the region also starts inside that string.
468 The prefix arg specifies the number of columns to indent.
471 @subsection Customizing Lisp Indentation
472 @cindex customizing Lisp indentation
474 The indentation pattern for a Lisp expression can depend on the function
475 called by the expression. For each Lisp function, you can choose among
476 several predefined patterns of indentation, or define an arbitrary one with
479 The standard pattern of indentation is as follows: the second line of the
480 expression is indented under the first argument, if that is on the same
481 line as the beginning of the expression; otherwise, the second line is
482 indented underneath the function name. Each following line is indented
483 under the previous line whose nesting depth is the same.
485 @vindex lisp-indent-offset
486 If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
487 the usual indentation pattern for the second line of an expression, so that
488 such lines are always indented @code{lisp-indent-offset} more columns than
491 @vindex lisp-body-indent
492 Certain functions override the standard pattern. Functions whose
493 names start with @code{def} treat the second lines as the start of
494 a @dfn{body}, by indenting the second line @code{lisp-body-indent}
495 additional columns beyond the open-parenthesis that starts the
498 @cindex @code{lisp-indent-function} property
499 You can override the standard pattern in various ways for individual
500 functions, according to the @code{lisp-indent-function} property of
501 the function name. Normally you would use this for macro definitions
502 and specify it using the @code{declare} construct (@pxref{Defining
503 Macros,,, elisp, the Emacs Lisp Reference Manual}).
506 @subsection Commands for C Indentation
508 Here are special features for indentation in C mode and related modes:
512 @kindex C-c C-q @r{(C mode)}
513 @findex c-indent-defun
514 Reindent the current top-level function definition or aggregate type
515 declaration (@code{c-indent-defun}).
518 @kindex C-M-q @r{(C mode)}
520 Reindent each line in the balanced expression that follows point
521 (@code{c-indent-exp}). A prefix argument inhibits warning messages
522 about invalid syntax.
525 @findex c-indent-command
526 Reindent the current line, and/or in some cases insert a tab character
527 (@code{c-indent-command}).
529 @vindex c-tab-always-indent
530 If @code{c-tab-always-indent} is @code{t}, this command always reindents
531 the current line and does nothing else. This is the default.
533 If that variable is @code{nil}, this command reindents the current line
534 only if point is at the left margin or in the line's indentation;
535 otherwise, it inserts a tab (or the equivalent number of spaces,
536 if @code{indent-tabs-mode} is @code{nil}).
538 Any other value (not @code{nil} or @code{t}) means always reindent the
539 line, and also insert a tab if within a comment or a string.
542 To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This
543 first selects the whole buffer as the region, then reindents that
546 To reindent the current block, use @kbd{C-M-u C-M-q}. This moves
547 to the front of the block and then reindents it all.
549 @node Custom C Indent
550 @subsection Customizing C Indentation
551 @cindex style (for indentation)
553 C mode and related modes use a flexible mechanism for customizing
554 indentation. C mode indents a source line in two steps: first it
555 classifies the line syntactically according to its contents and
556 context; second, it determines the indentation offset associated by
557 your selected @dfn{style} with the syntactic construct and adds this
558 onto the indentation of the @dfn{anchor statement}.
561 @item C-c . @key{RET} @var{style} @key{RET}
562 Select a predefined style @var{style} (@code{c-set-style}).
565 A @dfn{style} is a named collection of customizations that can be
566 used in C mode and the related modes. @ref{Styles,,, ccmode, The CC
567 Mode Manual}, for a complete description. Emacs comes with several
568 predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
569 @code{stroustrup}, @code{linux}, @code{python}, @code{java},
570 @code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these
571 styles are primarily intended for one language, but any of them can be
572 used with any of the languages supported by these modes. To find out
573 what a style looks like, select it and reindent some code, e.g., by
574 typing @key{C-M-q} at the start of a function definition.
576 @kindex C-c . @r{(C mode)}
578 To choose a style for the current buffer, use the command @w{@kbd{C-c
579 .}}. Specify a style name as an argument (case is not significant).
580 This command affects the current buffer only, and it affects only
581 future invocations of the indentation commands; it does not reindent
582 the code already in the buffer. To reindent the whole buffer in the
583 new style, you can type @kbd{C-x h C-M-\}.
585 @vindex c-default-style
586 You can also set the variable @code{c-default-style} to specify the
587 default style for various major modes. Its value should be either the
588 style's name (a string) or an alist, in which each element specifies
589 one major mode and which indentation style to use for it. For
593 (setq c-default-style
594 '((java-mode . "java") (awk-mode . "awk") (other . "gnu")))
598 specifies explicit choices for Java and AWK modes, and the default
599 @samp{gnu} style for the other C-like modes. (These settings are
600 actually the defaults.) This variable takes effect when you select
601 one of the C-like major modes; thus, if you specify a new default
602 style for Java mode, you can make it take effect in an existing Java
603 mode buffer by typing @kbd{M-x java-mode} there.
605 The @code{gnu} style specifies the formatting recommended by the GNU
606 Project for C; it is the default, so as to encourage use of our
609 @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and
610 @ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more
611 information on customizing indentation for C and related modes,
612 including how to override parts of an existing style and how to define
616 @section Commands for Editing with Parentheses
619 @cindex unbalanced parentheses and quotes
620 This section describes the commands and features that take advantage
621 of the parenthesis structure in a program, or help you keep it
624 When talking about these facilities, the term ``parenthesis'' also
625 includes braces, brackets, or whatever delimiters are defined to match
626 in pairs. The major mode controls which delimiters are significant,
627 through the syntax table (@pxref{Syntax}). In Lisp, only parentheses
628 count; in C, these commands apply to braces and brackets too.
630 You can use @kbd{M-x check-parens} to find any unbalanced
631 parentheses and unbalanced string quotes in the buffer.
634 * Expressions:: Expressions with balanced parentheses.
635 * Moving by Parens:: Commands for moving up, down and across
636 in the structure of parentheses.
637 * Matching:: Insertion of a close-delimiter flashes matching open.
641 @subsection Expressions with Balanced Parentheses
645 @cindex balanced expression
646 These commands deal with balanced expressions, also called
647 @dfn{sexps}@footnote{The word ``sexp'' is used to refer to an
648 expression in Lisp.}.
652 Move forward over a balanced expression (@code{forward-sexp}).
654 Move backward over a balanced expression (@code{backward-sexp}).
656 Kill balanced expression forward (@code{kill-sexp}).
658 Transpose expressions (@code{transpose-sexps}).
661 Put mark after following expression (@code{mark-sexp}).
664 Each programming language major mode customizes the definition of
665 balanced expressions to suit that language. Balanced expressions
666 typically include symbols, numbers, and string constants, as well as
667 any pair of matching delimiters and their contents. Some languages
668 have obscure forms of expression syntax that nobody has bothered to
672 By convention, the keys for these commands are all Control-Meta
673 characters. They usually act on expressions just as the corresponding
674 Meta characters act on words. For instance, the command @kbd{C-M-b}
675 moves backward over a balanced expression, just as @kbd{M-b} moves
681 @findex backward-sexp
682 To move forward over a balanced expression, use @kbd{C-M-f}
683 (@code{forward-sexp}). If the first significant character after point
684 is an opening delimiter (@samp{(} in Lisp; @samp{(}, @samp{[} or
685 @samp{@{} in C), @kbd{C-M-f} moves past the matching closing
686 delimiter. If the character begins a symbol, string, or number,
687 @kbd{C-M-f} moves over that.
689 The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
690 balanced expression. The detailed rules are like those above for
691 @kbd{C-M-f}, but with directions reversed. If there are prefix
692 characters (single-quote, backquote and comma, in Lisp) preceding the
693 expression, @kbd{C-M-b} moves back over them as well. The balanced
694 expression commands move across comments as if they were whitespace,
697 @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the
698 specified number of times; with a negative argument, it moves in the
701 @cindex killing expressions
704 Killing a whole balanced expression can be done with @kbd{C-M-k}
705 (@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f}
708 @cindex transposition of expressions
710 @findex transpose-sexps
711 A somewhat random-sounding command which is nevertheless handy is
712 @kbd{C-M-t} (@code{transpose-sexps}), which drags the previous
713 balanced expression across the next one. An argument serves as a
714 repeat count, moving the previous expression over that many following
715 ones. A negative argument drags the previous balanced expression
716 backwards across those before it (thus canceling out the effect of
717 @kbd{C-M-t} with a positive argument). An argument of zero, rather
718 than doing nothing, transposes the balanced expressions ending at or
719 after point and the mark.
722 @kindex C-M-@key{SPC}
724 To set the region around the next balanced expression in the buffer,
725 use @kbd{C-M-@@} (@code{mark-sexp}), which sets mark at the same place
726 that @kbd{C-M-f} would move to. @kbd{C-M-@@} takes arguments like
727 @kbd{C-M-f}. In particular, a negative argument is useful for putting
728 the mark at the beginning of the previous balanced expression. The
729 alias @kbd{C-M-@key{SPC}} is equivalent to @kbd{C-M-@@}. When you
730 repeat this command, or use it in Transient Mark mode when the mark is
731 active, it extends the end of the region by one sexp each time.
733 In languages that use infix operators, such as C, it is not possible
734 to recognize all balanced expressions as such because there can be
735 multiple possibilities at a given position. For example, C mode does
736 not treat @samp{foo + bar} as a single expression, even though it
737 @emph{is} one C expression; instead, it recognizes @samp{foo} as one
738 expression and @samp{bar} as another, with the @samp{+} as punctuation
739 between them. Both @samp{foo + bar} and @samp{foo} are legitimate
740 choices for ``the expression following point'' when point is at the
741 @samp{f}, so the expression commands must perforce choose one or the
742 other to operate on. Note that @samp{(foo + bar)} is recognized as a
743 single expression in C mode, because of the parentheses.
745 @node Moving by Parens
746 @subsection Moving in the Parenthesis Structure
748 @cindex parenthetical groupings
749 @cindex parentheses, moving across
750 @cindex matching parenthesis and braces, moving to
751 @cindex braces, moving across
752 @cindex list commands
753 The Emacs commands for handling parenthetical groupings see nothing
754 except parentheses (or whatever characters must balance in the
755 language you are working with), and the escape characters that might
756 be used to quote those. They are mainly intended for editing
757 programs, but can be useful for editing any text that has parentheses.
758 They are sometimes called ``list'' commands because in Lisp these
763 Move forward over a parenthetical group (@code{forward-list}).
765 Move backward over a parenthetical group (@code{backward-list}).
767 Move up in parenthesis structure (@code{backward-up-list}).
769 Move down in parenthesis structure (@code{down-list}).
775 @findex backward-list
776 The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and
777 @kbd{C-M-p} (@code{backward-list}) move over one (or @var{n})
778 parenthetical groupings, skipping blithely over any amount of text
779 that doesn't include meaningful parentheses (symbols, strings, etc.).
782 @findex backward-up-list
783 @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
784 parenthesis structure. To move @emph{up} one (or @var{n}) levels, use
785 @kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up
786 past one unmatched opening delimiter. A positive argument serves as a
787 repeat count; a negative argument reverses the direction of motion, so
788 that the command moves forward and up one or more levels.
792 To move @emph{down} in the parenthesis structure, use @kbd{C-M-d}
793 (@code{down-list}). In Lisp mode, where @samp{(} is the only opening
794 delimiter, this is nearly the same as searching for a @samp{(}. An
795 argument specifies the number of levels to go down.
798 @subsection Automatic Display Of Matching Parentheses
799 @cindex matching parentheses
800 @cindex parentheses, displaying matches
802 The Emacs parenthesis-matching feature is designed to show
803 automatically how parentheses (and other matching delimiters) match in
804 the text. Whenever you type a self-inserting character that is a
805 closing delimiter, the cursor moves momentarily to the location of the
806 matching opening delimiter, provided that is on the screen. If it is
807 not on the screen, Emacs displays some of the text near it in the echo
808 area. Either way, you can tell which grouping you are closing off.
810 If the opening delimiter and closing delimiter are mismatched---such
811 as in @samp{[x)}---a warning message is displayed in the echo area.
813 @vindex blink-matching-paren
814 @vindex blink-matching-paren-distance
815 @vindex blink-matching-delay
816 Three variables control parenthesis match display:
818 @code{blink-matching-paren} turns the feature on or off: @code{nil}
819 disables it, but the default is @code{t} to enable match display.
821 @code{blink-matching-delay} says how many seconds to leave the
822 cursor on the matching opening delimiter, before bringing it back to
823 the real location of point; the default is 1, but on some systems it
824 is useful to specify a fraction of a second.
826 @code{blink-matching-paren-distance} specifies how many characters
827 back to search to find the matching opening delimiter. If the match
828 is not found in that distance, scanning stops, and nothing is displayed.
829 This is to prevent the scan for the matching delimiter from wasting
830 lots of time when there is no match. The default is 25600.
832 @cindex Show Paren mode
833 @cindex highlighting matching parentheses
834 @findex show-paren-mode
835 Show Paren mode provides a more powerful kind of automatic matching.
836 Whenever point is after a closing delimiter, that delimiter and its
837 matching opening delimiter are both highlighted; otherwise, if point
838 is before an opening delimiter, the matching closing delimiter is
839 highlighted. (There is no need to highlight the opening delimiter in
840 that case, because the cursor appears on top of that character.) Use
841 the command @kbd{M-x show-paren-mode} to enable or disable this mode.
843 Show Paren mode uses the faces @code{show-paren-match} and
844 @code{show-paren-mismatch} to highlight parentheses; you can customize
845 them to control how highlighting looks. @xref{Face Customization}.
848 @section Manipulating Comments
851 Because comments are such an important part of programming, Emacs
852 provides special commands for editing and inserting comments. It can
853 also do spell checking on comments with Flyspell Prog mode
857 * Comment Commands:: Inserting, killing, and aligning comments.
858 * Multi-Line Comments:: Commands for adding and editing multi-line comments.
859 * Options for Comments::Customizing the comment features.
862 @node Comment Commands
863 @subsection Comment Commands
864 @cindex indentation for comments
865 @cindex alignment for comments
867 The comment commands in this table insert, kill and align comments.
868 They are described in this section and following sections.
872 Insert or realign comment on current line; alternatively, comment or
873 uncomment the region (@code{comment-dwim}).
875 Kill comment on current line (@code{comment-kill}).
877 Set comment column (@code{comment-set-column}).
880 Like @key{RET} followed by inserting and aligning a comment
881 (@code{comment-indent-new-line}). @xref{Multi-Line Comments}.
882 @item @kbd{M-x comment-region}
883 @itemx @kbd{C-c C-c} (in C-like modes)
884 Add or remove comment delimiters on all the lines in the region.
889 The command to create or align a comment is @kbd{M-;}
890 (@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What
891 I Mean''; it indicates that this command can be used for many
892 different jobs relating to comments, depending on the situation where
895 If there is no comment already on the line, @kbd{M-;} inserts a new
896 comment, aligned at a specific column called the @dfn{comment column}.
897 The new comment begins with the string Emacs thinks comments should
898 start with (the value of @code{comment-start}; see below). Point is
899 after that string, so you can insert the text of the comment right
900 away. If the major mode has specified a string to terminate comments,
901 @kbd{M-;} inserts that after point, to keep the syntax valid.
903 If the text of the line extends past the comment column, this
904 command aligns the comment start string to a suitable boundary
905 (usually, at least one space is inserted).
907 You can also use @kbd{M-;} to align an existing comment. If a line
908 already contains the comment-start string, @kbd{M-;} realigns it to
909 the conventional alignment and moves point after it. (Exception:
910 comments starting in column 0 are not moved.) Even when an existing
911 comment is properly aligned, @kbd{M-;} is still useful for moving
912 directly to the start of the text inside the comment.
916 @kbd{C-u M-;} kills any comment on the current line, along with the
917 whitespace before it. To reinsert the comment on another line, move
918 to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to
921 Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;}
922 (@code{comment-dwim}) with a prefix argument. That command is
923 programmed so that when it receives a prefix argument it calls
924 @code{comment-kill}. However, @code{comment-kill} is a valid command
925 in its own right, and you can bind it directly to a key if you wish.
927 @kbd{M-;} does two other jobs when used with an active region in
928 Transient Mark mode (@pxref{Transient Mark}). Then it either adds or
929 removes comment delimiters on each line of the region. (If every line
930 is a comment, it removes comment delimiters from each; otherwise, it
931 adds comment delimiters to each.) If you are not using Transient Mark
932 mode, then you should use the commands @code{comment-region} and
933 @code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}),
934 or else enable Transient Mark mode momentarily (@pxref{Momentary Mark}).
935 A prefix argument used in these circumstances specifies how many
936 comment delimiters to add or how many to delete.
938 Some major modes have special rules for aligning certain kinds of
939 comments in certain contexts. For example, in Lisp code, comments which
940 start with two semicolons are indented as if they were lines of code,
941 instead of at the comment column. Comments which start with three
942 semicolons are supposed to start at the left margin. Emacs understands
943 these conventions by indenting a double-semicolon comment using @key{TAB},
944 and by not changing the indentation of a triple-semicolon comment at all.
947 ;; This function is just an example
948 ;;; Here either two or three semicolons are appropriate.
950 ;;; And now, the first part of the function:
951 ;; The following line adds one.
952 (1+ x)) ; This line adds one.
955 For C-like modes, you can configure the exact effect of @kbd{M-;}
956 more flexibly than for most buffers by setting the variables
957 @code{c-indent-comment-alist} and
958 @code{c-indent-comments-syntactically-p}. For example, on a line
959 ending in a closing brace, @kbd{M-;} puts the comment one space after
960 the brace rather than at @code{comment-column}. For full details see
961 @ref{Comment Commands,,, ccmode, The CC Mode Manual}.
963 @node Multi-Line Comments
964 @subsection Multiple Lines of Comments
968 @cindex blank lines in programs
969 @findex comment-indent-new-line
971 If you are typing a comment and wish to continue it on another line,
972 you can use the command @kbd{C-M-j} or @kbd{M-j}
973 (@code{comment-indent-new-line}). If @code{comment-multi-line}
974 (@pxref{Options for Comments}) is non-@code{nil}, it moves to a new
975 line within the comment. Otherwise it closes the comment and starts a
976 new comment on a new line. When Auto Fill mode is on, going past the
977 fill column while typing a comment causes the comment to be continued
978 in just this fashion.
980 @kindex C-c C-c (C mode)
981 @findex comment-region
982 To turn existing lines into comment lines, use the @kbd{M-x
983 comment-region} command (or type @kbd{C-c C-c} in C-like modes). It
984 adds comment delimiters to the lines that start in the region, thus
985 commenting them out. With a negative argument, it does the
986 opposite---it deletes comment delimiters from the lines in the region.
988 With a positive argument, @code{comment-region} duplicates the last
989 character of the comment start sequence it adds; the argument
990 specifies how many copies of the character to insert. Thus, in Lisp
991 mode, @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line.
992 Duplicating the comment delimiter is a way of calling attention to the
993 comment. It can also affect how the comment is aligned or indented.
994 In Lisp, for proper indentation, you should use an argument of two or
995 three, if between defuns; if within a defun, it must be three.
997 You can configure C Mode such that when you type a @samp{/} at the
998 start of a line in a multi-line block comment, this closes the
999 comment. Enable the @code{comment-close-slash} clean-up for this.
1000 @xref{Clean-ups,,, ccmode, The CC Mode Manual}.
1002 @node Options for Comments
1003 @subsection Options Controlling Comments
1005 @vindex comment-column
1007 @findex comment-set-column
1008 The @dfn{comment column}, the column at which Emacs tries to place
1009 comments, is stored in the variable @code{comment-column}. You can
1010 set it to a number explicitly. Alternatively, the command @kbd{C-x ;}
1011 (@code{comment-set-column}) sets the comment column to the column
1012 point is at. @kbd{C-u C-x ;} sets the comment column to match the
1013 last comment before point in the buffer, and then does a @kbd{M-;} to
1014 align the current line's comment under the previous one.
1016 The variable @code{comment-column} is per-buffer: setting the variable
1017 in the normal fashion affects only the current buffer, but there is a
1018 default value which you can change with @code{setq-default}.
1019 @xref{Locals}. Many major modes initialize this variable for the
1022 @vindex comment-start-skip
1023 The comment commands recognize comments based on the regular
1024 expression that is the value of the variable @code{comment-start-skip}.
1025 Make sure this regexp does not match the null string. It may match more
1026 than the comment starting delimiter in the strictest sense of the word;
1027 for example, in C mode the value of the variable is
1028 @c This stops M-q from breaking the line inside that @code.
1029 @code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces
1030 after the @samp{/*} itself, and accepts C++ style comments also.
1031 (Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in
1032 the string, which is needed to deny the first star its special meaning
1033 in regexp syntax. @xref{Regexp Backslash}.)
1035 @vindex comment-start
1037 When a comment command makes a new comment, it inserts the value of
1038 @code{comment-start} to begin it. The value of @code{comment-end} is
1039 inserted after point, so that it will follow the text that you will
1040 insert into the comment. When @code{comment-end} is non-empty, it
1041 should start with a space. For example, in C mode,
1042 @code{comment-start} has the value @w{@code{"/* "}} and
1043 @code{comment-end} has the value @w{@code{" */"}}.
1045 @vindex comment-padding
1046 The variable @code{comment-padding} specifies how many spaces
1047 @code{comment-region} should insert on each line between the comment
1048 delimiter and the line's original text. The default is 1, to insert
1049 one space. @code{nil} means 0. Alternatively, @code{comment-padding}
1050 can hold the actual string to insert.
1052 @vindex comment-multi-line
1053 The variable @code{comment-multi-line} controls how @kbd{C-M-j}
1054 (@code{indent-new-comment-line}) behaves when used inside a comment.
1055 Specifically, when @code{comment-multi-line} is @code{nil}, the
1056 command inserts a comment terminator, begins a new line, and finally
1057 inserts a comment starter. Otherwise it does not insert the
1058 terminator and starter, so it effectively continues the current
1059 comment across multiple lines. In languages that allow multi-line
1060 comments, the choice of value for this variable is a matter of taste.
1061 The default for this variable depends on the major mode.
1063 @vindex comment-indent-function
1064 The variable @code{comment-indent-function} should contain a function
1065 that will be called to compute the alignment for a newly inserted
1066 comment or for aligning an existing comment. It is set differently by
1067 various major modes. The function is called with no arguments, but with
1068 point at the beginning of the comment, or at the end of a line if a new
1069 comment is to be inserted. It should return the column in which the
1070 comment ought to start. For example, in Lisp mode, the indent hook
1071 function bases its decision on how many semicolons begin an existing
1072 comment, and on the code in the preceding lines.
1075 @section Documentation Lookup
1077 Emacs provides several features you can use to look up the
1078 documentation of functions, variables and commands that you plan to
1079 use in your program.
1082 * Info Lookup:: Looking up library functions and commands
1084 * Man Page:: Looking up man pages of library functions and commands.
1085 * Lisp Doc:: Looking up Emacs Lisp functions, etc.
1089 @subsection Info Documentation Lookup
1091 @findex info-lookup-symbol
1092 @findex info-lookup-file
1094 For many major modes, that apply to languages that have
1095 documentation in Info, you can use @kbd{C-h S}
1096 (@code{info-lookup-symbol}) to view the Info documentation for a
1097 symbol used in the program. You specify the symbol with the
1098 minibuffer; the default is the symbol appearing in the buffer at
1099 point. For example, in C mode this looks for the symbol in the C
1100 Library Manual. The command only works if the appropriate manual's
1101 Info files are installed.
1103 The major mode determines where to look for documentation for the
1104 symbol---which Info files to look in, and which indices to search.
1105 You can also use @kbd{M-x info-lookup-file} to look for documentation
1108 If you use @kbd{C-h S} in a major mode that does not support it,
1109 it asks you to specify the ``symbol help mode''. You should enter
1110 a command such as @code{c-mode} that would select a major
1111 mode which @kbd{C-h S} does support.
1114 @subsection Man Page Lookup
1117 On Unix, the main form of on-line documentation was the @dfn{manual
1118 page} or @dfn{man page}. In the GNU operating system, we aim to
1119 replace man pages with better-organized manuals that you can browse
1120 with Info (@pxref{Misc Help}). This process is not finished, so it is
1121 still useful to read manual pages.
1123 @findex manual-entry
1124 You can read the man page for an operating system command, library
1125 function, or system call, with the @kbd{M-x man} command. It
1126 runs the @code{man} program to format the man page; if the system
1127 permits, it runs @code{man} asynchronously, so that you can keep on
1128 editing while the page is being formatted. (On MS-DOS and MS-Windows
1129 3, you cannot edit while Emacs waits for @code{man} to finish.) The
1130 result goes in a buffer named @samp{*Man @var{topic}*}. These buffers
1131 use a special major mode, Man mode, that facilitates scrolling and
1132 jumping to other manual pages. For details, type @kbd{C-h m} while in
1135 @cindex sections of manual pages
1136 Each man page belongs to one of ten or more @dfn{sections}, each
1137 named by a digit or by a digit and a letter. Sometimes there are
1138 multiple man pages with the same name in different sections. To read
1139 a man page from a specific section, type
1140 @samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}}
1141 when @kbd{M-x manual-entry} prompts for the topic. For example, to
1142 read the man page for the C library function @code{chmod} (as opposed
1143 to a command of the same name), type @kbd{M-x manual-entry @key{RET}
1144 chmod(2) @key{RET}}. (@code{chmod} is a system call, so it is in
1147 @vindex Man-switches
1148 If you do not specify a section, the results depend on how the
1149 @code{man} program works on your system. Some of them display only
1150 the first man page they find. Others display all man pages that have
1151 the specified name, so you can move between them with the @kbd{M-n}
1152 and @kbd{M-p} keys@footnote{On some systems, the @code{man} program
1153 accepts a @samp{-a} command-line option which tells it to display all
1154 the man pages for the specified topic. If you want this behavior, you
1155 can add this option to the value of the variable @code{Man-switches}.}.
1156 The mode line shows how many manual pages are present in the Man buffer.
1158 @vindex Man-fontify-manpage-flag
1159 By default, Emacs highlights the text in man pages. For a long man
1160 page, highlighting can take substantial time. You can turn off
1161 highlighting of man pages by setting the variable
1162 @code{Man-fontify-manpage-flag} to @code{nil}.
1164 @findex Man-fontify-manpage
1165 If you insert the text of a man page into an Emacs buffer in some
1166 other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to
1167 perform the same conversions that @kbd{M-x manual-entry} does.
1170 @cindex manual pages, on MS-DOS/MS-Windows
1171 An alternative way of reading manual pages is the @kbd{M-x woman}
1172 command@footnote{The name of the command, @code{woman}, is an acronym
1173 for ``w/o (without) man,'' since it doesn't use the @code{man}
1174 program.}. Unlike @kbd{M-x man}, it does not run any external
1175 programs to format and display the man pages; instead it does the job
1176 in Emacs Lisp, so it works on systems such as MS-Windows, where the
1177 @code{man} program (and other programs it uses) are not generally
1180 @kbd{M-x woman} prompts for a name of a manual page, and provides
1181 completion based on the list of manual pages that are installed on
1182 your machine; the list of available manual pages is computed
1183 automatically the first time you invoke @code{woman}. The word at
1184 point in the current buffer is used to suggest the default for the
1185 name the manual page.
1187 With a numeric argument, @kbd{M-x woman} recomputes the list of the
1188 manual pages used for completion. This is useful if you add or delete
1191 If you type a name of a manual page and @kbd{M-x woman} finds that
1192 several manual pages by the same name exist in different sections, it
1193 pops up a window with possible candidates asking you to choose one of
1196 For more information about setting up and using @kbd{M-x woman}, see
1197 @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan
1201 @subsection Emacs Lisp Documentation Lookup
1203 As you edit Lisp code to be run in Emacs, you can use the commands
1204 @kbd{C-h f} (@code{describe-function}) and @kbd{C-h v}
1205 (@code{describe-variable}) to view documentation of functions and
1206 variables that you want to use. These commands use the minibuffer to
1207 read the name of a function or variable to document, and display the
1208 documentation in a window. Their default arguments are based on the
1209 code in the neighborhood of point. For @kbd{C-h f}, the default is
1210 the function called in the innermost list containing point. @kbd{C-h
1211 v} uses the symbol name around or adjacent to point as its default.
1215 A more automatic but less powerful method is Eldoc mode. This minor
1216 mode constantly displays in the echo area the argument list for the
1217 function being called at point. (In other words, it finds the
1218 function call that point is contained in, and displays the argument
1219 list of that function.) If point is over a documented variable, it
1220 shows the first line of the variable's docstring. Eldoc mode applies
1221 in Emacs Lisp and Lisp Interaction modes, and perhaps a few others
1222 that provide special support for looking up doc strings. Use the
1223 command @kbd{M-x eldoc-mode} to enable or disable this feature.
1226 @section Hideshow minor mode
1228 @findex hs-minor-mode
1229 Hideshow minor mode provides selective display of portions of a
1230 program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode}
1231 to enable or disable this mode, or add @code{hs-minor-mode} to the
1232 mode hook for certain major modes in order to enable it automatically
1235 Just what constitutes a block depends on the major mode. In C mode
1236 or C++ mode, they are delimited by braces, while in Lisp mode and
1237 similar modes they are delimited by parentheses. Multi-line comments
1238 also count as blocks.
1241 @findex hs-hide-block
1243 @findex hs-show-block
1244 @findex hs-show-region
1245 @findex hs-hide-level
1246 @findex hs-minor-mode
1249 @kindex C-c @@ C-M-h
1250 @kindex C-c @@ C-M-s
1256 Hide the current block (@code{hs-hide-block}).
1258 Show the current block (@code{hs-show-block}).
1260 Either hide or show the current block (@code{hs-toggle-hiding}).
1262 Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}).
1264 Hide all top-level blocks (@code{hs-hide-all}).
1266 Show everything in the buffer (@code{hs-show-all}).
1268 Hide all blocks @var{n} levels below this block
1269 (@code{hs-hide-level}).
1272 @vindex hs-hide-comments-when-hiding-all
1273 @vindex hs-isearch-open
1274 @vindex hs-special-modes-alist
1275 These variables exist for customizing Hideshow mode.
1278 @item hs-hide-comments-when-hiding-all
1279 Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too.
1281 @item hs-isearch-open
1282 Specifies what kind of hidden blocks incremental search should make
1283 visible. The value should be one of these four symbols:
1287 Open only code blocks.
1291 Open both code blocks and comments.
1293 Open neither code blocks nor comments.
1296 @item hs-special-modes-alist
1297 A list of elements, each specifying how to initialize Hideshow
1298 variables for one major mode. See the variable's documentation string
1299 for more information.
1302 @node Symbol Completion
1303 @section Completion for Symbol Names
1304 @cindex completion (symbol names)
1306 In Emacs, completion is something you normally do in the minibuffer.
1307 But one kind of completion is available in all buffers: completion for
1311 The character @kbd{M-@key{TAB}} runs a command to complete the
1312 partial symbol before point against the set of meaningful symbol
1313 names. This command inserts at point any additional characters that
1314 it can determine from the partial name. (If your window manager
1315 defines @kbd{M-@key{TAB}} to switch windows, you can type
1316 @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.)
1318 If the partial name in the buffer has multiple possible completions
1319 that differ in the very next character, so that it is impossible to
1320 complete even one more character, @kbd{M-@key{TAB}} displays a list of
1321 all possible completions in another window.
1323 @cindex tags-based completion
1324 @cindex Info index completion
1325 @findex complete-symbol
1326 In most programming language major modes, @kbd{M-@key{TAB}} runs the
1327 command @code{complete-symbol}, which provides two kinds of completion.
1328 Normally it does completion based on a tags table (@pxref{Tags}); with a
1329 numeric argument (regardless of the value), it does completion based on
1330 the names listed in the Info file indexes for your language. Thus, to
1331 complete the name of a symbol defined in your own program, use
1332 @kbd{M-@key{TAB}} with no argument; to complete the name of a standard
1333 library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based
1334 completion works only if there is an Info file for the standard library
1335 functions of your language, and only if it is installed at your site.
1337 @cindex Lisp symbol completion
1338 @cindex completion (Lisp symbols)
1339 @findex lisp-complete-symbol
1340 In Emacs-Lisp mode, the name space for completion normally consists of
1341 nontrivial symbols present in Emacs---those that have function
1342 definitions, values or properties. However, if there is an
1343 open-parenthesis immediately before the beginning of the partial symbol,
1344 only symbols with function definitions are considered as completions.
1345 The command which implements this is @code{lisp-complete-symbol}.
1347 In Text mode and related modes, @kbd{M-@key{TAB}} completes words
1348 based on the spell-checker's dictionary. @xref{Spelling}.
1351 @section Glasses minor mode
1352 @cindex Glasses mode
1353 @cindex identifiers, making long ones readable
1354 @cindex StudlyCaps, making them readable
1355 @findex glasses-mode
1357 Glasses minor mode makes @samp{unreadableIdentifiersLikeThis}
1358 readable by altering the way they display. It knows two different
1359 ways to do this: by displaying underscores between a lower-case letter
1360 and the following capital letter, and by emboldening the capital
1361 letters. It does not alter the buffer text, only the way they
1362 display, so you can use it even on read-only buffers. You can use the
1363 command @kbd{M-x glasses-mode} to enable or disable the mode in the
1364 current buffer; you can also add @code{glasses-mode} to the mode hook
1365 of the programming language major modes in which you normally want
1366 to use Glasses mode.
1368 @node Misc for Programs
1369 @section Other Features Useful for Editing Programs
1371 A number of Emacs commands that aren't designed specifically for
1372 editing programs are useful for that nonetheless.
1374 The Emacs commands that operate on words, sentences and paragraphs
1375 are useful for editing code. Most symbols names contain words
1376 (@pxref{Words}); sentences can be found in strings and comments
1377 (@pxref{Sentences}). Paragraphs in the strict sense can be found in
1378 program code (in long comments), but the paragraph commands are useful
1379 in other places too, because programming language major modes define
1380 paragraphs to begin and end at blank lines (@pxref{Paragraphs}).
1381 Judicious use of blank lines to make the program clearer will also
1382 provide useful chunks of text for the paragraph commands to work on.
1383 Auto Fill mode, if enabled in a programming language major mode,
1384 indents the new lines which it creates.
1386 The selective display feature is useful for looking at the overall
1387 structure of a function (@pxref{Selective Display}). This feature
1388 hides the lines that are indented more than a specified amount.
1389 Programming modes often support Outline minor mode (@pxref{Outline
1390 Mode}). The Foldout package provides folding-editor features
1393 The ``automatic typing'' features may be useful for writing programs.
1394 @xref{Top,,Autotyping, autotype, Autotyping}.
1397 @section C and Related Modes
1402 @cindex CORBA IDL mode
1403 @cindex Objective C mode
1409 @cindex mode, Objective C
1410 @cindex mode, CORBA IDL
1414 This section gives a brief description of the special features
1415 available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
1416 (These are called ``C mode and related modes.'') @xref{Top, , CC Mode,
1417 ccmode, CC Mode}, for a more extensive description of these modes
1418 and their special features.
1421 * Motion in C:: Commands to move by C statements, etc.
1422 * Electric C:: Colon and other chars can automatically reindent.
1423 * Hungry Delete:: A more powerful DEL command.
1424 * Other C Commands:: Filling comments, viewing expansion of macros,
1425 and other neat features.
1429 @subsection C Mode Motion Commands
1431 This section describes commands for moving point, in C mode and
1435 @item M-x c-beginning-of-defun
1436 @itemx M-x c-end-of-defun
1437 @findex c-beginning-of-defun
1438 @findex c-end-of-defun
1439 Move point to the beginning or end of the current function or
1440 top-level definition. These are found by searching for the least
1441 enclosing braces. (By contrast, @code{beginning-of-defun} and
1442 @code{end-of-defun} search for braces in column zero.) If you are
1443 editing code where the opening brace of a function isn't placed in
1444 column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to
1445 these commands. @xref{Moving by Defuns}.
1448 @kindex C-c C-u @r{(C mode)}
1449 @findex c-up-conditional
1450 Move point back to the containing preprocessor conditional, leaving the
1451 mark behind. A prefix argument acts as a repeat count. With a negative
1452 argument, move point forward to the end of the containing
1453 preprocessor conditional.
1455 @samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so
1456 the function will stop at a @samp{#elif} when going backward, but not
1460 @kindex C-c C-p @r{(C mode)}
1461 @findex c-backward-conditional
1462 Move point back over a preprocessor conditional, leaving the mark
1463 behind. A prefix argument acts as a repeat count. With a negative
1464 argument, move forward.
1467 @kindex C-c C-n @r{(C mode)}
1468 @findex c-forward-conditional
1469 Move point forward across a preprocessor conditional, leaving the mark
1470 behind. A prefix argument acts as a repeat count. With a negative
1471 argument, move backward.
1474 @kindex M-a (C mode)
1475 @findex c-beginning-of-statement
1476 Move point to the beginning of the innermost C statement
1477 (@code{c-beginning-of-statement}). If point is already at the beginning
1478 of a statement, move to the beginning of the preceding statement. With
1479 prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
1481 In comments or in strings which span more than one line, this command
1482 moves by sentences instead of statements.
1485 @kindex M-e (C mode)
1486 @findex c-end-of-statement
1487 Move point to the end of the innermost C statement or sentence; like
1488 @kbd{M-a} except that it moves in the other direction
1489 (@code{c-end-of-statement}).
1493 @subsection Electric C Characters
1495 In C mode and related modes, certain printing characters are
1496 @dfn{electric}---in addition to inserting themselves, they also
1497 reindent the current line, and optionally also insert newlines. The
1498 ``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#},
1499 @kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and
1502 You might find electric indentation inconvenient if you are editing
1503 chaotically indented code. If you are new to CC Mode, you might find
1504 it disconcerting. You can toggle electric action with the command
1505 @kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line
1506 after the mode name:
1510 @kindex C-c C-l @r{(C mode)}
1511 @findex c-toggle-electric-state
1512 Toggle electric action (@code{c-toggle-electric-state}). With a
1513 prefix argument, this command enables electric action if the argument
1514 is positive, disables it if it is negative.
1517 Electric characters insert newlines only when, in addition to the
1518 electric state, the @dfn{auto-newline} feature is enabled (indicated
1519 by @samp{/la} in the mode line after the mode name). You can turn
1520 this feature on or off with the command @kbd{C-c C-a}:
1524 @kindex C-c C-a @r{(C mode)}
1525 @findex c-toggle-auto-newline
1526 Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a
1527 prefix argument, this command turns the auto-newline feature on if the
1528 argument is positive, and off if it is negative.
1531 Usually the CC Mode style configures the exact circumstances in
1532 which Emacs inserts auto-newlines. You can also configure this
1533 directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}.
1536 @subsection Hungry Delete Feature in C
1537 @cindex hungry deletion (C Mode)
1539 If you want to delete an entire block of whitespace at point, you
1540 can use @dfn{hungry deletion}. This deletes all the contiguous
1541 whitespace either before point or after point in a single operation.
1542 @dfn{Whitespace} here includes tabs and newlines, but not comments or
1543 preprocessor commands.
1546 @item C-c C-@key{DEL}
1547 @itemx C-c @key{DEL}
1548 @findex c-hungry-backspace
1549 @kindex C-c C-@key{DEL} (C Mode)
1550 @kindex C-c @key{DEL} (C Mode)
1551 @code{c-hungry-backspace}---Delete the entire block of whitespace
1555 @itemx C-c C-@key{DELETE}
1556 @itemx C-c @key{DELETE}
1557 @findex c-hungry-delete-forward
1558 @kindex C-c C-d (C Mode)
1559 @kindex C-c C-@key{DELETE} (C Mode)
1560 @kindex C-c @key{DELETE} (C Mode)
1561 @code{c-hungry-delete-forward}---Delete the entire block of whitespace
1565 As an alternative to the above commands, you can enable @dfn{hungry
1566 delete mode}. When this feature is enabled (indicated by @samp{/h} in
1567 the mode line after the mode name), a single @key{DEL} deletes all
1568 preceding whitespace, not just one space, and a single @kbd{C-c C-d}
1569 (but @emph{not} plain @key{DELETE}) deletes all following whitespace.
1572 @item M-x c-toggle-hungry-state
1573 @findex c-toggle-hungry-state
1574 Toggle the hungry-delete feature
1575 (@code{c-toggle-hungry-state})@footnote{This command had the binding
1576 @kbd{C-c C-d} in earlier versions of Emacs. @kbd{C-c C-d} is now
1577 bound to @code{c-hungry-delete-forward}.}. With a prefix argument,
1578 this command turns the hungry-delete feature on if the argument is
1579 positive, and off if it is negative.
1582 @vindex c-hungry-delete-key
1583 The variable @code{c-hungry-delete-key} controls whether the
1584 hungry-delete feature is enabled.
1586 @node Other C Commands
1587 @subsection Other Commands for C Mode
1591 @itemx M-x c-subword-mode
1592 @findex c-subword-mode
1593 Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word
1594 commands then recognize upper case letters in
1595 @samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by
1596 the flag @samp{/w} on the mode line after the mode name
1597 (e.g. @samp{C/law}). You can even use @kbd{M-x c-subword-mode} in
1598 non-CC Mode buffers.
1600 In the GNU project, we recommend using underscores to separate words
1601 within an identifier in C or C++, rather than using case distinctions.
1603 @item M-x c-context-line-break
1604 @findex c-context-line-break
1605 This command inserts a line break and indents the new line in a manner
1606 appropriate to the context. In normal code, it does the work of
1607 @kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it
1608 additionally inserts a @samp{\} at the line break, and within comments
1609 it's like @kbd{M-j} (@code{c-indent-new-comment-line}).
1611 @code{c-context-line-break} isn't bound to a key by default, but it
1612 needs a binding to be useful. The following code will bind it to
1613 @kbd{C-j}. We use @code{c-initialization-hook} here to make sure
1614 the keymap is loaded before we try to change it.
1617 (defun my-bind-clb ()
1618 (define-key c-mode-base-map "\C-j" 'c-context-line-break))
1619 (add-hook 'c-initialization-hook 'my-bind-clb)
1623 Put mark at the end of a function definition, and put point at the
1624 beginning (@code{c-mark-function}).
1627 @kindex M-q @r{(C mode)}
1628 @findex c-fill-paragraph
1629 Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
1630 If any part of the current line is a comment or within a comment, this
1631 command fills the comment or the paragraph of it that point is in,
1632 preserving the comment indentation and comment delimiters.
1635 @cindex macro expansion in C
1636 @cindex expansion of C macros
1637 @findex c-macro-expand
1638 @kindex C-c C-e @r{(C mode)}
1639 Run the C preprocessor on the text in the region, and show the result,
1640 which includes the expansion of all the macro calls
1641 (@code{c-macro-expand}). The buffer text before the region is also
1642 included in preprocessing, for the sake of macros defined there, but the
1643 output from this part isn't shown.
1645 When you are debugging C code that uses macros, sometimes it is hard to
1646 figure out precisely how the macros expand. With this command, you
1647 don't have to figure it out; you can see the expansions.
1650 @findex c-backslash-region
1651 @kindex C-c C-\ @r{(C mode)}
1652 Insert or align @samp{\} characters at the ends of the lines of the
1653 region (@code{c-backslash-region}). This is useful after writing or
1654 editing a C macro definition.
1656 If a line already ends in @samp{\}, this command adjusts the amount of
1657 whitespace before it. Otherwise, it inserts a new @samp{\}. However,
1658 the last line in the region is treated specially; no @samp{\} is
1659 inserted on that line, and any @samp{\} there is deleted.
1661 @item M-x cpp-highlight-buffer
1662 @cindex preprocessor highlighting
1663 @findex cpp-highlight-buffer
1664 Highlight parts of the text according to its preprocessor conditionals.
1665 This command displays another buffer named @samp{*CPP Edit*}, which
1666 serves as a graphic menu for selecting how to display particular kinds
1667 of conditionals and their contents. After changing various settings,
1668 click on @samp{[A]pply these settings} (or go to that buffer and type
1669 @kbd{a}) to rehighlight the C mode buffer accordingly.
1672 @findex c-show-syntactic-information
1673 @kindex C-c C-s @r{(C mode)}
1674 Display the syntactic information about the current source line
1675 (@code{c-show-syntactic-information}). This information directs how
1676 the line is indented.
1678 @item M-x cwarn-mode
1679 @itemx M-x global-cwarn-mode
1681 @findex global-cwarn-mode
1682 @vindex global-cwarn-mode
1684 @cindex suspicious constructions in C, C++
1685 CWarn minor mode highlights certain suspicious C and C++ constructions:
1689 Assignments inside expressions.
1691 Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
1692 (except after a @samp{do @dots{} while} statement);
1694 C++ functions with reference parameters.
1698 You can enable the mode for one buffer with the command @kbd{M-x
1699 cwarn-mode}, or for all suitable buffers with the command @kbd{M-x
1700 global-cwarn-mode} or by customizing the variable
1701 @code{global-cwarn-mode}. You must also enable Font Lock mode to make
1704 @item M-x hide-ifdef-mode
1705 @findex hide-ifdef-mode
1706 @cindex Hide-ifdef mode
1707 Hide-ifdef minor mode hides selected code within @samp{#if} and
1708 @samp{#ifdef} preprocessor blocks. See the documentation string of
1709 @code{hide-ifdef-mode} for more information.
1711 @item M-x ff-find-related-file
1712 @cindex related files
1713 @findex ff-find-related-file
1714 @vindex ff-related-file-alist
1715 Find a file ``related'' in a special way to the file visited by the
1716 current buffer. Typically this will be the header file corresponding
1717 to a C/C++ source file, or vice versa. The variable
1718 @code{ff-related-file-alist} specifies how to compute related file
1726 @cindex assembler mode
1727 Asm mode is a major mode for editing files of assembler code. It
1728 defines these commands:
1732 @code{tab-to-tab-stop}.
1734 Insert a newline and then indent using @code{tab-to-tab-stop}.
1736 Insert a colon and then remove the indentation from before the label
1737 preceding colon. Then do @code{tab-to-tab-stop}.
1739 Insert or align a comment.
1742 The variable @code{asm-comment-char} specifies which character
1743 starts comments in assembler syntax.
1746 arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0