1 @c -*- coding: utf-8 -*-
2 @c This is part of the Emacs manual.
3 @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2014 Free Software
5 @c See file emacs.texi for copying conditions.
7 @chapter Editing Programs
10 @cindex program editing
12 This chapter describes Emacs features for facilitating editing
13 programs. Some of the things these features can do are:
17 Find or move over top-level definitions (@pxref{Defuns}).
19 Apply the usual indentation conventions of the language
20 (@pxref{Program Indent}).
22 Balance parentheses (@pxref{Parentheses}).
24 Insert, kill or align comments (@pxref{Comments}).
26 Highlight program syntax (@pxref{Font Lock}).
30 * Program Modes:: Major modes for editing programs.
31 * Defuns:: Commands to operate on major top-level parts
33 * Program Indent:: Adjusting indentation to show the nesting.
34 * Parentheses:: Commands that operate on parentheses.
35 * Comments:: Inserting, killing, and aligning comments.
36 * Documentation:: Getting documentation of functions you plan to call.
37 * Hideshow:: Displaying blocks selectively.
38 * Symbol Completion:: Completion on symbol names of your program or language.
39 * MixedCase Words:: Dealing with identifiersLikeThis.
40 * Semantic:: Suite of editing tools based on source code parsing.
41 * Misc for Programs:: Other Emacs features useful for editing programs.
42 * C Modes:: Special commands of C, C++, Objective-C, Java,
43 IDL, Pike and AWK modes.
44 * Asm Mode:: Asm mode and its special features.
46 * Fortran:: Fortran mode and its special features.
51 @section Major Modes for Programming Languages
52 @cindex modes for programming languages
54 Emacs has specialized major modes (@pxref{Major Modes}) for many
55 programming languages. A programming language mode typically
56 specifies the syntax of expressions, the customary rules for
57 indentation, how to do syntax highlighting for the language, and how
58 to find the beginning or end of a function definition. It often has
59 features for compiling and debugging programs as well. The major mode
60 for each language is named after the language; for instance, the major
61 mode for the C programming language is @code{c-mode}.
78 @cindex Shell-script mode
80 @cindex PostScript mode
83 @cindex Javascript mode
84 Emacs has programming language modes for Lisp, Scheme, the
85 Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++,
86 Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont
87 (@TeX{}'s companion for font creation), Modula2, Object Pascal, Objective-C,
88 Octave, Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl,
89 and VHDL@. An alternative mode for Perl is called CPerl mode. Modes are
90 also available for the scripting languages of the common GNU and Unix
91 shells, VMS DCL, and MS-DOS/MS-Windows @samp{BAT} files, and for
92 makefiles, DNS master files, and various sorts of configuration files.
94 Ideally, Emacs should have a major mode for each programming
95 language that you might want to edit. If it doesn't have a mode for
96 your favorite language, the mode might be implemented in a package not
97 distributed with Emacs (@pxref{Packages}); or you can contribute one.
99 @kindex DEL @r{(programming modes)}
100 @findex c-electric-backspace
101 @findex backward-delete-char-untabify
102 In most programming languages, indentation should vary from line to
103 line to illustrate the structure of the program. Therefore, in most
104 programming language modes, typing @key{TAB} updates the indentation
105 of the current line (@pxref{Program Indent}). Furthermore, @key{DEL}
106 is usually bound to @code{backward-delete-char-untabify}, which
107 deletes backward treating each tab as if it were the equivalent number
108 of spaces, so that you can delete one column of indentation without
109 worrying whether the whitespace consists of spaces or tabs.
113 @vindex lisp-mode-hook
114 @vindex emacs-lisp-mode-hook
115 @vindex lisp-interaction-mode-hook
116 @vindex scheme-mode-hook
117 Entering a programming language mode runs the custom Lisp functions
118 specified in the hook variable @code{prog-mode-hook}, followed by
119 those specified in the mode's own mode hook (@pxref{Major Modes}).
120 For instance, entering C mode runs the hooks @code{prog-mode-hook} and
121 @code{c-mode-hook}. @xref{Hooks}, for information about hooks.
124 Separate manuals are available for the modes for Ada (@pxref{Top,,
125 Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba
126 IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), and IDLWAVE
127 (@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}).
130 The Emacs distribution contains Info manuals for the major modes for
131 Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE@. For
132 Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized Emacs Features}.
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 @vindex open-paren-in-column-0-is-defun-start
190 If you need to override this convention, you can do so by setting
191 the variable @code{open-paren-in-column-0-is-defun-start}.
192 If this user option is set to @code{t} (the default), opening
193 parentheses or braces at column zero always start defuns. When it is
194 @code{nil}, defuns are found by searching for parens or braces at the
197 Usually, you should leave this option at its default value of
198 @code{t}. If your buffer contains parentheses or braces in column
199 zero which don't start defuns, and it is somehow impractical to remove
200 these parentheses or braces, it might be helpful to set the option to
201 @code{nil}. Be aware that this might make scrolling and display in
202 large buffers quite sluggish. Furthermore, the parentheses and braces
203 must be correctly matched throughout the buffer for it to work
206 @node Moving by Defuns
207 @subsection Moving by Defuns
210 These commands move point or set up the region based on top-level
211 major definitions, also called @dfn{defuns}.
215 Move to beginning of current or preceding defun
216 (@code{beginning-of-defun}).
218 Move to end of current or following defun (@code{end-of-defun}).
220 Put region around whole current or following defun (@code{mark-defun}).
223 @cindex move to beginning or end of function
224 @cindex function, move to beginning or end
228 @findex beginning-of-defun
231 The commands to move to the beginning and end of the current defun
232 are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e}
233 (@code{end-of-defun}). If you repeat one of these commands, or use a
234 positive numeric argument, each repetition moves to the next defun in
235 the direction of motion.
237 @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward
238 @var{n} times to the next beginning of a defun. This is not exactly
239 the same place that @kbd{C-M-e} with argument @var{n} would move to;
240 the end of this defun is not usually exactly the same place as the
241 beginning of the following defun. (Whitespace, comments, and perhaps
242 declarations can separate them.) Likewise, @kbd{C-M-e} with a
243 negative argument moves back to an end of a defun, which is not quite
244 the same as @kbd{C-M-a} with a positive argument.
246 @kindex C-M-h @r{(C mode)}
247 @findex c-mark-function
248 To operate on the current defun, use @kbd{C-M-h}
249 (@code{mark-defun}), which sets the mark at the end of the current
250 defun and puts point at its beginning. @xref{Marking Objects}. This
251 is the easiest way to get ready to kill the defun in order to move it
252 to a different place in the file. If you use the command while point
253 is between defuns, it uses the following defun. If you use the
254 command while the mark is already active, it sets the mark but does
255 not move point; furthermore, each successive use of @kbd{C-M-h}
256 extends the end of the region to include one more defun.
258 In C mode, @kbd{C-M-h} runs the function @code{c-mark-function},
259 which is almost the same as @code{mark-defun}; the difference is that
260 it backs up over the argument declarations, function name and returned
261 data type so that the entire C function is inside the region. This is
262 an example of how major modes adjust the standard key bindings so that
263 they do their standard jobs in a way better fitting a particular
264 language. Other major modes may replace any or all of these key
265 bindings for that purpose.
269 @cindex index of buffer definitions
270 @cindex buffer definitions index
272 The Imenu facility offers a way to find the major definitions in
273 a file by name. It is also useful in text formatter major modes,
274 where it treats each chapter, section, etc., as a definition.
275 (@xref{Tags}, for a more powerful feature that handles multiple files
279 If you type @kbd{M-x imenu}, it reads the name of a definition using
280 the minibuffer, then moves point to that definition. You can use
281 completion to specify the name; the command always displays the whole
284 @findex imenu-add-menubar-index
285 Alternatively, you can bind the command @code{imenu} to a mouse
286 click. Then it displays mouse menus for you to select a definition
287 name. You can also add the buffer's index to the menu bar by calling
288 @code{imenu-add-menubar-index}. If you want to have this menu bar
289 item available for all buffers in a certain major mode, you can do
290 this by adding @code{imenu-add-menubar-index} to its mode hook. But
291 if you have done that, you will have to wait a little while each time
292 you visit a file in that mode, while Emacs finds all the definitions
295 @vindex imenu-auto-rescan
296 When you change the contents of a buffer, if you add or delete
297 definitions, you can update the buffer's index based on the
298 new contents by invoking the @samp{*Rescan*} item in the menu.
299 Rescanning happens automatically if you set @code{imenu-auto-rescan} to
300 a non-@code{nil} value. There is no need to rescan because of small
303 @vindex imenu-sort-function
304 You can customize the way the menus are sorted by setting the
305 variable @code{imenu-sort-function}. By default, names are ordered as
306 they occur in the buffer; if you want alphabetic sorting, use the
307 symbol @code{imenu--sort-by-name} as the value. You can also
308 define your own comparison function by writing Lisp code.
310 Imenu provides the information to guide Which Function mode
312 (@pxref{Which Function}).
317 The Speedbar can also use it (@pxref{Speedbar}).
320 @subsection Which Function Mode
321 @cindex current function name in mode line
323 Which Function mode is a global minor mode (@pxref{Minor Modes})
324 which displays the current function name in the mode line, updating it
325 as you move around in a buffer.
327 @findex which-function-mode
328 @vindex which-func-modes
329 To either enable or disable Which Function mode, use the command
330 @kbd{M-x which-function-mode}. Which Function mode is a global minor
331 mode. By default, it takes effect in all major modes major modes that
332 know how to support it (i.e., all the major modes that support
333 Imenu). You can restrict it to a specific list of major modes by
334 changing the value of the variable @code{which-func-modes} from
335 @code{t} (which means to support all available major modes) to a list
339 @section Indentation for Programs
340 @cindex indentation for programs
342 The best way to keep a program properly indented is to use Emacs to
343 reindent it as you change it. Emacs has commands to indent either a
344 single line, a specified number of lines, or all of the lines inside a
345 single parenthetical grouping.
347 @xref{Indentation}, for general information about indentation. This
348 section describes indentation features specific to programming
352 * Basic Indent:: Indenting a single line.
353 * Multi-line Indent:: Commands to reindent many lines at once.
354 * Lisp Indent:: Specifying how each Lisp function should be indented.
355 * C Indent:: Extra features for indenting C and related modes.
356 * Custom C Indent:: Controlling indentation style for C and related modes.
359 @cindex pretty-printer
360 Emacs also provides a Lisp pretty-printer in the @code{pp} package,
361 which reformats Lisp objects with nice-looking indentation.
364 @subsection Basic Program Indentation Commands
368 Adjust indentation of current line (@code{indent-for-tab-command}).
370 Insert a newline, then adjust indentation of following line
374 @kindex TAB @r{(programming modes)}
375 @findex c-indent-command
376 @findex indent-line-function
377 @findex indent-for-tab-command
378 The basic indentation command is @key{TAB}
379 (@code{indent-for-tab-command}), which was documented in
380 @ref{Indentation}. In programming language modes, @key{TAB} indents
381 the current line, based on the indentation and syntactic content of
382 the preceding lines; if the region is active, @key{TAB} indents each
383 line within the region, not just the current line.
385 The command @key{RET} (@code{newline}), which was documented in
386 @ref{Inserting Text}, does the same as @key{C-j} followed by
387 @key{TAB}: it inserts a new line, then adjusts the line's indentation.
389 When indenting a line that starts within a parenthetical grouping,
390 Emacs usually places the start of the line under the preceding line
391 within the group, or under the text after the parenthesis. If you
392 manually give one of these lines a nonstandard indentation (e.g., for
393 aesthetic purposes), the lines below will follow it.
395 The indentation commands for most programming language modes assume
396 that a open-parenthesis, open-brace or other opening delimiter at the
397 left margin is the start of a function. If the code you are editing
398 violates this assumption---even if the delimiters occur in strings or
399 comments---you must set @code{open-paren-in-column-0-is-defun-start}
400 to @code{nil} for indentation to work properly. @xref{Left Margin
403 @node Multi-line Indent
404 @subsection Indenting Several Lines
406 Sometimes, you may want to reindent several lines of code at a time.
407 One way to do this is to use the mark; when the mark is active and the
408 region is non-empty, @key{TAB} indents every line in the region.
409 Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents
410 every line in the region, whether or not the mark is active
411 (@pxref{Indentation Commands}).
413 In addition, Emacs provides the following commands for indenting
414 large chunks of code:
418 Reindent all the lines within one parenthetical grouping.
420 Shift an entire parenthetical grouping rigidly sideways so that its
421 first line is properly indented.
422 @item M-x indent-code-rigidly
423 Shift all the lines in the region rigidly sideways, but do not alter
424 lines that start inside comments and strings.
428 @findex indent-pp-sexp
429 To reindent the contents of a single parenthetical grouping,
430 position point before the beginning of the grouping and type
431 @kbd{C-M-q}. This changes the relative indentation within the
432 grouping, without affecting its overall indentation (i.e., the
433 indentation of the line where the grouping starts). The function that
434 @kbd{C-M-q} runs depends on the major mode; it is
435 @code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode,
436 etc. To correct the overall indentation as well, type @key{TAB}
440 If you like the relative indentation within a grouping but not the
441 indentation of its first line, move point to that first line and type
442 @kbd{C-u @key{TAB}}. In Lisp, C, and some other major modes,
443 @key{TAB} with a numeric argument reindents the current line as usual,
444 then reindents by the same amount all the lines in the parenthetical
445 grouping starting on the current line. It is clever, though, and does
446 not alter lines that start inside strings. Neither does it alter C
447 preprocessor lines when in C mode, but it does reindent any
448 continuation lines that may be attached to them.
450 @findex indent-code-rigidly
451 The command @kbd{M-x indent-code-rigidly} rigidly shifts all the
452 lines in the region sideways, like @code{indent-rigidly} does
453 (@pxref{Indentation Commands}). It doesn't alter the indentation of
454 lines that start inside a string, unless the region also starts inside
455 that string. The prefix arg specifies the number of columns to
459 @subsection Customizing Lisp Indentation
460 @cindex customizing Lisp indentation
462 The indentation pattern for a Lisp expression can depend on the function
463 called by the expression. For each Lisp function, you can choose among
464 several predefined patterns of indentation, or define an arbitrary one with
467 The standard pattern of indentation is as follows: the second line of the
468 expression is indented under the first argument, if that is on the same
469 line as the beginning of the expression; otherwise, the second line is
470 indented underneath the function name. Each following line is indented
471 under the previous line whose nesting depth is the same.
473 @vindex lisp-indent-offset
474 If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
475 the usual indentation pattern for the second line of an expression, so that
476 such lines are always indented @code{lisp-indent-offset} more columns than
479 @vindex lisp-body-indent
480 Certain functions override the standard pattern. Functions whose
481 names start with @code{def} treat the second lines as the start of
482 a @dfn{body}, by indenting the second line @code{lisp-body-indent}
483 additional columns beyond the open-parenthesis that starts the
486 @cindex @code{lisp-indent-function} property
487 You can override the standard pattern in various ways for individual
488 functions, according to the @code{lisp-indent-function} property of
489 the function name. This is normally done for macro definitions, using
490 the @code{declare} construct. @xref{Defining Macros,,, elisp, the
491 Emacs Lisp Reference Manual}.
494 @subsection Commands for C Indentation
496 Here are special features for indentation in C mode and related modes:
500 @kindex C-c C-q @r{(C mode)}
501 @findex c-indent-defun
502 Reindent the current top-level function definition or aggregate type
503 declaration (@code{c-indent-defun}).
506 @kindex C-M-q @r{(C mode)}
508 Reindent each line in the balanced expression that follows point
509 (@code{c-indent-exp}). A prefix argument inhibits warning messages
510 about invalid syntax.
513 @findex c-indent-command
514 Reindent the current line, and/or in some cases insert a tab character
515 (@code{c-indent-command}).
517 @vindex c-tab-always-indent
518 If @code{c-tab-always-indent} is @code{t}, this command always reindents
519 the current line and does nothing else. This is the default.
521 If that variable is @code{nil}, this command reindents the current line
522 only if point is at the left margin or in the line's indentation;
523 otherwise, it inserts a tab (or the equivalent number of spaces,
524 if @code{indent-tabs-mode} is @code{nil}).
526 Any other value (not @code{nil} or @code{t}) means always reindent the
527 line, and also insert a tab if within a comment or a string.
530 To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This
531 first selects the whole buffer as the region, then reindents that
534 To reindent the current block, use @kbd{C-M-u C-M-q}. This moves
535 to the front of the block and then reindents it all.
537 @node Custom C Indent
538 @subsection Customizing C Indentation
539 @cindex style (for indentation)
541 C mode and related modes use a flexible mechanism for customizing
542 indentation. C mode indents a source line in two steps: first it
543 classifies the line syntactically according to its contents and
544 context; second, it determines the indentation offset associated by
545 your selected @dfn{style} with the syntactic construct and adds this
546 onto the indentation of the @dfn{anchor statement}.
549 @item C-c . @key{RET} @var{style} @key{RET}
550 Select a predefined style @var{style} (@code{c-set-style}).
553 A @dfn{style} is a named collection of customizations that can be
554 used in C mode and the related modes. @ref{Styles,,, ccmode, The CC
555 Mode Manual}, for a complete description. Emacs comes with several
556 predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
557 @code{stroustrup}, @code{linux}, @code{python}, @code{java},
558 @code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these
559 styles are primarily intended for one language, but any of them can be
560 used with any of the languages supported by these modes. To find out
561 what a style looks like, select it and reindent some code, e.g., by
562 typing @key{C-M-q} at the start of a function definition.
564 @kindex C-c . @r{(C mode)}
566 To choose a style for the current buffer, use the command @w{@kbd{C-c
567 .}}. Specify a style name as an argument (case is not significant).
568 This command affects the current buffer only, and it affects only
569 future invocations of the indentation commands; it does not reindent
570 the code already in the buffer. To reindent the whole buffer in the
571 new style, you can type @kbd{C-x h C-M-\}.
573 @vindex c-default-style
574 You can also set the variable @code{c-default-style} to specify the
575 default style for various major modes. Its value should be either the
576 style's name (a string) or an alist, in which each element specifies
577 one major mode and which indentation style to use for it. For
581 (setq c-default-style
582 '((java-mode . "java")
588 specifies explicit choices for Java and AWK modes, and the default
589 @samp{gnu} style for the other C-like modes. (These settings are
590 actually the defaults.) This variable takes effect when you select
591 one of the C-like major modes; thus, if you specify a new default
592 style for Java mode, you can make it take effect in an existing Java
593 mode buffer by typing @kbd{M-x java-mode} there.
595 The @code{gnu} style specifies the formatting recommended by the GNU
596 Project for C; it is the default, so as to encourage use of our
599 @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and
600 @ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more
601 information on customizing indentation for C and related modes,
602 including how to override parts of an existing style and how to define
606 @findex c-guess-install
607 As an alternative to specifying a style, you can tell Emacs to guess
608 a style by typing @kbd{M-x c-guess} in a sample code buffer. You can
609 then apply the guessed style to other buffers with @kbd{M-x
610 c-guess-install}. @xref{Guessing the Style,,, ccmode, the CC Mode
611 Manual}, for details.
614 @section Commands for Editing with Parentheses
617 @cindex unbalanced parentheses and quotes
618 This section describes the commands and features that take advantage
619 of the parenthesis structure in a program, or help you keep it
622 When talking about these facilities, the term ``parenthesis'' also
623 includes braces, brackets, or whatever delimiters are defined to match
624 in pairs. The major mode controls which delimiters are significant,
625 through the syntax table (@pxref{Syntax Tables,, Syntax Tables, elisp,
626 The Emacs Lisp Reference Manual}). In Lisp, only parentheses count;
627 in C, these commands apply to braces and brackets too.
629 You can use @kbd{M-x check-parens} to find any unbalanced
630 parentheses and unbalanced string quotes in the buffer.
633 * Expressions:: Expressions with balanced parentheses.
634 * Moving by Parens:: Commands for moving up, down and across
635 in the structure of parentheses.
636 * Matching:: Insertion of a close-delimiter flashes matching open.
640 @subsection Expressions with Balanced Parentheses
644 @cindex balanced expression
645 Each programming language mode has its own definition of a
646 @dfn{balanced expression}. Balanced expressions typically include
647 individual symbols, numbers, and string constants, as well as pieces
648 of code enclosed in a matching pair of delimiters. The following
649 commands deal with balanced expressions (in Emacs, such expressions
650 are referred to internally as @dfn{sexps}@footnote{The word ``sexp''
651 is used to refer to an expression in Lisp.}).
655 Move forward over a balanced expression (@code{forward-sexp}).
657 Move backward over a balanced expression (@code{backward-sexp}).
659 Kill balanced expression forward (@code{kill-sexp}).
661 Transpose expressions (@code{transpose-sexps}).
664 Put mark after following expression (@code{mark-sexp}).
670 @findex backward-sexp
671 To move forward over a balanced expression, use @kbd{C-M-f}
672 (@code{forward-sexp}). If the first significant character after point
673 is an opening delimiter (e.g., @samp{(}, @samp{[} or @samp{@{} in C),
674 this command moves past the matching closing delimiter. If the
675 character begins a symbol, string, or number, the command moves over
678 The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
679 balanced expression---like @kbd{C-M-f}, but in the reverse direction.
680 If the expression is preceded by any prefix characters (single-quote,
681 backquote and comma, in Lisp), the command moves back over them as
684 @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation
685 the specified number of times; with a negative argument means to move
686 in the opposite direction. In most modes, these two commands move
687 across comments as if they were whitespace. Note that their keys,
688 @kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b},
689 which move by characters (@pxref{Moving Point}), and @kbd{M-f} and
690 @kbd{M-b}, which move by words (@pxref{Words}).
692 @cindex killing expressions
695 To kill a whole balanced expression, type @kbd{C-M-k}
696 (@code{kill-sexp}). This kills the text that @kbd{C-M-f} would move
699 @cindex transposition of expressions
701 @findex transpose-sexps
702 @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the
703 previous balanced expression and the next one. It is analogous to the
704 @kbd{C-t} command, which transposes characters (@pxref{Transpose}).
705 An argument to @kbd{C-M-t} serves as a repeat count, moving the
706 previous expression over that many following ones. A negative
707 argument moves the previous balanced expression backwards across those
708 before it. An argument of zero, rather than doing nothing, transposes
709 the balanced expressions ending at or after point and the mark.
712 @kindex C-M-@key{SPC}
714 To operate on balanced expressions with a command which acts on the
715 region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}). This sets the
716 mark where @kbd{C-M-f} would move to. While the mark is active, each
717 successive call to this command extends the region by shifting the
718 mark by one expression. Positive or negative numeric arguments move
719 the mark forward or backward by the specified number of expressions.
720 The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}.
721 @xref{Marking Objects}, for more information about this and related
724 In languages that use infix operators, such as C, it is not possible
725 to recognize all balanced expressions because there can be multiple
726 possibilities at a given position. For example, C mode does not treat
727 @samp{foo + bar} as a single expression, even though it @emph{is} one
728 C expression; instead, it recognizes @samp{foo} as one expression and
729 @samp{bar} as another, with the @samp{+} as punctuation between them.
730 However, C mode recognizes @samp{(foo + bar)} as a single expression,
731 because of the parentheses.
733 @node Moving by Parens
734 @subsection Moving in the Parenthesis Structure
736 @cindex parenthetical groupings
737 @cindex parentheses, moving across
738 @cindex matching parenthesis and braces, moving to
739 @cindex braces, moving across
740 @cindex list commands
742 The following commands move over groupings delimited by parentheses
743 (or whatever else serves as delimiters in the language you are working
744 with). They ignore strings and comments, including any parentheses
745 within them, and also ignore parentheses that are ``quoted'' with an
746 escape character. These commands are mainly intended for editing
747 programs, but can be useful for editing any text containing
748 parentheses. They are referred to internally as ``list'' commands
749 because in Lisp these groupings are lists.
751 These commands assume that the starting point is not inside a string
752 or a comment. If you invoke them from inside a string or comment, the
753 results are unreliable.
757 Move forward over a parenthetical group (@code{forward-list}).
759 Move backward over a parenthetical group (@code{backward-list}).
761 Move up in parenthesis structure (@code{backward-up-list}).
763 Move down in parenthesis structure (@code{down-list}).
769 @findex backward-list
770 The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and
771 @kbd{C-M-p} (@code{backward-list}) move forward or backward over one
772 (or @var{n}) parenthetical groupings.
775 @findex backward-up-list
776 @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
777 parenthesis structure. To move @emph{up} one (or @var{n}) levels, use
778 @kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up
779 past one unmatched opening delimiter. A positive argument serves as a
780 repeat count; a negative argument reverses the direction of motion, so
781 that the command moves forward and up one or more levels.
785 To move @emph{down} in the parenthesis structure, use @kbd{C-M-d}
786 (@code{down-list}). In Lisp mode, where @samp{(} is the only opening
787 delimiter, this is nearly the same as searching for a @samp{(}. An
788 argument specifies the number of levels to go down.
791 @subsection Matching Parentheses
792 @cindex matching parentheses
793 @cindex parentheses, displaying matches
795 Emacs has a number of @dfn{parenthesis matching} features, which
796 make it easy to see how and whether parentheses (or other delimiters)
799 Whenever you type a self-inserting character that is a closing
800 delimiter, the cursor moves momentarily to the location of the
801 matching opening delimiter, provided that is on the screen. If it is
802 not on the screen, Emacs displays some of the text near it in the echo
803 area. Either way, you can tell which grouping you are closing off.
804 If the opening delimiter and closing delimiter are mismatched---such
805 as in @samp{[x)}---a warning message is displayed in the echo area.
807 @vindex blink-matching-paren
808 @vindex blink-matching-paren-distance
809 @vindex blink-matching-delay
810 Three variables control the display of matching parentheses:
814 @code{blink-matching-paren} turns the feature on or off: @code{nil}
815 disables it, but the default is @code{t} to enable it.
818 @code{blink-matching-delay} says how many seconds to leave the cursor
819 on the matching opening delimiter, before bringing it back to the real
820 location of point. This may be an integer or floating-point number;
824 @code{blink-matching-paren-distance} specifies how many characters
825 back to search to find the matching opening delimiter. If the match
826 is not found in that distance, Emacs stops scanning and nothing is
827 displayed. The default is 102400.
830 @cindex Show Paren mode
831 @cindex highlighting matching parentheses
832 @findex show-paren-mode
833 Show Paren mode, a global minor mode, provides a more powerful kind
834 of automatic matching. Whenever point is before an opening delimiter
835 or after a closing delimiter, both that delimiter and its opposite
836 delimiter are highlighted. To toggle Show Paren mode, type @kbd{M-x
839 @cindex Electric Pair mode
840 @cindex inserting matching parentheses
841 @findex electric-pair-mode
842 Electric Pair mode, a global minor mode, provides a way to easily
843 insert matching delimiters. Whenever you insert an opening delimiter,
844 the matching closing delimiter is automatically inserted as well,
845 leaving point between the two. Conversely, when you insert a closing
846 delimiter over an existing one, no inserting takes places and that
847 position is simply skipped over. These variables control additional
848 features of Electric Pair mode:
852 @code{electric-pair-preserve-balance}, when non-@code{nil}, makes the
853 default pairing logic balance out the number of opening and closing
857 @code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes
858 backspacing between two adjacent delimiters also automatically delete
859 the closing delimiter.
862 @code{electric-pair-open-newline-between-pairs}, when non-@code{nil},
863 makes inserting inserting a newline between two adjacent pairs also
864 automatically open and extra newline after point.
867 @code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor
868 mode to skip whitespace forward before deciding whether to skip over
869 the closing delimiter.
872 To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}.
875 @section Manipulating Comments
878 Because comments are such an important part of programming, Emacs
879 provides special commands for editing and inserting comments. It can
880 also do spell checking on comments with Flyspell Prog mode
883 Some major modes have special rules for indenting different kinds of
884 comments. For example, in Lisp code, comments starting with two
885 semicolons are indented as if they were lines of code, while those
886 starting with three semicolons are supposed to be aligned to the left
887 margin and are often used for sectioning purposes. Emacs understand
888 these conventions; for instance, typing @key{TAB} on a comment line
889 will indent the comment to the appropriate position.
892 ;; This function is just an example.
893 ;;; Here either two or three semicolons are appropriate.
895 ;;; And now, the first part of the function:
896 ;; The following line adds one.
897 (1+ x)) ; This line adds one.
901 * Comment Commands:: Inserting, killing, and aligning comments.
902 * Multi-Line Comments:: Commands for adding and editing multi-line comments.
903 * Options for Comments::Customizing the comment features.
906 @node Comment Commands
907 @subsection Comment Commands
908 @cindex indentation for comments
909 @cindex alignment for comments
911 The following commands operate on comments:
915 Insert or realign comment on current line; if the region is active,
916 comment or uncomment the region instead (@code{comment-dwim}).
918 Kill comment on current line (@code{comment-kill}).
920 Set comment column (@code{comment-set-column}).
923 Like @key{RET} followed by inserting and aligning a comment
924 (@code{comment-indent-new-line}). @xref{Multi-Line Comments}.
925 @item @kbd{M-x comment-region}
926 @itemx @kbd{C-c C-c} (in C-like modes)
927 Add comment delimiters to all the lines in the region.
932 The command to create or align a comment is @kbd{M-;}
933 (@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What
934 I Mean''; it indicates that this command can be used for many
935 different jobs relating to comments, depending on the situation where
938 When a region is active (@pxref{Mark}), @kbd{M-;} either adds
939 comment delimiters to the region, or removes them. If every line in
940 the region is already a comment, it ``uncomments'' each of those lines
941 by removing their comment delimiters. Otherwise, it adds comment
942 delimiters to enclose the text in the region.
944 If you supply a prefix argument to @kbd{M-;} when a region is
945 active, that specifies the number of comment delimiters to add or
946 delete. A positive argument @var{n} adds @var{n} delimiters, while a
947 negative argument @var{-n} removes @var{n} delimiters.
949 If the region is not active, and there is no existing comment on the
950 current line, @kbd{M-;} adds a new comment to the current line. If
951 the line is blank (i.e., empty or containing only whitespace
952 characters), the comment is indented to the same position where
953 @key{TAB} would indent to (@pxref{Basic Indent}). If the line is
954 non-blank, the comment is placed after the last non-whitespace
955 character on the line; normally, Emacs tries putting it at the column
956 specified by the variable @code{comment-column} (@pxref{Options for
957 Comments}), but if the line already extends past that column, it puts
958 the comment at some suitable position, usually separated from the
959 non-comment text by at least one space. In each case, Emacs places
960 point after the comment's starting delimiter, so that you can start
961 typing the comment text right away.
963 You can also use @kbd{M-;} to align an existing comment. If a line
964 already contains the comment-start string, @kbd{M-;} realigns it to
965 the conventional alignment and moves point after the comment's
966 starting delimiter. As an exception, comments starting in column 0
967 are not moved. Even when an existing comment is properly aligned,
968 @kbd{M-;} is still useful for moving directly to the start of the
973 @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any
974 comment on the current line, along with the whitespace before it.
975 Since the comment is saved to the kill ring, you can reinsert it on
976 another line by moving to the end of that line, doing @kbd{C-y}, and
977 then @kbd{M-;} to realign the comment. You can achieve the same
978 effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill}
979 (@code{comment-dwim} actually calls @code{comment-kill} as a
980 subroutine when it is given a prefix argument).
982 @kindex C-c C-c (C mode)
983 @findex comment-region
984 @findex uncomment-region
985 The command @kbd{M-x comment-region} is equivalent to calling
986 @kbd{M-;} on an active region, except that it always acts on the
987 region, even if the mark is inactive. In C mode and related modes,
988 this command is bound to @kbd{C-c C-c}. The command @kbd{M-x
989 uncomment-region} uncomments each line in the region; a numeric prefix
990 argument specifies the number of comment delimiters to remove
991 (negative arguments specify the number of comment to delimiters to
994 For C-like modes, you can configure the exact effect of @kbd{M-;} by
995 setting the variables @code{c-indent-comment-alist} and
996 @code{c-indent-comments-syntactically-p}. For example, on a line
997 ending in a closing brace, @kbd{M-;} puts the comment one space after
998 the brace rather than at @code{comment-column}. For full details see
999 @ref{Comment Commands,,, ccmode, The CC Mode Manual}.
1001 @node Multi-Line Comments
1002 @subsection Multiple Lines of Comments
1006 @cindex blank lines in programs
1007 @findex comment-indent-new-line
1008 @vindex comment-multi-line
1009 If you are typing a comment and wish to continue it to another line,
1010 type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}). This
1011 breaks the current line, and inserts the necessary comment delimiters
1012 and indentation to continue the comment.
1014 For languages with closing comment delimiters (e.g., @samp{*/} in
1015 C), the exact behavior of @kbd{M-j} depends on the value of the
1016 variable @code{comment-multi-line}. If the value is @code{nil}, the
1017 command closes the comment on the old line and starts a new comment on
1018 the new line. Otherwise, it opens a new line within the current
1021 When Auto Fill mode is on, going past the fill column while typing a
1022 comment also continues the comment, in the same way as an explicit
1023 invocation of @kbd{M-j}.
1025 To turn existing lines into comment lines, use @kbd{M-;} with the
1026 region active, or use @kbd{M-x comment-region}
1028 (@pxref{Comment Commands}).
1031 as described in the preceding section.
1034 You can configure C Mode such that when you type a @samp{/} at the
1035 start of a line in a multi-line block comment, this closes the
1036 comment. Enable the @code{comment-close-slash} clean-up for this.
1037 @xref{Clean-ups,,, ccmode, The CC Mode Manual}.
1039 @node Options for Comments
1040 @subsection Options Controlling Comments
1042 @vindex comment-column
1044 @findex comment-set-column
1045 As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command
1046 adds a comment to a line, it tries to place the comment at the column
1047 specified by the buffer-local variable @code{comment-column}. You can
1048 set either the local value or the default value of this buffer-local
1049 variable in the usual way (@pxref{Locals}). Alternatively, you can
1050 type @kbd{C-x ;} (@code{comment-set-column}) to set the value of
1051 @code{comment-column} in the current buffer to the column where point
1052 is currently located. @kbd{C-u C-x ;} sets the comment column to
1053 match the last comment before point in the buffer, and then does a
1054 @kbd{M-;} to align the current line's comment under the previous one.
1056 @vindex comment-start-skip
1057 The comment commands recognize comments based on the regular
1058 expression that is the value of the variable @code{comment-start-skip}.
1059 Make sure this regexp does not match the null string. It may match more
1060 than the comment starting delimiter in the strictest sense of the word;
1061 for example, in C mode the value of the variable is
1062 @c This stops M-q from breaking the line inside that @code.
1063 @code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and
1064 spaces after the @samp{/*} itself, and accepts C++ style comments
1065 also. (Note that @samp{\\} is needed in Lisp syntax to include a
1066 @samp{\} in the string, which is needed to deny the first star its
1067 special meaning in regexp syntax. @xref{Regexp Backslash}.)
1069 @vindex comment-start
1071 When a comment command makes a new comment, it inserts the value of
1072 @code{comment-start} as an opening comment delimiter. It also inserts
1073 the value of @code{comment-end} after point, as a closing comment
1074 delimiter. For example, in Lisp mode, @code{comment-start} is
1075 @samp{";"} and @code{comment-end} is @code{""} (the empty string). In
1076 C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is
1079 @vindex comment-padding
1080 The variable @code{comment-padding} specifies a string that the
1081 commenting commands should insert between the comment delimiter(s) and
1082 the comment text. The default, @samp{" "}, specifies a single space.
1083 Alternatively, the value can be a number, which specifies that number
1084 of spaces, or @code{nil}, which means no spaces at all.
1086 The variable @code{comment-multi-line} controls how @kbd{M-j} and
1087 Auto Fill mode continue comments over multiple lines.
1088 @xref{Multi-Line Comments}.
1090 @vindex comment-indent-function
1091 The variable @code{comment-indent-function} should contain a function
1092 that will be called to compute the alignment for a newly inserted
1093 comment or for aligning an existing comment. It is set differently by
1094 various major modes. The function is called with no arguments, but with
1095 point at the beginning of the comment, or at the end of a line if a new
1096 comment is to be inserted. It should return the column in which the
1097 comment ought to start. For example, in Lisp mode, the indent hook
1098 function bases its decision on how many semicolons begin an existing
1099 comment, and on the code in the preceding lines.
1102 @section Documentation Lookup
1104 Emacs provides several features you can use to look up the
1105 documentation of functions, variables and commands that you plan to
1106 use in your program.
1109 * Info Lookup:: Looking up library functions and commands in Info files.
1110 * Man Page:: Looking up man pages of library functions and commands.
1111 * Lisp Doc:: Looking up Emacs Lisp functions, etc.
1115 @subsection Info Documentation Lookup
1117 @findex info-lookup-symbol
1118 @findex info-lookup-file
1120 For major modes that apply to languages which have documentation in
1121 Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the
1122 Info documentation for a symbol used in the program. You specify the
1123 symbol with the minibuffer; the default is the symbol appearing in the
1124 buffer at point. For example, in C mode this looks for the symbol in
1125 the C Library Manual. The command only works if the appropriate
1126 manual's Info files are installed.
1128 The major mode determines where to look for documentation for the
1129 symbol---which Info files to look in, and which indices to search.
1130 You can also use @kbd{M-x info-lookup-file} to look for documentation
1133 If you use @kbd{C-h S} in a major mode that does not support it,
1134 it asks you to specify the ``symbol help mode''. You should enter
1135 a command such as @code{c-mode} that would select a major
1136 mode which @kbd{C-h S} does support.
1139 @subsection Man Page Lookup
1142 On Unix, the main form of on-line documentation was the @dfn{manual
1143 page} or @dfn{man page}. In the GNU operating system, we aim to
1144 replace man pages with better-organized manuals that you can browse
1145 with Info (@pxref{Misc Help}). This process is not finished, so it is
1146 still useful to read manual pages.
1148 @findex manual-entry
1149 You can read the man page for an operating system command, library
1150 function, or system call, with the @kbd{M-x man} command. This
1151 prompts for a topic, with completion (@pxref{Completion}), and runs
1152 the @command{man} program to format the corresponding man page. If
1153 the system permits, it runs @command{man} asynchronously, so that you
1154 can keep on editing while the page is being formatted. The result
1155 goes in a buffer named @file{*Man @var{topic}*}. These buffers use a
1156 special major mode, Man mode, that facilitates scrolling and jumping
1157 to other manual pages. For details, type @kbd{C-h m} while in a Man
1160 @cindex sections of manual pages
1161 Each man page belongs to one of ten or more @dfn{sections}, each
1162 named by a digit or by a digit and a letter. Sometimes there are man
1163 pages with the same name in different sections. To read a man page
1164 from a specific section, type @samp{@var{topic}(@var{section})} or
1165 @samp{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts
1166 for the topic. For example, the man page for the C library function
1167 @code{chmod} is in section 2, but there is a shell command of the same
1168 name, whose man page is in section 1; to view the former, type
1169 @kbd{M-x manual-entry @key{RET} chmod(2) @key{RET}}.
1171 @vindex Man-switches
1172 @kindex M-n @r{(Man mode)}
1173 @kindex M-p @r{(Man mode)}
1174 If you do not specify a section, @kbd{M-x man} normally displays
1175 only the first man page found. On some systems, the @code{man}
1176 program accepts a @samp{-a} command-line option, which tells it to
1177 display all the man pages for the specified topic. To make use of
1178 this, change the value of the variable @code{Man-switches} to
1179 @samp{"-a"}. Then, in the Man mode buffer, you can type @kbd{M-n} and
1180 @kbd{M-p} to switch between man pages in different sections. The mode
1181 line shows how many manual pages are available.
1184 @cindex manual pages, on MS-DOS/MS-Windows
1185 An alternative way of reading manual pages is the @kbd{M-x woman}
1186 command. Unlike @kbd{M-x man}, it does not run any external programs
1187 to format and display the man pages; the formatting is done by Emacs,
1188 so it works on systems such as MS-Windows where the @command{man}
1189 program may be unavailable. It prompts for a man page, and displays
1190 it in a buffer named @file{*WoMan @var{section} @var{topic}}.
1192 @kbd{M-x woman} computes the completion list for manpages the first
1193 time you invoke the command. With a numeric argument, it recomputes
1194 this list; this is useful if you add or delete manual pages.
1196 If you type a name of a manual page and @kbd{M-x woman} finds that
1197 several manual pages by the same name exist in different sections, it
1198 pops up a window with possible candidates asking you to choose one of
1201 For more information about setting up and using @kbd{M-x woman}, see
1203 @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The
1207 the WoMan Info manual, which is distributed with Emacs.
1211 @subsection Emacs Lisp Documentation Lookup
1213 When editing Emacs Lisp code, you can use the commands @kbd{C-h f}
1214 (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable})
1215 to view the built-in documentation for the Lisp functions and
1216 variables that you want to use. @xref{Name Help}.
1220 Eldoc is a buffer-local minor mode that helps with looking up Lisp
1221 documentation. When it is enabled, the echo area displays some useful
1222 information whenever there is a Lisp function or variable at point;
1223 for a function, it shows the argument list, and for a variable it
1224 shows the first line of the variable's documentation string. To
1225 toggle Eldoc mode, type @kbd{M-x eldoc-mode}. Eldoc mode can be used
1226 with the Emacs Lisp and Lisp Interaction major modes.
1229 @section Hideshow minor mode
1230 @cindex Hideshow mode
1231 @cindex mode, Hideshow
1233 @findex hs-minor-mode
1234 Hideshow mode is a buffer-local minor mode that allows you to
1235 selectively display portions of a program, which are referred to as
1236 @dfn{blocks}. Type @kbd{M-x hs-minor-mode} to toggle this minor mode
1237 (@pxref{Minor Modes}).
1239 When you use Hideshow mode to hide a block, the block disappears
1240 from the screen, to be replaced by an ellipsis (three periods in a
1241 row). Just what constitutes a block depends on the major mode. In C
1242 mode and related modes, blocks are delimited by braces, while in Lisp
1243 mode they are delimited by parentheses. Multi-line comments also
1246 Hideshow mode provides the following commands:
1249 @findex hs-hide-block
1251 @findex hs-show-block
1252 @findex hs-show-region
1253 @findex hs-hide-level
1254 @findex hs-minor-mode
1257 @kindex C-c @@ C-M-h
1258 @kindex C-c @@ C-M-s
1264 Hide the current block (@code{hs-hide-block}).
1266 Show the current block (@code{hs-show-block}).
1268 Either hide or show the current block (@code{hs-toggle-hiding}).
1270 Toggle hiding for the block you click on (@code{hs-mouse-toggle-hiding}).
1272 Hide all top-level blocks (@code{hs-hide-all}).
1274 Show all blocks in the buffer (@code{hs-show-all}).
1276 Hide all blocks @var{n} levels below this block
1277 (@code{hs-hide-level}).
1280 @vindex hs-hide-comments-when-hiding-all
1281 @vindex hs-isearch-open
1282 @vindex hs-special-modes-alist
1283 These variables can be used to customize Hideshow mode:
1286 @item hs-hide-comments-when-hiding-all
1287 If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides
1290 @item hs-isearch-open
1291 This variable specifies the conditions under which incremental search
1292 should unhide a hidden block when matching text occurs within the
1293 block. Its value should be either @code{code} (unhide only code
1294 blocks), @code{comment} (unhide only comments), @code{t} (unhide both
1295 code blocks and comments), or @code{nil} (unhide neither code blocks
1296 nor comments). The default value is @code{code}.
1299 @node Symbol Completion
1300 @section Completion for Symbol Names
1301 @cindex completion (symbol names)
1303 Completion is normally done in the minibuffer (@pxref{Completion}),
1304 but you can also complete symbol names in ordinary Emacs buffers.
1308 In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}}
1309 to complete the partial symbol before point. On graphical displays,
1310 the @kbd{M-@key{TAB}} key is usually reserved by the window manager
1311 for switching graphical windows, so you should type @kbd{C-M-i} or
1312 @kbd{@key{ESC} @key{TAB}} instead.
1314 @cindex tags-based completion
1315 @findex completion-at-point
1316 @cindex Lisp symbol completion
1317 @cindex completion (Lisp symbols)
1318 In most programming language modes, @kbd{C-M-i} (or
1319 @kbd{M-@key{TAB}}) invokes the command @code{completion-at-point},
1320 which generates its completion list in a flexible way. If Semantic
1321 mode is enabled, it tries to use the Semantic parser data for
1322 completion (@pxref{Semantic}). If Semantic mode is not enabled or
1323 fails at performing completion, it tries to complete using the
1324 selected tags table (@pxref{Tags}). If in Emacs Lisp mode, it
1325 performs completion using the function, variable, or property names
1326 defined in the current Emacs session.
1328 In all other respects, in-buffer symbol completion behaves like
1329 minibuffer completion. For instance, if Emacs cannot complete to a
1330 unique symbol, it displays a list of completion alternatives in
1331 another window. @xref{Completion}.
1333 In Text mode and related modes, @kbd{M-@key{TAB}} completes words
1334 based on the spell-checker's dictionary. @xref{Spelling}.
1336 @node MixedCase Words
1337 @section MixedCase Words
1340 Some programming styles make use of mixed-case (or ``CamelCase'')
1341 symbols like @samp{unReadableSymbol}. (In the GNU project, we recommend
1342 using underscores to separate words within an identifier, rather than
1343 using case distinctions.) Emacs has various features to make it easier
1344 to deal with such symbols.
1346 @cindex Glasses mode
1347 @findex mode, Glasses
1348 Glasses mode is a buffer-local minor mode that makes it easier to read
1349 such symbols, by altering how they are displayed. By default, it
1350 displays extra underscores between each lower-case letter and the
1351 following capital letter. This does not alter the buffer text, only how
1354 To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor
1355 Modes}). When Glasses mode is enabled, the minor mode indicator
1356 @samp{o^o} appears in the mode line. For more information about
1357 Glasses mode, type @kbd{C-h P glasses @key{RET}}.
1359 @cindex Subword mode
1360 @findex subword-mode
1361 Subword mode is another buffer-local minor mode. In subword mode,
1362 Emacs's word commands recognize upper case letters in
1363 @samp{StudlyCapsIdentifiers} as word boundaries. When Subword mode is
1364 enabled, the minor mode indicator @samp{,} appears in the mode line.
1365 See also the similar @code{superword-mode} (@pxref{Misc for Programs}).
1369 @cindex Semantic package
1371 Semantic is a package that provides language-aware editing commands
1372 based on @code{source code parsers}. This section provides a brief
1373 description of Semantic; for full details,
1375 see @ref{Top, Semantic,, semantic, Semantic}.
1378 see the Semantic Info manual, which is distributed with Emacs.
1381 Most of the ``language aware'' features in Emacs, such as Font Lock
1382 mode (@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular
1383 expressions and syntax tables.} that usually give good results but are
1384 never completely exact. In contrast, the parsers used by Semantic
1385 have an exact understanding of programming language syntax. This
1386 allows Semantic to provide search, navigation, and completion commands
1387 that are powerful and precise.
1389 @cindex Semantic mode
1390 @cindex mode, Semantic
1391 To begin using Semantic, type @kbd{M-x semantic-mode} or click on
1392 the menu item named @samp{Source Code Parsers (Semantic)} in the
1393 @samp{Tools} menu. This enables Semantic mode, a global minor mode.
1395 When Semantic mode is enabled, Emacs automatically attempts to
1396 parse each file you visit. Currently, Semantic understands C, C++,
1397 Scheme, Javascript, Java, HTML, and Make. Within each parsed buffer,
1398 the following commands are available:
1403 Prompt for the name of a function defined in the current file, and
1404 move point there (@code{semantic-complete-jump-local}).
1408 Prompt for the name of a function defined in any file Emacs has
1409 parsed, and move point there (@code{semantic-complete-jump}).
1411 @item C-c , @key{SPC}
1412 @kindex C-c , @key{SPC}
1413 Display a list of possible completions for the symbol at point
1414 (@code{semantic-complete-analyze-inline}). This also activates a set
1415 of special key bindings for choosing a completion: @key{RET} accepts
1416 the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible
1417 completions, @key{TAB} completes as far as possible and then cycles,
1418 and @kbd{C-g} or any other key aborts completion.
1422 Display a list of the possible completions of the symbol at point, in
1423 another window (@code{semantic-analyze-possible-completions}).
1427 In addition to the above commands, the Semantic package provides a
1428 variety of other ways to make use of parser information. For
1429 instance, you can use it to display a list of completions when Emacs
1432 @xref{Top, Semantic,, semantic, Semantic}, for details.
1435 @node Misc for Programs
1436 @section Other Features Useful for Editing Programs
1438 Some Emacs commands that aren't designed specifically for editing
1439 programs are useful for that nonetheless.
1441 The Emacs commands that operate on words, sentences and paragraphs
1442 are useful for editing code. Most symbols names contain words
1443 (@pxref{Words}), while sentences can be found in strings and comments
1444 (@pxref{Sentences}). As for paragraphs, they are defined in most
1445 programming language modes to begin and end at blank lines
1446 (@pxref{Paragraphs}). Therefore, judicious use of blank lines to make
1447 the program clearer will also provide useful chunks of text for the
1448 paragraph commands to work on. Auto Fill mode, if enabled in a
1449 programming language major mode, indents the new lines which it
1452 @findex superword-mode
1453 Superword mode is a buffer-local minor mode that causes editing and
1454 motion commands to treat symbols (e.g., @samp{this_is_a_symbol}) as words.
1455 When Subword mode is enabled, the minor mode indicator
1462 appears in the mode line. See also the similar @code{subword-mode}
1463 (@pxref{MixedCase Words}).
1465 @findex electric-layout-mode
1466 Electric Layout mode (@kbd{M-x electric-layout-mode}) is a global
1467 minor mode that automatically inserts newlines when you type certain
1468 characters; for example, @samp{@{}, @samp{@}} and @samp{;} in Javascript
1471 Apart from Hideshow mode (@pxref{Hideshow}), another way to
1472 selectively display parts of a program is to use the selective display
1473 feature (@pxref{Selective Display}). Programming modes often also
1474 support Outline minor mode (@pxref{Outline Mode}), which can be used
1475 with the Foldout package (@pxref{Foldout}).
1478 The ``automatic typing'' features may be useful for writing programs.
1479 @xref{Top,,Autotyping, autotype, Autotyping}.
1483 @section C and Related Modes
1488 @cindex CORBA IDL mode
1489 @cindex Objective C mode
1495 @cindex mode, Objective C
1496 @cindex mode, CORBA IDL
1500 This section gives a brief description of the special features
1501 available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
1502 (These are called ``C mode and related modes''.)
1504 @xref{Top,, CC Mode, ccmode, CC Mode}, for more details.
1507 For more details, see the CC mode Info manual, which is distributed
1512 * Motion in C:: Commands to move by C statements, etc.
1513 * Electric C:: Colon and other chars can automatically reindent.
1514 * Hungry Delete:: A more powerful DEL command.
1515 * Other C Commands:: Filling comments, viewing expansion of macros,
1516 and other neat features.
1520 @subsection C Mode Motion Commands
1522 This section describes commands for moving point, in C mode and
1528 @findex c-beginning-of-defun
1529 @findex c-end-of-defun
1530 Move point to the beginning or end of the current function or
1531 top-level definition. In languages with enclosing scopes (such as
1532 C++'s classes) the @dfn{current function} is the immediate one,
1533 possibly inside a scope. Otherwise it is the one defined by the least
1534 enclosing braces. (By contrast, @code{beginning-of-defun} and
1535 @code{end-of-defun} search for braces in column zero.) @xref{Moving
1539 @kindex C-c C-u @r{(C mode)}
1540 @findex c-up-conditional
1541 Move point back to the containing preprocessor conditional, leaving the
1542 mark behind. A prefix argument acts as a repeat count. With a negative
1543 argument, move point forward to the end of the containing
1544 preprocessor conditional.
1546 @samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so
1547 the function will stop at a @samp{#elif} when going backward, but not
1551 @kindex C-c C-p @r{(C mode)}
1552 @findex c-backward-conditional
1553 Move point back over a preprocessor conditional, leaving the mark
1554 behind. A prefix argument acts as a repeat count. With a negative
1555 argument, move forward.
1558 @kindex C-c C-n @r{(C mode)}
1559 @findex c-forward-conditional
1560 Move point forward across a preprocessor conditional, leaving the mark
1561 behind. A prefix argument acts as a repeat count. With a negative
1562 argument, move backward.
1565 @kindex M-a (C mode)
1566 @findex c-beginning-of-statement
1567 Move point to the beginning of the innermost C statement
1568 (@code{c-beginning-of-statement}). If point is already at the beginning
1569 of a statement, move to the beginning of the preceding statement. With
1570 prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
1572 In comments or in strings which span more than one line, this command
1573 moves by sentences instead of statements.
1576 @kindex M-e (C mode)
1577 @findex c-end-of-statement
1578 Move point to the end of the innermost C statement or sentence; like
1579 @kbd{M-a} except that it moves in the other direction
1580 (@code{c-end-of-statement}).
1584 @subsection Electric C Characters
1586 In C mode and related modes, certain printing characters are
1587 @dfn{electric}---in addition to inserting themselves, they also
1588 reindent the current line, and optionally also insert newlines. The
1589 ``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#},
1590 @kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and
1593 You might find electric indentation inconvenient if you are editing
1594 chaotically indented code. If you are new to CC Mode, you might find
1595 it disconcerting. You can toggle electric action with the command
1596 @kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line
1597 after the mode name:
1601 @kindex C-c C-l @r{(C mode)}
1602 @findex c-toggle-electric-state
1603 Toggle electric action (@code{c-toggle-electric-state}). With a
1604 positive prefix argument, this command enables electric action, with a
1605 negative one it disables it.
1608 Electric characters insert newlines only when, in addition to the
1609 electric state, the @dfn{auto-newline} feature is enabled (indicated
1610 by @samp{/la} in the mode line after the mode name). You can turn
1611 this feature on or off with the command @kbd{C-c C-a}:
1615 @kindex C-c C-a @r{(C mode)}
1616 @findex c-toggle-auto-newline
1617 Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a
1618 prefix argument, this command turns the auto-newline feature on if the
1619 argument is positive, and off if it is negative.
1622 Usually the CC Mode style configures the exact circumstances in
1623 which Emacs inserts auto-newlines. You can also configure this
1624 directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}.
1627 @subsection Hungry Delete Feature in C
1628 @cindex hungry deletion (C Mode)
1630 If you want to delete an entire block of whitespace at point, you
1631 can use @dfn{hungry deletion}. This deletes all the contiguous
1632 whitespace either before point or after point in a single operation.
1633 @dfn{Whitespace} here includes tabs and newlines, but not comments or
1634 preprocessor commands.
1637 @item C-c C-@key{DEL}
1638 @itemx C-c @key{DEL}
1639 @findex c-hungry-delete-backwards
1640 @kindex C-c C-@key{DEL} (C Mode)
1641 @kindex C-c @key{DEL} (C Mode)
1642 Delete the entire block of whitespace preceding point (@code{c-hungry-delete-backwards}).
1645 @itemx C-c C-@key{DELETE}
1646 @itemx C-c @key{DELETE}
1647 @findex c-hungry-delete-forward
1648 @kindex C-c C-d (C Mode)
1649 @kindex C-c C-@key{DELETE} (C Mode)
1650 @kindex C-c @key{DELETE} (C Mode)
1651 Delete the entire block of whitespace after point (@code{c-hungry-delete-forward}).
1654 As an alternative to the above commands, you can enable @dfn{hungry
1655 delete mode}. When this feature is enabled (indicated by @samp{/h} in
1656 the mode line after the mode name), a single @key{DEL} deletes all
1657 preceding whitespace, not just one space, and a single @kbd{C-c C-d}
1658 (but @emph{not} plain @key{DELETE}) deletes all following whitespace.
1661 @item M-x c-toggle-hungry-state
1662 @findex c-toggle-hungry-state
1663 Toggle the hungry-delete feature
1664 (@code{c-toggle-hungry-state}). With a prefix argument,
1665 this command turns the hungry-delete feature on if the argument is
1666 positive, and off if it is negative.
1669 @vindex c-hungry-delete-key
1670 The variable @code{c-hungry-delete-key} controls whether the
1671 hungry-delete feature is enabled.
1673 @node Other C Commands
1674 @subsection Other Commands for C Mode
1677 @item M-x c-context-line-break
1678 @findex c-context-line-break
1679 This command inserts a line break and indents the new line in a manner
1680 appropriate to the context. In normal code, it does the work of
1681 @key{RET} (@code{newline}), in a C preprocessor line it additionally
1682 inserts a @samp{\} at the line break, and within comments it's like
1683 @kbd{M-j} (@code{c-indent-new-comment-line}).
1685 @code{c-context-line-break} isn't bound to a key by default, but it
1686 needs a binding to be useful. The following code will bind it to
1687 @kbd{RET}. We use @code{c-initialization-hook} here to make sure
1688 the keymap is loaded before we try to change it.
1691 (defun my-bind-clb ()
1692 (define-key c-mode-base-map "\C-m"
1693 'c-context-line-break))
1694 (add-hook 'c-initialization-hook 'my-bind-clb)
1698 Put mark at the end of a function definition, and put point at the
1699 beginning (@code{c-mark-function}).
1702 @kindex M-q @r{(C mode)}
1703 @findex c-fill-paragraph
1704 Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
1705 If any part of the current line is a comment or within a comment, this
1706 command fills the comment or the paragraph of it that point is in,
1707 preserving the comment indentation and comment delimiters.
1710 @cindex macro expansion in C
1711 @cindex expansion of C macros
1712 @findex c-macro-expand
1713 @kindex C-c C-e @r{(C mode)}
1714 Run the C preprocessor on the text in the region, and show the result,
1715 which includes the expansion of all the macro calls
1716 (@code{c-macro-expand}). The buffer text before the region is also
1717 included in preprocessing, for the sake of macros defined there, but the
1718 output from this part isn't shown.
1720 When you are debugging C code that uses macros, sometimes it is hard to
1721 figure out precisely how the macros expand. With this command, you
1722 don't have to figure it out; you can see the expansions.
1725 @findex c-backslash-region
1726 @kindex C-c C-\ @r{(C mode)}
1727 Insert or align @samp{\} characters at the ends of the lines of the
1728 region (@code{c-backslash-region}). This is useful after writing or
1729 editing a C macro definition.
1731 If a line already ends in @samp{\}, this command adjusts the amount of
1732 whitespace before it. Otherwise, it inserts a new @samp{\}. However,
1733 the last line in the region is treated specially; no @samp{\} is
1734 inserted on that line, and any @samp{\} there is deleted.
1736 @item M-x cpp-highlight-buffer
1737 @cindex preprocessor highlighting
1738 @findex cpp-highlight-buffer
1739 Highlight parts of the text according to its preprocessor conditionals.
1740 This command displays another buffer named @file{*CPP Edit*}, which
1741 serves as a graphic menu for selecting how to display particular kinds
1742 of conditionals and their contents. After changing various settings,
1743 click on @samp{[A]pply these settings} (or go to that buffer and type
1744 @kbd{a}) to rehighlight the C mode buffer accordingly.
1747 @findex c-show-syntactic-information
1748 @kindex C-c C-s @r{(C mode)}
1749 Display the syntactic information about the current source line
1750 (@code{c-show-syntactic-information}). This information directs how
1751 the line is indented.
1753 @item M-x cwarn-mode
1754 @itemx M-x global-cwarn-mode
1756 @findex global-cwarn-mode
1757 @vindex global-cwarn-mode
1759 @cindex suspicious constructions in C, C++
1760 CWarn minor mode highlights certain suspicious C and C++ constructions:
1764 Assignments inside expressions.
1766 Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
1767 (except after a @samp{do @dots{} while} statement);
1769 C++ functions with reference parameters.
1773 You can enable the mode for one buffer with the command @kbd{M-x
1774 cwarn-mode}, or for all suitable buffers with the command @kbd{M-x
1775 global-cwarn-mode} or by customizing the variable
1776 @code{global-cwarn-mode}. You must also enable Font Lock mode to make
1779 @item M-x hide-ifdef-mode
1780 @findex hide-ifdef-mode
1781 @cindex Hide-ifdef mode
1782 @vindex hide-ifdef-shadow
1783 Hide-ifdef minor mode hides selected code within @samp{#if} and
1784 @samp{#ifdef} preprocessor blocks. If you change the variable
1785 @code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode
1786 ``shadows'' preprocessor blocks by displaying them with a less
1787 prominent face, instead of hiding them entirely. See the
1788 documentation string of @code{hide-ifdef-mode} for more information.
1790 @item M-x ff-find-related-file
1791 @cindex related files
1792 @findex ff-find-related-file
1793 @vindex ff-related-file-alist
1794 Find a file ``related'' in a special way to the file visited by the
1795 current buffer. Typically this will be the header file corresponding
1796 to a C/C++ source file, or vice versa. The variable
1797 @code{ff-related-file-alist} specifies how to compute related file
1805 @cindex assembler mode
1806 Asm mode is a major mode for editing files of assembler code. It
1807 defines these commands:
1811 @code{tab-to-tab-stop}.
1812 @c FIXME: Maybe this should be consistent with other programming modes.
1814 Insert a newline and then indent using @code{tab-to-tab-stop}.
1816 Insert a colon and then remove the indentation from before the label
1817 preceding colon. Then do @code{tab-to-tab-stop}.
1819 Insert or align a comment.
1822 The variable @code{asm-comment-char} specifies which character
1823 starts comments in assembler syntax.
1826 @include fortran-xtra.texi