1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2011
3 @c 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 This chapter describes Emacs features for facilitating editing
12 programs. Some of these features can:
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}).
29 * Program Modes:: Major modes for editing programs.
30 * Defuns:: Commands to operate on major top-level parts
32 * Program Indent:: Adjusting indentation to show the nesting.
33 * Parentheses:: Commands that operate on parentheses.
34 * Comments:: Inserting, killing, and aligning comments.
35 * Documentation:: Getting documentation of functions you plan to call.
36 * Hideshow:: Displaying blocks selectively.
37 * Symbol Completion:: Completion on symbol names of your program or language.
38 * Glasses:: Making identifiersLikeThis more readable.
39 * Semantic:: Suite of editing tools based on source code parsing.
40 * Misc for Programs:: Other Emacs features useful for editing programs.
41 * C Modes:: Special commands of C, C++, Objective-C,
43 * Asm Mode:: Asm mode and its special features.
45 * Fortran:: Fortran mode and its special features.
50 @section Major Modes for Programming Languages
51 @cindex modes for programming languages
53 Emacs has specialized major modes (@pxref{Major Modes}) for many
54 programming languages. A programming language mode typically
55 specifies the syntax of expressions, the customary rules for
56 indentation, how to do syntax highlighting for the language, and how
57 to find the beginning or end of a function definition. It often has
58 features for compiling and debugging programs as well. The major mode
59 for each language is named after the language; for instance, the major
60 mode for the C programming language is @code{c-mode}.
77 @cindex Shell-script mode
79 @cindex PostScript mode
82 @cindex Javascript mode
83 Emacs has programming language modes for Lisp, Scheme, the
84 Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Delphi,
85 Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont
86 (@TeX{}'s companion for font creation), Modula2, Objective-C, Octave,
87 Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl, and
88 VHDL. An alternative mode for Perl is called CPerl mode. Modes are
89 also available for the scripting languages of the common GNU and Unix
90 shells, VMS DCL, and MS-DOS/MS-Windows @samp{BAT} files, and for
91 makefiles, DNS master files, and various sorts of configuration files.
93 Ideally, Emacs should have a major mode for each programming
94 language that you might want to edit. If it doesn't have a mode for
95 your favorite language, the mode might be implemented in a package not
96 distributed with Emacs (@pxref{Packages}); or you can contribute one.
98 @kindex DEL @r{(programming modes)}
99 @findex c-electric-backspace
100 @findex backward-delete-char-untabify
101 In most programming languages, indentation should vary from line to
102 line to illustrate the structure of the program. Therefore, in most
103 programming language modes, typing @key{TAB} updates the indentation
104 of the current line (@pxref{Program Indent}). Furthermore, @key{DEL}
105 is usually bound to @code{backward-delete-char-untabify}, which
106 deletes backward treating each tab as if it were the equivalent number
107 of spaces, so that you can delete one column of indentation without
108 worrying whether the whitespace consists of spaces or tabs.
112 @vindex lisp-mode-hook
113 @vindex emacs-lisp-mode-hook
114 @vindex lisp-interaction-mode-hook
115 @vindex scheme-mode-hook
116 Entering a programming language mode runs the custom Lisp functions
117 specified in the hook variable @code{prog-mode-hook}, followed by
118 those specified in the mode's own mode hook (@pxref{Major Modes}).
119 For instance, entering C mode runs the hooks @code{prog-mode-hook} and
120 @code{c-mode-hook}. @xref{Hooks}, for information about hooks.
123 Separate manuals are available for the modes for Ada (@pxref{Top,,
124 Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba
125 IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), and IDLWAVE
126 (@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}).
129 The Emacs distribution contains Info manuals for the major modes for
130 Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE. For
131 Fortran mode, see the ``Fortran'' section in the Info version of the
132 Emacs manual, which is not included in this printed version.
136 @section Top-Level Definitions, or Defuns
138 In Emacs, a major definition at the top level in the buffer, such as
139 a function, is called a @dfn{defun}. The name comes from Lisp, but in
140 Emacs we use it for all languages.
143 * Left Margin Paren:: An open-paren or similar opening delimiter
144 starts a defun if it is at the left margin.
145 * Moving by Defuns:: Commands to move over or mark a major definition.
146 * Imenu:: Making buffer indexes as menus.
147 * Which Function:: Which Function mode shows which function you are in.
150 @node Left Margin Paren
151 @subsection Left Margin Convention
153 @cindex open-parenthesis in leftmost column
154 @cindex ( in leftmost column
155 Many programming-language modes assume by default that any opening
156 delimiter found at the left margin is the start of a top-level
157 definition, or defun. Therefore, @strong{don't put an opening
158 delimiter at the left margin unless it should have that significance}.
159 For instance, never put an open-parenthesis at the left margin in a
160 Lisp file unless it is the start of a top-level list.
162 The convention speeds up many Emacs operations, which would
163 otherwise have to scan back to the beginning of the buffer to analyze
164 the syntax of the code.
166 If you don't follow this convention, not only will you have trouble
167 when you explicitly use the commands for motion by defuns; other
168 features that use them will also give you trouble. This includes the
169 indentation commands (@pxref{Program Indent}) and Font Lock mode
172 The most likely problem case is when you want an opening delimiter
173 at the start of a line inside a string. To avoid trouble, put an
174 escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some
175 other Lisp dialects) before the opening delimiter. This will not
176 affect the contents of the string, but will prevent that opening
177 delimiter from starting a defun. Here's an example:
185 To help you catch violations of this convention, Font Lock mode
186 highlights confusing opening delimiters (those that ought to be
189 If you need to override this convention, you can do so by setting
192 @defvar open-paren-in-column-0-is-defun-start
193 If this user option is set to @code{t} (the default), opening
194 parentheses or braces at column zero always start defuns. When it's
195 @code{nil}, defuns are found by searching for parens or braces at the
199 Usually, you should leave this option at its default value of
200 @code{t}. If your buffer contains parentheses or braces in column
201 zero which don't start defuns, and it is somehow impractical to remove
202 these parentheses or braces, it might be helpful to set the option to
203 @code{nil}. Be aware that this might make scrolling and display in
204 large buffers quite sluggish. Furthermore, the parentheses and braces
205 must be correctly matched throughout the buffer for it to work
208 @node Moving by Defuns
209 @subsection Moving by Defuns
212 These commands move point or set up the region based on top-level
213 major definitions, also called @dfn{defuns}.
217 Move to beginning of current or preceding defun
218 (@code{beginning-of-defun}).
220 Move to end of current or following defun (@code{end-of-defun}).
222 Put region around whole current or following defun (@code{mark-defun}).
225 @cindex move to beginning or end of function
226 @cindex function, move to beginning or end
230 @findex beginning-of-defun
233 The commands to move to the beginning and end of the current defun
234 are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e}
235 (@code{end-of-defun}). If you repeat one of these commands, or use a
236 positive numeric argument, each repetition moves to the next defun in
237 the direction of motion.
239 @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward
240 @var{n} times to the next beginning of a defun. This is not exactly
241 the same place that @kbd{C-M-e} with argument @var{n} would move to;
242 the end of this defun is not usually exactly the same place as the
243 beginning of the following defun. (Whitespace, comments, and perhaps
244 declarations can separate them.) Likewise, @kbd{C-M-e} with a
245 negative argument moves back to an end of a defun, which is not quite
246 the same as @kbd{C-M-a} with a positive argument.
248 @kindex C-M-h @r{(C mode)}
249 @findex c-mark-function
250 To operate on the current defun, use @kbd{C-M-h}
251 (@code{mark-defun}), which sets the mark at the end of the current
252 defun and puts point at its beginning. @xref{Marking Objects}. This
253 is the easiest way to get ready to kill the defun in order to move it
254 to a different place in the file. If you use the command while point
255 is between defuns, it uses the following defun. If you use the
256 command while the mark is already active, it sets the mark but does
257 not move point; furthermore, each successive use of @kbd{C-M-h}
258 extends the end of the region to include one more defun.
260 In C mode, @kbd{C-M-h} runs the function @code{c-mark-function},
261 which is almost the same as @code{mark-defun}; the difference is that
262 it backs up over the argument declarations, function name and returned
263 data type so that the entire C function is inside the region. This is
264 an example of how major modes adjust the standard key bindings so that
265 they do their standard jobs in a way better fitting a particular
266 language. Other major modes may replace any or all of these key
267 bindings for that purpose.
271 @cindex index of buffer definitions
272 @cindex buffer definitions index
274 The Imenu facility offers a way to find the major definitions in
275 a file by name. It is also useful in text formatter major modes,
276 where it treats each chapter, section, etc., as a definition.
277 (@xref{Tags}, for a more powerful feature that handles multiple files
281 If you type @kbd{M-x imenu}, it reads the name of a definition using
282 the minibuffer, then moves point to that definition. You can use
283 completion to specify the name; the command always displays the whole
286 @findex imenu-add-menubar-index
287 Alternatively, you can bind the command @code{imenu} to a mouse
288 click. Then it displays mouse menus for you to select a definition
289 name. You can also add the buffer's index to the menu bar by calling
290 @code{imenu-add-menubar-index}. If you want to have this menu bar
291 item available for all buffers in a certain major mode, you can do
292 this by adding @code{imenu-add-menubar-index} to its mode hook. But
293 if you have done that, you will have to wait a little while each time
294 you visit a file in that mode, while Emacs finds all the definitions
297 @vindex imenu-auto-rescan
298 When you change the contents of a buffer, if you add or delete
299 definitions, you can update the buffer's index based on the
300 new contents by invoking the @samp{*Rescan*} item in the menu.
301 Rescanning happens automatically if you set @code{imenu-auto-rescan} to
302 a non-@code{nil} value. There is no need to rescan because of small
305 @vindex imenu-sort-function
306 You can customize the way the menus are sorted by setting the
307 variable @code{imenu-sort-function}. By default, names are ordered as
308 they occur in the buffer; if you want alphabetic sorting, use the
309 symbol @code{imenu--sort-by-name} as the value. You can also
310 define your own comparison function by writing Lisp code.
312 Imenu provides the information to guide Which Function mode
314 (@pxref{Which Function}).
319 The Speedbar can also use it (@pxref{Speedbar}).
322 @subsection Which Function Mode
323 @cindex current function name in mode line
325 Which Function mode is a global minor mode (@pxref{Minor Modes})
326 which displays the current function name in the mode line, updating it
327 as you move around in a buffer.
329 @findex which-function-mode
330 @vindex which-func-modes
331 To either enable or disable Which Function mode, use the command
332 @kbd{M-x which-function-mode}. Although Which Function mode is a
333 global minor mode, it takes effect only in certain major modes: those
334 listed in the variable @code{which-func-modes}. If the value of
335 @code{which-func-modes} is @code{t} rather than a list of modes, then
336 Which Function mode applies to all major modes that know how to
337 support it---in other words, all the major modes that support Imenu.
340 @section Indentation for Programs
341 @cindex indentation for programs
343 The best way to keep a program properly indented is to use Emacs to
344 reindent it as you change it. Emacs has commands to indent either a
345 single line, a specified number of lines, or all of the lines inside a
346 single parenthetical grouping.
348 @xref{Indentation}, for general information about indentation. This
349 section describes indentation features specific to programming
353 * Basic Indent:: Indenting a single line.
354 * Multi-line Indent:: Commands to reindent many lines at once.
355 * Lisp Indent:: Specifying how each Lisp function should be indented.
356 * C Indent:: Extra features for indenting C and related modes.
357 * Custom C Indent:: Controlling indentation style for C and related modes.
360 @cindex pretty-printer
361 Emacs also provides a Lisp pretty-printer in the @code{pp} package,
362 which reformats Lisp objects with nice-looking indentation.
365 @subsection Basic Program Indentation Commands
369 Adjust indentation of current line (@code{indent-for-tab-command}).
371 Insert a newline, then adjust indentation of following line
372 (@code{newline-and-indent}).
375 @kindex TAB @r{(programming modes)}
376 @findex c-indent-command
377 @findex indent-line-function
378 @findex indent-for-tab-command
379 The basic indentation command is @key{TAB}
380 (@code{indent-for-tab-command}), which was documented in
381 @ref{Indentation}. In programming language modes, @key{TAB} indents
382 the current line, based on the indentation and syntactic content of
383 the preceding lines; if the region is active, @key{TAB} indents each
384 line within the region, not just the current line.
386 @kindex C-j @r{(indenting source code)}
387 @findex newline-and-indent
388 The command @kbd{C-j} (@code{newline-and-indent}), which was
389 documented in @ref{Indentation Commands}, does the same as @key{RET}
390 followed by @key{TAB}: it inserts a new line, then adjusts the line's
393 When indenting a line that starts within a parenthetical grouping,
394 Emacs usually places the start of the line under the preceding line
395 within the group, or under the text after the parenthesis. If you
396 manually give one of these lines a nonstandard indentation (e.g.@: for
397 aesthetic purposes), the lines below will follow it.
399 The indentation commands for most programming language modes assume
400 that a open-parenthesis, open-brace or other opening delimiter at the
401 left margin is the start of a function. If the code you are editing
402 violates this assumption---even if the delimiters occur in strings or
403 comments---you must set @code{open-paren-in-column-0-is-defun-start}
404 to @code{nil} for indentation to work properly. @xref{Left Margin
407 @node Multi-line Indent
408 @subsection Indenting Several Lines
410 Sometimes, you may want to reindent several lines of code at a time.
411 One way to do this is to use the mark; when the mark is active and the
412 region is non-empty, @key{TAB} indents every line in the region.
413 Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents
414 every line in the region, whether or not the mark is active
415 (@pxref{Indentation Commands}).
417 In addition, Emacs provides the following commands for indenting
418 large chunks of code:
422 Reindent all the lines within one parenthetical grouping.
424 Shift an entire parenthetical grouping rigidly sideways so that its
425 first line is properly indented.
426 @item M-x indent-code-rigidly
427 Shift all the lines in the region rigidly sideways, but do not alter
428 lines that start inside comments and strings.
432 @findex indent-pp-sexp
433 To reindent the contents of a single parenthetical grouping,
434 position point before the beginning of the grouping and type
435 @kbd{C-M-q}. This changes the relative indentation within the
436 grouping, without affecting its overall indentation (i.e.@: the
437 indentation of the line where the grouping starts). The function that
438 @kbd{C-M-q} runs depends on the major mode; it is
439 @code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode,
440 etc. To correct the overall indentation as well, type @key{TAB}
444 If you like the relative indentation within a grouping but not the
445 indentation of its first line, move point to that first line and type
446 @kbd{C-u @key{TAB}}. In Lisp, C, and some other major modes,
447 @key{TAB} with a numeric argument reindents the current line as usual,
448 then reindents by the same amount all the lines in the parenthetical
449 grouping starting on the current line. It is clever, though, and does
450 not alter lines that start inside strings. Neither does it alter C
451 preprocessor lines when in C mode, but it does reindent any
452 continuation lines that may be attached to them.
454 @findex indent-code-rigidly
455 The command @kbd{M-x indent-code-rigidly} rigidly shifts all the
456 lines in the region sideways, like @code{indent-rigidly} does
457 (@pxref{Indentation Commands}). It doesn't alter the indentation of
458 lines that start inside a string, unless the region also starts inside
459 that string. The prefix arg specifies the number of columns to
463 @subsection Customizing Lisp Indentation
464 @cindex customizing Lisp indentation
466 The indentation pattern for a Lisp expression can depend on the function
467 called by the expression. For each Lisp function, you can choose among
468 several predefined patterns of indentation, or define an arbitrary one with
471 The standard pattern of indentation is as follows: the second line of the
472 expression is indented under the first argument, if that is on the same
473 line as the beginning of the expression; otherwise, the second line is
474 indented underneath the function name. Each following line is indented
475 under the previous line whose nesting depth is the same.
477 @vindex lisp-indent-offset
478 If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
479 the usual indentation pattern for the second line of an expression, so that
480 such lines are always indented @code{lisp-indent-offset} more columns than
483 @vindex lisp-body-indent
484 Certain functions override the standard pattern. Functions whose
485 names start with @code{def} treat the second lines as the start of
486 a @dfn{body}, by indenting the second line @code{lisp-body-indent}
487 additional columns beyond the open-parenthesis that starts the
490 @cindex @code{lisp-indent-function} property
491 You can override the standard pattern in various ways for individual
492 functions, according to the @code{lisp-indent-function} property of
493 the function name. This is normally done for macro definitions, using
494 the @code{declare} construct. @xref{Defining Macros,,, elisp, the
495 Emacs Lisp Reference Manual}.
498 @subsection Commands for C Indentation
500 Here are special features for indentation in C mode and related modes:
504 @kindex C-c C-q @r{(C mode)}
505 @findex c-indent-defun
506 Reindent the current top-level function definition or aggregate type
507 declaration (@code{c-indent-defun}).
510 @kindex C-M-q @r{(C mode)}
512 Reindent each line in the balanced expression that follows point
513 (@code{c-indent-exp}). A prefix argument inhibits warning messages
514 about invalid syntax.
517 @findex c-indent-command
518 Reindent the current line, and/or in some cases insert a tab character
519 (@code{c-indent-command}).
521 @vindex c-tab-always-indent
522 If @code{c-tab-always-indent} is @code{t}, this command always reindents
523 the current line and does nothing else. This is the default.
525 If that variable is @code{nil}, this command reindents the current line
526 only if point is at the left margin or in the line's indentation;
527 otherwise, it inserts a tab (or the equivalent number of spaces,
528 if @code{indent-tabs-mode} is @code{nil}).
530 Any other value (not @code{nil} or @code{t}) means always reindent the
531 line, and also insert a tab if within a comment or a string.
534 To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This
535 first selects the whole buffer as the region, then reindents that
538 To reindent the current block, use @kbd{C-M-u C-M-q}. This moves
539 to the front of the block and then reindents it all.
541 @node Custom C Indent
542 @subsection Customizing C Indentation
543 @cindex style (for indentation)
545 C mode and related modes use a flexible mechanism for customizing
546 indentation. C mode indents a source line in two steps: first it
547 classifies the line syntactically according to its contents and
548 context; second, it determines the indentation offset associated by
549 your selected @dfn{style} with the syntactic construct and adds this
550 onto the indentation of the @dfn{anchor statement}.
553 @item C-c . @key{RET} @var{style} @key{RET}
554 Select a predefined style @var{style} (@code{c-set-style}).
557 A @dfn{style} is a named collection of customizations that can be
558 used in C mode and the related modes. @ref{Styles,,, ccmode, The CC
559 Mode Manual}, for a complete description. Emacs comes with several
560 predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
561 @code{stroustrup}, @code{linux}, @code{python}, @code{java},
562 @code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these
563 styles are primarily intended for one language, but any of them can be
564 used with any of the languages supported by these modes. To find out
565 what a style looks like, select it and reindent some code, e.g., by
566 typing @key{C-M-q} at the start of a function definition.
568 @kindex C-c . @r{(C mode)}
570 To choose a style for the current buffer, use the command @w{@kbd{C-c
571 .}}. Specify a style name as an argument (case is not significant).
572 This command affects the current buffer only, and it affects only
573 future invocations of the indentation commands; it does not reindent
574 the code already in the buffer. To reindent the whole buffer in the
575 new style, you can type @kbd{C-x h C-M-\}.
577 @vindex c-default-style
578 You can also set the variable @code{c-default-style} to specify the
579 default style for various major modes. Its value should be either the
580 style's name (a string) or an alist, in which each element specifies
581 one major mode and which indentation style to use for it. For
585 (setq c-default-style
586 '((java-mode . "java")
592 specifies explicit choices for Java and AWK modes, and the default
593 @samp{gnu} style for the other C-like modes. (These settings are
594 actually the defaults.) This variable takes effect when you select
595 one of the C-like major modes; thus, if you specify a new default
596 style for Java mode, you can make it take effect in an existing Java
597 mode buffer by typing @kbd{M-x java-mode} there.
599 The @code{gnu} style specifies the formatting recommended by the GNU
600 Project for C; it is the default, so as to encourage use of our
603 @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and
604 @ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more
605 information on customizing indentation for C and related modes,
606 including how to override parts of an existing style and how to define
610 @section Commands for Editing with Parentheses
613 @cindex unbalanced parentheses and quotes
614 This section describes the commands and features that take advantage
615 of the parenthesis structure in a program, or help you keep it
618 When talking about these facilities, the term ``parenthesis'' also
619 includes braces, brackets, or whatever delimiters are defined to match
620 in pairs. The major mode controls which delimiters are significant,
621 through the syntax table (@pxref{Syntax Tables,, Syntax Tables, elisp,
622 The Emacs Lisp Reference Manual}). In Lisp, only parentheses count;
623 in C, these commands apply to braces and brackets too.
625 You can use @kbd{M-x check-parens} to find any unbalanced
626 parentheses and unbalanced string quotes in the buffer.
629 * Expressions:: Expressions with balanced parentheses.
630 * Moving by Parens:: Commands for moving up, down and across
631 in the structure of parentheses.
632 * Matching:: Insertion of a close-delimiter flashes matching open.
636 @subsection Expressions with Balanced Parentheses
640 @cindex balanced expression
641 Each programming language mode has its own definition of a
642 @dfn{balanced expression}. Balanced expressions typically include
643 individual symbols, numbers, and string constants, as well as pieces
644 of code enclosed in a matching pair of delimiters. The following
645 commands deal with balanced expressions (in Emacs, such expressions
646 are referred to internally as @dfn{sexps}@footnote{The word ``sexp''
647 is used to refer to an expression in Lisp.}).
651 Move forward over a balanced expression (@code{forward-sexp}).
653 Move backward over a balanced expression (@code{backward-sexp}).
655 Kill balanced expression forward (@code{kill-sexp}).
657 Transpose expressions (@code{transpose-sexps}).
660 Put mark after following expression (@code{mark-sexp}).
666 @findex backward-sexp
667 To move forward over a balanced expression, use @kbd{C-M-f}
668 (@code{forward-sexp}). If the first significant character after point
669 is an opening delimiter (e.g.@: @samp{(}, @samp{[} or @samp{@{} in C),
670 this command moves past the matching closing delimiter. If the
671 character begins a symbol, string, or number, the command moves over
674 The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
675 balanced expression---like @kbd{C-M-f}, but in the reverse direction.
676 If the expression is preceded by any prefix characters (single-quote,
677 backquote and comma, in Lisp), the command moves back over them as
680 @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation
681 the specified number of times; with a negative argument means to move
682 in the opposite direction. In most modes, these two commands move
683 across comments as if they were whitespace. Note that their keys,
684 @kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b},
685 which move by characters (@pxref{Moving Point}), and @kbd{M-f} and
686 @kbd{M-b}, which move by words (@pxref{Words}).
688 @cindex killing expressions
691 To kill a whole balanced expression, type @kbd{C-M-k}
692 (@code{kill-sexp}). This kills the text that @kbd{C-M-f} would move
695 @cindex transposition of expressions
697 @findex transpose-sexps
698 @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the
699 previous balanced expression and the next one. It is analogous to the
700 @kbd{C-t} command, which transposes characters (@pxref{Transpose}).
701 An argument to @kbd{C-M-t} serves as a repeat count, moving the
702 previous expression over that many following ones. A negative
703 argument moves the previous balanced expression backwards across those
704 before it. An argument of zero, rather than doing nothing, transposes
705 the balanced expressions ending at or after point and the mark.
708 @kindex C-M-@key{SPC}
710 To operate on balanced expressions with a command which acts on the
711 region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}). This sets the
712 mark where @kbd{C-M-f} would move to. While the mark is active, each
713 successive call to this command extends the region by shifting the
714 mark by one expression. Positive or negative numeric arguments move
715 the mark forward or backward by the specified number of expressions.
716 The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}.
717 @xref{Marking Objects}, for more information about this and related
720 In languages that use infix operators, such as C, it is not possible
721 to recognize all balanced expressions because there can be multiple
722 possibilities at a given position. For example, C mode does not treat
723 @samp{foo + bar} as a single expression, even though it @emph{is} one
724 C expression; instead, it recognizes @samp{foo} as one expression and
725 @samp{bar} as another, with the @samp{+} as punctuation between them.
726 However, C mode recognizes @samp{(foo + bar)} as a single expression,
727 because of the parentheses.
729 @node Moving by Parens
730 @subsection Moving in the Parenthesis Structure
732 @cindex parenthetical groupings
733 @cindex parentheses, moving across
734 @cindex matching parenthesis and braces, moving to
735 @cindex braces, moving across
736 @cindex list commands
738 The following commands move over groupings delimited by parentheses
739 (or whatever else serves as delimiters in the language you are working
740 with). They ignore strings and comments, including any parentheses
741 within them, and also ignore parentheses that are ``quoted'' with an
742 escape character. These commands are mainly intended for editing
743 programs, but can be useful for editing any text containing
744 parentheses. They are referred to internally as ``list'' commands
745 because in Lisp these groupings are lists.
747 These commands assume that the starting point is not inside a string
748 or a comment. If you invoke them from inside a string or comment, the
749 results are unreliable.
753 Move forward over a parenthetical group (@code{forward-list}).
755 Move backward over a parenthetical group (@code{backward-list}).
757 Move up in parenthesis structure (@code{backward-up-list}).
759 Move down in parenthesis structure (@code{down-list}).
765 @findex backward-list
766 The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and
767 @kbd{C-M-p} (@code{backward-list}) move forward or backward over one
768 (or @var{n}) parenthetical groupings.
771 @findex backward-up-list
772 @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
773 parenthesis structure. To move @emph{up} one (or @var{n}) levels, use
774 @kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up
775 past one unmatched opening delimiter. A positive argument serves as a
776 repeat count; a negative argument reverses the direction of motion, so
777 that the command moves forward and up one or more levels.
781 To move @emph{down} in the parenthesis structure, use @kbd{C-M-d}
782 (@code{down-list}). In Lisp mode, where @samp{(} is the only opening
783 delimiter, this is nearly the same as searching for a @samp{(}. An
784 argument specifies the number of levels to go down.
787 @subsection Matching Parentheses
788 @cindex matching parentheses
789 @cindex parentheses, displaying matches
791 Emacs has a number of @dfn{parenthesis matching} features, which
792 make it easy to see how and whether parentheses (or other delimiters)
795 Whenever you type a self-inserting character that is a closing
796 delimiter, the cursor moves momentarily to the location of the
797 matching opening delimiter, provided that is on the screen. If it is
798 not on the screen, Emacs displays some of the text near it in the echo
799 area. Either way, you can tell which grouping you are closing off.
800 If the opening delimiter and closing delimiter are mismatched---such
801 as in @samp{[x)}---a warning message is displayed in the echo area.
803 @vindex blink-matching-paren
804 @vindex blink-matching-paren-distance
805 @vindex blink-matching-delay
806 Three variables control the display of matching parentheses:
810 @code{blink-matching-paren} turns the feature on or off: @code{nil}
811 disables it, but the default is @code{t} to enable it.
814 @code{blink-matching-delay} says how many seconds to leave the cursor
815 on the matching opening delimiter, before bringing it back to the real
816 location of point. This may be an integer or floating-point number;
820 @code{blink-matching-paren-distance} specifies how many characters
821 back to search to find the matching opening delimiter. If the match
822 is not found in that distance, Emacs stops scanning and nothing is
823 displayed. The default is 102400.
826 @cindex Show Paren mode
827 @cindex highlighting matching parentheses
828 @findex show-paren-mode
829 Show Paren mode, a global minor mode, provides a more powerful kind
830 of automatic matching. Whenever point is before an opening delimiter
831 or after a closing delimiter, both that delimiter and its opposite
832 delimiter are highlighted. To toggle Show Paren mode, type @kbd{M-x
835 @cindex Electric Pair mode
836 @cindex inserting matching parentheses
837 @findex electric-pair-mode
838 Electric Pair mode, a global minor mode, provides a way to easily
839 insert matching delimiters. Whenever you insert an opening delimiter,
840 the matching closing delimiter is automatically inserted as well,
841 leaving point between the two. To toggle Electric Pair mode, type
842 @kbd{M-x electric-pair-mode}.
845 @section Manipulating Comments
848 Because comments are such an important part of programming, Emacs
849 provides special commands for editing and inserting comments. It can
850 also do spell checking on comments with Flyspell Prog mode
853 Some major modes have special rules for indenting different kinds of
854 comments. For example, in Lisp code, comments starting with two
855 semicolons are indented as if they were lines of code, while those
856 starting with three semicolons are supposed to be aligned to the left
857 margin and are often used for sectioning purposes. Emacs understand
858 these conventions; for instance, typing @key{TAB} on a comment line
859 will indent the comment to the appropriate position.
862 ;; This function is just an example.
863 ;;; Here either two or three semicolons are appropriate.
865 ;;; And now, the first part of the function:
866 ;; The following line adds one.
867 (1+ x)) ; This line adds one.
871 * Comment Commands:: Inserting, killing, and aligning comments.
872 * Multi-Line Comments:: Commands for adding and editing multi-line comments.
873 * Options for Comments::Customizing the comment features.
876 @node Comment Commands
877 @subsection Comment Commands
878 @cindex indentation for comments
879 @cindex alignment for comments
881 The following commands operate on comments:
885 Insert or realign comment on current line; if the region is active,
886 comment or uncomment the region instead (@code{comment-dwim}).
888 Kill comment on current line (@code{comment-kill}).
890 Set comment column (@code{comment-set-column}).
893 Like @key{RET} followed by inserting and aligning a comment
894 (@code{comment-indent-new-line}). @xref{Multi-Line Comments}.
895 @item @kbd{M-x comment-region}
896 @itemx @kbd{C-c C-c} (in C-like modes)
897 Add comment delimiters to all the lines in the region.
902 The command to create or align a comment is @kbd{M-;}
903 (@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What
904 I Mean''; it indicates that this command can be used for many
905 different jobs relating to comments, depending on the situation where
908 When a region is active (@pxref{Mark}), @kbd{M-;} either adds
909 comment delimiters to the region, or removes them. If every line in
910 the region is already a comment, it ``uncomments'' each of those lines
911 by removing their comment delimiters. Otherwise, it adds comment
912 delimiters to enclose the text in the region.
914 If you supply a prefix argument to @kbd{M-;} when a region is
915 active, that specifies the number of comment delimiters to add or
916 delete. A positive argument @var{n} adds @var{n} delimiters, while a
917 negative argument @var{-n} removes @var{n} delimiters.
919 If the region is not active, and there is no existing comment on the
920 current line, @kbd{M-;} adds a new comment to the current line. If
921 the line is blank (i.e.@: empty or containing only whitespace
922 characters), the comment is indented to the same position where
923 @key{TAB} would indent to (@pxref{Basic Indent}). If the line is
924 non-blank, the comment is placed after the last non-whitespace
925 character on the line; normally, Emacs tries putting it at the column
926 specified by the variable @code{comment-column} (@pxref{Options for
927 Comments}), but if the line already extends past that column, it puts
928 the comment at some suitable position, usually separated from the
929 non-comment text by at least one space. In each case, Emacs places
930 point after the comment's starting delimiter, so that you can start
931 typing the comment text right away.
933 You can also use @kbd{M-;} to align an existing comment. If a line
934 already contains the comment-start string, @kbd{M-;} realigns it to
935 the conventional alignment and moves point after the comment's
936 starting delimiter. As an exception, comments starting in column 0
937 are not moved. Even when an existing comment is properly aligned,
938 @kbd{M-;} is still useful for moving directly to the start of the
943 @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any
944 comment on the current line, along with the whitespace before it.
945 Since the comment is saved to the kill ring, you can reinsert it on
946 another line by moving to the end of that line, doing @kbd{C-y}, and
947 then @kbd{M-;} to realign the command. You can achieve the same
948 effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill}
949 (@code{comment-dwim} actually calls @code{comment-kill} as a
950 subroutine when it is given a prefix argument).
952 @kindex C-c C-c (C mode)
953 @findex comment-region
954 @findex uncomment-region
955 The command @kbd{M-x comment-region} is equivalent to calling
956 @kbd{M-;} on an active region, except that it always acts on the
957 region, even if the mark is inactive. In C mode and related modes,
958 this command is bound to @kbd{C-c C-c}. The command @kbd{M-x
959 uncomment-region} uncomments each line in the region; a numeric prefix
960 argument specifies the number of comment delimiters to remove
961 (negative arguments specify the number of comment to delimiters to
964 For C-like modes, you can configure the exact effect of @kbd{M-;} by
965 setting the variables @code{c-indent-comment-alist} and
966 @code{c-indent-comments-syntactically-p}. For example, on a line
967 ending in a closing brace, @kbd{M-;} puts the comment one space after
968 the brace rather than at @code{comment-column}. For full details see
969 @ref{Comment Commands,,, ccmode, The CC Mode Manual}.
971 @node Multi-Line Comments
972 @subsection Multiple Lines of Comments
976 @cindex blank lines in programs
977 @findex comment-indent-new-line
978 @vindex comment-multi-line
979 If you are typing a comment and wish to continue it to another line,
980 type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}). This
981 breaks the current line, and inserts the necessary comment delimiters
982 and indentation to continue the comment.
984 For languages with closing comment delimiters (e.g.@: @samp{*/} in
985 C), the exact behavior of @kbd{M-j} depends on the value of the
986 variable @code{comment-multi-line}. If the value is @code{nil}, the
987 command closes the comment on the old line and starts a new comment on
988 the new line. Otherwise, it opens a new line within the current
991 When Auto Fill mode is on, going past the fill column while typing a
992 comment also continues the comment, in the same way as an explicit
993 invocation of @kbd{M-j}.
995 To turn existing lines into comment lines, use @kbd{M-;} with the
996 region active, or use @kbd{M-x comment-region}
998 (@pxref{Comment Commands}).
1001 as described in the preceding section.
1004 You can configure C Mode such that when you type a @samp{/} at the
1005 start of a line in a multi-line block comment, this closes the
1006 comment. Enable the @code{comment-close-slash} clean-up for this.
1007 @xref{Clean-ups,,, ccmode, The CC Mode Manual}.
1009 @node Options for Comments
1010 @subsection Options Controlling Comments
1012 @vindex comment-column
1014 @findex comment-set-column
1015 As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command
1016 adds a comment to a line, it tries to place the comment at the column
1017 specified by the buffer-local variable @code{comment-column}. You can
1018 set either the local value or the default value of this buffer-local
1019 variable in the usual way (@pxref{Locals}). Alternatively, you can
1020 type @kbd{C-x ;} (@code{comment-set-column}) to set the value of
1021 @code{comment-column} in the current buffer to the column where point
1022 is currently located. @kbd{C-u C-x ;} sets the comment column to
1023 match the last comment before point in the buffer, and then does a
1024 @kbd{M-;} to align the current line's comment under the previous one.
1026 @vindex comment-start-skip
1027 The comment commands recognize comments based on the regular
1028 expression that is the value of the variable @code{comment-start-skip}.
1029 Make sure this regexp does not match the null string. It may match more
1030 than the comment starting delimiter in the strictest sense of the word;
1031 for example, in C mode the value of the variable is
1032 @c This stops M-q from breaking the line inside that @code.
1033 @code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and
1034 spaces after the @samp{/*} itself, and accepts C++ style comments
1035 also. (Note that @samp{\\} is needed in Lisp syntax to include a
1036 @samp{\} in the string, which is needed to deny the first star its
1037 special meaning in regexp syntax. @xref{Regexp Backslash}.)
1039 @vindex comment-start
1041 When a comment command makes a new comment, it inserts the value of
1042 @code{comment-start} as an opening comment delimiter. It also inserts
1043 the value of @code{comment-end} after point, as a closing comment
1044 delimiter. For example, in Lisp mode, @code{comment-start} is
1045 @samp{";"} and @code{comment-end} is @code{""} (the empty string). In
1046 C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is
1049 @vindex comment-padding
1050 The variable @code{comment-padding} specifies a string that the
1051 commenting commands should insert between the comment delimiter(s) and
1052 the comment text. The default, @samp{" "}, specifies a single space.
1053 Alternatively, the value can be a number, which specifies that number
1054 of spaces, or @code{nil}, which means no spaces at all.
1056 The variable @code{comment-multi-line} controls how @kbd{M-j} and
1057 Auto Fill mode continue comments over multiple lines.
1058 @xref{Multi-Line Comments}.
1060 @vindex comment-indent-function
1061 The variable @code{comment-indent-function} should contain a function
1062 that will be called to compute the alignment for a newly inserted
1063 comment or for aligning an existing comment. It is set differently by
1064 various major modes. The function is called with no arguments, but with
1065 point at the beginning of the comment, or at the end of a line if a new
1066 comment is to be inserted. It should return the column in which the
1067 comment ought to start. For example, in Lisp mode, the indent hook
1068 function bases its decision on how many semicolons begin an existing
1069 comment, and on the code in the preceding lines.
1072 @section Documentation Lookup
1074 Emacs provides several features you can use to look up the
1075 documentation of functions, variables and commands that you plan to
1076 use in your program.
1079 * Info Lookup:: Looking up library functions and commands
1081 * Man Page:: Looking up man pages of library functions and commands.
1082 * Lisp Doc:: Looking up Emacs Lisp functions, etc.
1086 @subsection Info Documentation Lookup
1088 @findex info-lookup-symbol
1089 @findex info-lookup-file
1091 For major modes that apply to languages which have documentation in
1092 Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the
1093 Info documentation for a symbol used in the program. You specify the
1094 symbol with the minibuffer; the default is the symbol appearing in the
1095 buffer at point. For example, in C mode this looks for the symbol in
1096 the C Library Manual. The command only works if the appropriate
1097 manual's Info files are installed.
1099 The major mode determines where to look for documentation for the
1100 symbol---which Info files to look in, and which indices to search.
1101 You can also use @kbd{M-x info-lookup-file} to look for documentation
1104 If you use @kbd{C-h S} in a major mode that does not support it,
1105 it asks you to specify the ``symbol help mode.'' You should enter
1106 a command such as @code{c-mode} that would select a major
1107 mode which @kbd{C-h S} does support.
1110 @subsection Man Page Lookup
1113 On Unix, the main form of on-line documentation was the @dfn{manual
1114 page} or @dfn{man page}. In the GNU operating system, we aim to
1115 replace man pages with better-organized manuals that you can browse
1116 with Info (@pxref{Misc Help}). This process is not finished, so it is
1117 still useful to read manual pages.
1119 @findex manual-entry
1120 You can read the man page for an operating system command, library
1121 function, or system call, with the @kbd{M-x man} command. This
1122 prompts for a topic, with completion (@pxref{Completion}), and runs
1123 the @command{man} program to format the corresponding man page. If
1124 the system permits, it runs @command{man} asynchronously, so that you
1125 can keep on editing while the page is being formatted. The result
1126 goes in a buffer named @samp{*Man @var{topic}*}. These buffers use a
1127 special major mode, Man mode, that facilitates scrolling and jumping
1128 to other manual pages. For details, type @kbd{C-h m} while in a Man
1131 @cindex sections of manual pages
1132 Each man page belongs to one of ten or more @dfn{sections}, each
1133 named by a digit or by a digit and a letter. Sometimes there are man
1134 pages with the same name in different sections. To read a man page
1135 from a specific section, type @samp{@var{topic}(@var{section})} or
1136 @samp{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts
1137 for the topic. For example, the man page for the C library function
1138 @code{chmod} is in section 2, but there is a shell command of the same
1139 name, whose man page is in section 1; to view the former, type
1140 @kbd{M-x manual-entry @key{RET} chmod(2) @key{RET}}.
1142 @vindex Man-switches
1143 @kindex M-n @r{(Man mode)}
1144 @kindex M-p @r{(Man mode)}
1145 If you do not specify a section, @kbd{M-x man} normally displays
1146 only the first man page found. On some systems, the @code{man}
1147 program accepts a @samp{-a} command-line option, which tells it to
1148 display all the man pages for the specified topic. To make use of
1149 this, change the value of the variable @code{Man-switches} to
1150 @samp{"-a"}. Then, in the Man mode buffer, you can type @kbd{M-n} and
1151 @kbd{M-p} to switch between man pages in different sections. The mode
1152 line shows how many manual pages are available.
1155 @cindex manual pages, on MS-DOS/MS-Windows
1156 An alternative way of reading manual pages is the @kbd{M-x woman}
1157 command. Unlike @kbd{M-x man}, it does not run any external programs
1158 to format and display the man pages; the formatting is done by Emacs,
1159 so it works on systems such as MS-Windows where the @command{man}
1160 program may be unavailable. It prompts for a man page, and displays
1161 it in a buffer named @samp{*WoMan @var{section} @var{topic}}.
1163 @kbd{M-x woman} computes the completion list for manpages the first
1164 time you invoke the command. With a numeric argument, it recomputes
1165 this list; this is useful if you add or delete manual pages.
1167 If you type a name of a manual page and @kbd{M-x woman} finds that
1168 several manual pages by the same name exist in different sections, it
1169 pops up a window with possible candidates asking you to choose one of
1172 For more information about setting up and using @kbd{M-x woman}, see
1174 @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The
1178 the WoMan Info manual, which is distributed with Emacs.
1182 @subsection Emacs Lisp Documentation Lookup
1184 When editing Emacs Lisp code, you can use the commands @kbd{C-h f}
1185 (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable})
1186 to view the built-in documentation for the Lisp functions and
1187 variables that you want to use. @xref{Name Help}.
1191 Eldoc is a buffer-local minor mode that helps with looking up Lisp
1192 documention. When it is enabled, the echo area displays some useful
1193 information whenever there is a Lisp function or variable at point;
1194 for a function, it shows the argument list, and for a variable it
1195 shows the first line of the variable's documentation string. To
1196 toggle Eldoc mode, type @kbd{M-x eldoc-mode}. Eldoc mode can be used
1197 with the Emacs Lisp and Lisp Interaction major modes.
1200 @section Hideshow minor mode
1201 @cindex Hideshow mode
1202 @cindex mode, Hideshow
1204 @findex hs-minor-mode
1205 Hideshow mode is a buffer-local minor mode that allows you to
1206 selectively display portions of a program, which are referred to as
1207 @dfn{blocks}. Type @kbd{M-x hs-minor-mode} to toggle this minor mode
1208 (@pxref{Minor Modes}).
1210 When you use Hideshow mode to hide a block, the block disappears
1211 from the screen, to be replaced by an ellipsis (three periods in a
1212 row). Just what constitutes a block depends on the major mode. In C
1213 mode and related modes, blocks are delimited by braces, while in Lisp
1214 mode they are delimited by parentheses. Multi-line comments also
1217 Hideshow mode provides the following commands:
1220 @findex hs-hide-block
1222 @findex hs-show-block
1223 @findex hs-show-region
1224 @findex hs-hide-level
1225 @findex hs-minor-mode
1228 @kindex C-c @@ C-M-h
1229 @kindex C-c @@ C-M-s
1235 Hide the current block (@code{hs-hide-block}).
1237 Show the current block (@code{hs-show-block}).
1239 Either hide or show the current block (@code{hs-toggle-hiding}).
1241 Toggle hiding for the block you click on (@code{hs-mouse-toggle-hiding}).
1243 Hide all top-level blocks (@code{hs-hide-all}).
1245 Show all blocks in the buffer (@code{hs-show-all}).
1247 Hide all blocks @var{n} levels below this block
1248 (@code{hs-hide-level}).
1251 @vindex hs-hide-comments-when-hiding-all
1252 @vindex hs-isearch-open
1253 @vindex hs-special-modes-alist
1254 These variables can be used to customize Hideshow mode:
1257 @item hs-hide-comments-when-hiding-all
1258 If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides
1261 @item hs-isearch-open
1262 This variable specifies the conditions under which incremental search
1263 should unhide a hidden block when matching text occurs within the
1264 block. Its value should be either @code{code} (unhide only code
1265 blocks), @code{comment} (unhide only comments), @code{t} (unhide both
1266 code blocks and comments), or @code{nil} (unhide neither code blocks
1267 nor comments). The default value is @code{code}.
1270 @node Symbol Completion
1271 @section Completion for Symbol Names
1272 @cindex completion (symbol names)
1274 Completion is normally done in the minibuffer (@pxref{Completion}),
1275 but you can also complete symbol names in ordinary Emacs buffers.
1279 In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}}
1280 to complete the partial symbol before point. On graphical displays,
1281 the @kbd{M-@key{TAB}} key is usually reserved by the window manager
1282 for switching graphical windows, so you should type @kbd{C-M-i} or
1283 @kbd{@key{ESC} @key{TAB}} instead.
1285 @cindex tags-based completion
1286 @cindex Info index completion
1287 @findex complete-symbol
1288 In-buffer symbol completion generates its completion list in a
1289 number of different ways. In most programming language modes,
1290 completion is normally done using a tags table (@pxref{Tags}).
1291 However, if you supply @kbd{C-M-i} or @kbd{M-@key{TAB}} with a numeric
1292 argument, it completes using the Info file indexes for the current
1293 language (e.g.@: the C Library Manual). Of course, Info-based
1294 completion works only if there is an Info file for the standard
1295 library functions of your language, and only if it is installed at
1298 @cindex Lisp symbol completion
1299 @cindex completion (Lisp symbols)
1300 In Emacs Lisp mode, completion is performed using the function,
1301 variable, and property names defined in the current Emacs session. If
1302 there is an open parenthesis immediately before the beginning of the
1303 partial symbol, only symbols with function definitions are considered.
1305 In all other respects, in-buffer symbol completion behaves like
1306 minibuffer completion. For instance, if Emacs cannot complete to a
1307 unique symbol, it displays a list of completion alternatives in
1308 another window. @xref{Completion}.
1310 In Text mode and related modes, @kbd{M-@key{TAB}} completes words
1311 based on the spell-checker's dictionary. @xref{Spelling}.
1314 @section Glasses minor mode
1315 @cindex Glasses mode
1317 @findex mode, Glasses
1319 Glasses mode is a buffer-local minor mode that makes it easier to
1320 read mixed-case (or ``CamelCase'') symbols like
1321 @samp{unReadableSymbol}, by altering how they are displayed. By
1322 default, it displays extra underscores between each lower-case letter
1323 and the following capital letter. This does not alter the buffer
1324 text, only how it is displayed.
1326 To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor
1327 Modes}). When Glasses mode is enabled, the minor mode indicator
1328 @samp{o^o} appears in the mode line. For more information about
1329 Glasses mode, type @kbd{C-h P glasses @key{RET}}.
1333 @cindex Semantic package
1335 Semantic is a package that provides language-aware editing commands
1336 based on @code{source code parsers}. This section provides a brief
1337 description of Semantic; for full details,
1339 see @ref{Top, Semantic,, semantic, Semantic}.
1342 see the Semantic Info manual, which is distributed with Emacs.
1345 Most of the ``language aware'' features in Emacs, such as Font Lock
1346 mode (@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular
1347 expressions and syntax tables.} that usually give good results but are
1348 never completely exact. In contrast, the parsers used by Semantic
1349 have an exact understanding of programming language syntax. This
1350 allows Semantic to provide search, navigation, and completion commands
1351 that are powerful and precise.
1353 To begin using Semantic, type @kbd{M-x semantic-mode} or click on
1354 the menu item named @samp{Source Code Parsers (Semantic)} in the
1355 @samp{Tools} menu. This enables Semantic mode, a global minor mode.
1357 When Semantic mode is enabled, Emacs automatically attempts to
1358 parses each file you visit. Currently, Semantic understands C, C++,
1359 Scheme, Javascript, Java, HTML, and Make. Within each parsed buffer,
1360 the following commands are available:
1365 Prompt for the name of a function defined in the current file, and
1366 move point there (@code{semantic-complete-jump-local}).
1370 Prompt for the name of a function defined in any file Emacs has
1371 parsed, and move point there (@code{semantic-complete-jump}).
1373 @item C-c , @key{SPC}
1374 @kindex C-c , @key{SPC}
1375 Display a list of possible completions for the symbol at point
1376 (@code{semantic-complete-analyze-inline}). This also activates a set
1377 of special key bindings for choosing a completion: @key{RET} accepts
1378 the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible
1379 completions, @key{TAB} completes as far as possible and then cycles,
1380 and @kbd{C-g} or any other key aborts completion.
1384 Display a list of the possible completions of the symbol at point, in
1385 another window (@code{semantic-analyze-possible-completions}).
1389 In addition to the above commands, the Semantic package provides a
1390 variety of other ways to make use of parser information. For
1391 instance, you can use it to display a list of completions when Emacs
1394 @xref{Top, Semantic,, semantic, Semantic}, for details.
1397 @node Misc for Programs
1398 @section Other Features Useful for Editing Programs
1400 Some Emacs commands that aren't designed specifically for editing
1401 programs are useful for that nonetheless.
1403 The Emacs commands that operate on words, sentences and paragraphs
1404 are useful for editing code. Most symbols names contain words
1405 (@pxref{Words}), while sentences can be found in strings and comments
1406 (@pxref{Sentences}). As for paragraphs, they are defined in most
1407 programming language modes to begin and end at blank lines
1408 (@pxref{Paragraphs}). Therefore, judicious use of blank lines to make
1409 the program clearer will also provide useful chunks of text for the
1410 paragraph commands to work on. Auto Fill mode, if enabled in a
1411 programming language major mode, indents the new lines which it
1414 Apart from Hideshow mode (@pxref{Hideshow}), another way to
1415 selectively display parts of a program is to use the selective display
1416 feature (@pxref{Selective Display}). Programming modes often also
1417 support Outline minor mode (@pxref{Outline Mode}), which can be used
1418 with the Foldout package (@pxref{Foldout}).
1421 The ``automatic typing'' features may be useful for writing programs.
1422 @xref{Top,,Autotyping, autotype, Autotyping}.
1426 @section C and Related Modes
1431 @cindex CORBA IDL mode
1432 @cindex Objective C mode
1438 @cindex mode, Objective C
1439 @cindex mode, CORBA IDL
1443 This section gives a brief description of the special features
1444 available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
1445 (These are called ``C mode and related modes.'')
1447 @xref{Top,, CC Mode, ccmode, CC Mode}, for more details.
1450 For more details, see the CC mode Info manual, which is distributed
1455 * Motion in C:: Commands to move by C statements, etc.
1456 * Electric C:: Colon and other chars can automatically reindent.
1457 * Hungry Delete:: A more powerful DEL command.
1458 * Other C Commands:: Filling comments, viewing expansion of macros,
1459 and other neat features.
1463 @subsection C Mode Motion Commands
1465 This section describes commands for moving point, in C mode and
1469 @item M-x c-beginning-of-defun
1470 @itemx M-x c-end-of-defun
1471 @findex c-beginning-of-defun
1472 @findex c-end-of-defun
1473 Move point to the beginning or end of the current function or
1474 top-level definition. These are found by searching for the least
1475 enclosing braces. (By contrast, @code{beginning-of-defun} and
1476 @code{end-of-defun} search for braces in column zero.) If you are
1477 editing code where the opening brace of a function isn't placed in
1478 column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to
1479 these commands. @xref{Moving by Defuns}.
1482 @kindex C-c C-u @r{(C mode)}
1483 @findex c-up-conditional
1484 Move point back to the containing preprocessor conditional, leaving the
1485 mark behind. A prefix argument acts as a repeat count. With a negative
1486 argument, move point forward to the end of the containing
1487 preprocessor conditional.
1489 @samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so
1490 the function will stop at a @samp{#elif} when going backward, but not
1494 @kindex C-c C-p @r{(C mode)}
1495 @findex c-backward-conditional
1496 Move point back over a preprocessor conditional, leaving the mark
1497 behind. A prefix argument acts as a repeat count. With a negative
1498 argument, move forward.
1501 @kindex C-c C-n @r{(C mode)}
1502 @findex c-forward-conditional
1503 Move point forward across a preprocessor conditional, leaving the mark
1504 behind. A prefix argument acts as a repeat count. With a negative
1505 argument, move backward.
1508 @kindex M-a (C mode)
1509 @findex c-beginning-of-statement
1510 Move point to the beginning of the innermost C statement
1511 (@code{c-beginning-of-statement}). If point is already at the beginning
1512 of a statement, move to the beginning of the preceding statement. With
1513 prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
1515 In comments or in strings which span more than one line, this command
1516 moves by sentences instead of statements.
1519 @kindex M-e (C mode)
1520 @findex c-end-of-statement
1521 Move point to the end of the innermost C statement or sentence; like
1522 @kbd{M-a} except that it moves in the other direction
1523 (@code{c-end-of-statement}).
1527 @subsection Electric C Characters
1529 In C mode and related modes, certain printing characters are
1530 @dfn{electric}---in addition to inserting themselves, they also
1531 reindent the current line, and optionally also insert newlines. The
1532 ``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#},
1533 @kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and
1536 You might find electric indentation inconvenient if you are editing
1537 chaotically indented code. If you are new to CC Mode, you might find
1538 it disconcerting. You can toggle electric action with the command
1539 @kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line
1540 after the mode name:
1544 @kindex C-c C-l @r{(C mode)}
1545 @findex c-toggle-electric-state
1546 Toggle electric action (@code{c-toggle-electric-state}). With a
1547 prefix argument, this command enables electric action if the argument
1548 is positive, disables it if it is negative.
1551 Electric characters insert newlines only when, in addition to the
1552 electric state, the @dfn{auto-newline} feature is enabled (indicated
1553 by @samp{/la} in the mode line after the mode name). You can turn
1554 this feature on or off with the command @kbd{C-c C-a}:
1558 @kindex C-c C-a @r{(C mode)}
1559 @findex c-toggle-auto-newline
1560 Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a
1561 prefix argument, this command turns the auto-newline feature on if the
1562 argument is positive, and off if it is negative.
1565 Usually the CC Mode style configures the exact circumstances in
1566 which Emacs inserts auto-newlines. You can also configure this
1567 directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}.
1570 @subsection Hungry Delete Feature in C
1571 @cindex hungry deletion (C Mode)
1573 If you want to delete an entire block of whitespace at point, you
1574 can use @dfn{hungry deletion}. This deletes all the contiguous
1575 whitespace either before point or after point in a single operation.
1576 @dfn{Whitespace} here includes tabs and newlines, but not comments or
1577 preprocessor commands.
1580 @item C-c C-@key{DEL}
1581 @itemx C-c @key{DEL}
1582 @findex c-hungry-delete-backwards
1583 @kindex C-c C-@key{DEL} (C Mode)
1584 @kindex C-c @key{DEL} (C Mode)
1585 @code{c-hungry-delete-backwards}---Delete the entire block of whitespace
1589 @itemx C-c C-@key{DELETE}
1590 @itemx C-c @key{DELETE}
1591 @findex c-hungry-delete-forward
1592 @kindex C-c C-d (C Mode)
1593 @kindex C-c C-@key{DELETE} (C Mode)
1594 @kindex C-c @key{DELETE} (C Mode)
1595 @code{c-hungry-delete-forward}---Delete the entire block of whitespace
1599 As an alternative to the above commands, you can enable @dfn{hungry
1600 delete mode}. When this feature is enabled (indicated by @samp{/h} in
1601 the mode line after the mode name), a single @key{DEL} deletes all
1602 preceding whitespace, not just one space, and a single @kbd{C-c C-d}
1603 (but @emph{not} plain @key{DELETE}) deletes all following whitespace.
1606 @item M-x c-toggle-hungry-state
1607 @findex c-toggle-hungry-state
1608 Toggle the hungry-delete feature
1609 (@code{c-toggle-hungry-state})@footnote{This command had the binding
1610 @kbd{C-c C-d} in earlier versions of Emacs. @kbd{C-c C-d} is now
1611 bound to @code{c-hungry-delete-forward}.}. With a prefix argument,
1612 this command turns the hungry-delete feature on if the argument is
1613 positive, and off if it is negative.
1616 @vindex c-hungry-delete-key
1617 The variable @code{c-hungry-delete-key} controls whether the
1618 hungry-delete feature is enabled.
1620 @node Other C Commands
1621 @subsection Other Commands for C Mode
1625 @itemx M-x subword-mode
1626 @findex subword-mode
1627 Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word
1628 commands recognize upper case letters in
1629 @samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by
1630 the flag @samp{/w} on the mode line after the mode name
1631 (e.g. @samp{C/law}). You can even use @kbd{M-x subword-mode} in
1632 non-CC Mode buffers.
1634 In the GNU project, we recommend using underscores to separate words
1635 within an identifier in C or C++, rather than using case distinctions.
1637 @item M-x c-context-line-break
1638 @findex c-context-line-break
1639 This command inserts a line break and indents the new line in a manner
1640 appropriate to the context. In normal code, it does the work of
1641 @kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it
1642 additionally inserts a @samp{\} at the line break, and within comments
1643 it's like @kbd{M-j} (@code{c-indent-new-comment-line}).
1645 @code{c-context-line-break} isn't bound to a key by default, but it
1646 needs a binding to be useful. The following code will bind it to
1647 @kbd{C-j}. We use @code{c-initialization-hook} here to make sure
1648 the keymap is loaded before we try to change it.
1651 (defun my-bind-clb ()
1652 (define-key c-mode-base-map "\C-j" 'c-context-line-break))
1653 (add-hook 'c-initialization-hook 'my-bind-clb)
1657 Put mark at the end of a function definition, and put point at the
1658 beginning (@code{c-mark-function}).
1661 @kindex M-q @r{(C mode)}
1662 @findex c-fill-paragraph
1663 Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
1664 If any part of the current line is a comment or within a comment, this
1665 command fills the comment or the paragraph of it that point is in,
1666 preserving the comment indentation and comment delimiters.
1669 @cindex macro expansion in C
1670 @cindex expansion of C macros
1671 @findex c-macro-expand
1672 @kindex C-c C-e @r{(C mode)}
1673 Run the C preprocessor on the text in the region, and show the result,
1674 which includes the expansion of all the macro calls
1675 (@code{c-macro-expand}). The buffer text before the region is also
1676 included in preprocessing, for the sake of macros defined there, but the
1677 output from this part isn't shown.
1679 When you are debugging C code that uses macros, sometimes it is hard to
1680 figure out precisely how the macros expand. With this command, you
1681 don't have to figure it out; you can see the expansions.
1684 @findex c-backslash-region
1685 @kindex C-c C-\ @r{(C mode)}
1686 Insert or align @samp{\} characters at the ends of the lines of the
1687 region (@code{c-backslash-region}). This is useful after writing or
1688 editing a C macro definition.
1690 If a line already ends in @samp{\}, this command adjusts the amount of
1691 whitespace before it. Otherwise, it inserts a new @samp{\}. However,
1692 the last line in the region is treated specially; no @samp{\} is
1693 inserted on that line, and any @samp{\} there is deleted.
1695 @item M-x cpp-highlight-buffer
1696 @cindex preprocessor highlighting
1697 @findex cpp-highlight-buffer
1698 Highlight parts of the text according to its preprocessor conditionals.
1699 This command displays another buffer named @samp{*CPP Edit*}, which
1700 serves as a graphic menu for selecting how to display particular kinds
1701 of conditionals and their contents. After changing various settings,
1702 click on @samp{[A]pply these settings} (or go to that buffer and type
1703 @kbd{a}) to rehighlight the C mode buffer accordingly.
1706 @findex c-show-syntactic-information
1707 @kindex C-c C-s @r{(C mode)}
1708 Display the syntactic information about the current source line
1709 (@code{c-show-syntactic-information}). This information directs how
1710 the line is indented.
1712 @item M-x cwarn-mode
1713 @itemx M-x global-cwarn-mode
1715 @findex global-cwarn-mode
1716 @vindex global-cwarn-mode
1718 @cindex suspicious constructions in C, C++
1719 CWarn minor mode highlights certain suspicious C and C++ constructions:
1723 Assignments inside expressions.
1725 Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
1726 (except after a @samp{do @dots{} while} statement);
1728 C++ functions with reference parameters.
1732 You can enable the mode for one buffer with the command @kbd{M-x
1733 cwarn-mode}, or for all suitable buffers with the command @kbd{M-x
1734 global-cwarn-mode} or by customizing the variable
1735 @code{global-cwarn-mode}. You must also enable Font Lock mode to make
1738 @item M-x hide-ifdef-mode
1739 @findex hide-ifdef-mode
1740 @cindex Hide-ifdef mode
1741 @vindex hide-ifdef-shadow
1742 Hide-ifdef minor mode hides selected code within @samp{#if} and
1743 @samp{#ifdef} preprocessor blocks. If you change the variable
1744 @code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode
1745 ``shadows'' preprocessor blocks by displaying them with a less
1746 prominent face, instead of hiding them entirely. See the
1747 documentation string of @code{hide-ifdef-mode} for more information.
1749 @item M-x ff-find-related-file
1750 @cindex related files
1751 @findex ff-find-related-file
1752 @vindex ff-related-file-alist
1753 Find a file ``related'' in a special way to the file visited by the
1754 current buffer. Typically this will be the header file corresponding
1755 to a C/C++ source file, or vice versa. The variable
1756 @code{ff-related-file-alist} specifies how to compute related file
1764 @cindex assembler mode
1765 Asm mode is a major mode for editing files of assembler code. It
1766 defines these commands:
1770 @code{tab-to-tab-stop}.
1772 Insert a newline and then indent using @code{tab-to-tab-stop}.
1774 Insert a colon and then remove the indentation from before the label
1775 preceding colon. Then do @code{tab-to-tab-stop}.
1777 Insert or align a comment.
1780 The variable @code{asm-comment-char} specifies which character
1781 starts comments in assembler syntax.
1784 @include fortran-xtra.texi