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
371 (@code{newline-and-indent}).
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 @kindex C-j @r{(indenting source code)}
386 @findex newline-and-indent
387 The command @kbd{C-j} (@code{newline-and-indent}), which was
388 documented in @ref{Indentation Commands}, does the same as @key{RET}
389 followed by @key{TAB}: it inserts a new line, then adjusts the line's
392 When indenting a line that starts within a parenthetical grouping,
393 Emacs usually places the start of the line under the preceding line
394 within the group, or under the text after the parenthesis. If you
395 manually give one of these lines a nonstandard indentation (e.g., for
396 aesthetic purposes), the lines below will follow it.
398 The indentation commands for most programming language modes assume
399 that a open-parenthesis, open-brace or other opening delimiter at the
400 left margin is the start of a function. If the code you are editing
401 violates this assumption---even if the delimiters occur in strings or
402 comments---you must set @code{open-paren-in-column-0-is-defun-start}
403 to @code{nil} for indentation to work properly. @xref{Left Margin
406 @node Multi-line Indent
407 @subsection Indenting Several Lines
409 Sometimes, you may want to reindent several lines of code at a time.
410 One way to do this is to use the mark; when the mark is active and the
411 region is non-empty, @key{TAB} indents every line in the region.
412 Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents
413 every line in the region, whether or not the mark is active
414 (@pxref{Indentation Commands}).
416 In addition, Emacs provides the following commands for indenting
417 large chunks of code:
421 Reindent all the lines within one parenthetical grouping.
423 Shift an entire parenthetical grouping rigidly sideways so that its
424 first line is properly indented.
425 @item M-x indent-code-rigidly
426 Shift all the lines in the region rigidly sideways, but do not alter
427 lines that start inside comments and strings.
431 @findex indent-pp-sexp
432 To reindent the contents of a single parenthetical grouping,
433 position point before the beginning of the grouping and type
434 @kbd{C-M-q}. This changes the relative indentation within the
435 grouping, without affecting its overall indentation (i.e., the
436 indentation of the line where the grouping starts). The function that
437 @kbd{C-M-q} runs depends on the major mode; it is
438 @code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode,
439 etc. To correct the overall indentation as well, type @key{TAB}
443 If you like the relative indentation within a grouping but not the
444 indentation of its first line, move point to that first line and type
445 @kbd{C-u @key{TAB}}. In Lisp, C, and some other major modes,
446 @key{TAB} with a numeric argument reindents the current line as usual,
447 then reindents by the same amount all the lines in the parenthetical
448 grouping starting on the current line. It is clever, though, and does
449 not alter lines that start inside strings. Neither does it alter C
450 preprocessor lines when in C mode, but it does reindent any
451 continuation lines that may be attached to them.
453 @findex indent-code-rigidly
454 The command @kbd{M-x indent-code-rigidly} rigidly shifts all the
455 lines in the region sideways, like @code{indent-rigidly} does
456 (@pxref{Indentation Commands}). It doesn't alter the indentation of
457 lines that start inside a string, unless the region also starts inside
458 that string. The prefix arg specifies the number of columns to
462 @subsection Customizing Lisp Indentation
463 @cindex customizing Lisp indentation
465 The indentation pattern for a Lisp expression can depend on the function
466 called by the expression. For each Lisp function, you can choose among
467 several predefined patterns of indentation, or define an arbitrary one with
470 The standard pattern of indentation is as follows: the second line of the
471 expression is indented under the first argument, if that is on the same
472 line as the beginning of the expression; otherwise, the second line is
473 indented underneath the function name. Each following line is indented
474 under the previous line whose nesting depth is the same.
476 @vindex lisp-indent-offset
477 If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
478 the usual indentation pattern for the second line of an expression, so that
479 such lines are always indented @code{lisp-indent-offset} more columns than
482 @vindex lisp-body-indent
483 Certain functions override the standard pattern. Functions whose
484 names start with @code{def} treat the second lines as the start of
485 a @dfn{body}, by indenting the second line @code{lisp-body-indent}
486 additional columns beyond the open-parenthesis that starts the
489 @cindex @code{lisp-indent-function} property
490 You can override the standard pattern in various ways for individual
491 functions, according to the @code{lisp-indent-function} property of
492 the function name. This is normally done for macro definitions, using
493 the @code{declare} construct. @xref{Defining Macros,,, elisp, the
494 Emacs Lisp Reference Manual}.
497 @subsection Commands for C Indentation
499 Here are special features for indentation in C mode and related modes:
503 @kindex C-c C-q @r{(C mode)}
504 @findex c-indent-defun
505 Reindent the current top-level function definition or aggregate type
506 declaration (@code{c-indent-defun}).
509 @kindex C-M-q @r{(C mode)}
511 Reindent each line in the balanced expression that follows point
512 (@code{c-indent-exp}). A prefix argument inhibits warning messages
513 about invalid syntax.
516 @findex c-indent-command
517 Reindent the current line, and/or in some cases insert a tab character
518 (@code{c-indent-command}).
520 @vindex c-tab-always-indent
521 If @code{c-tab-always-indent} is @code{t}, this command always reindents
522 the current line and does nothing else. This is the default.
524 If that variable is @code{nil}, this command reindents the current line
525 only if point is at the left margin or in the line's indentation;
526 otherwise, it inserts a tab (or the equivalent number of spaces,
527 if @code{indent-tabs-mode} is @code{nil}).
529 Any other value (not @code{nil} or @code{t}) means always reindent the
530 line, and also insert a tab if within a comment or a string.
533 To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This
534 first selects the whole buffer as the region, then reindents that
537 To reindent the current block, use @kbd{C-M-u C-M-q}. This moves
538 to the front of the block and then reindents it all.
540 @node Custom C Indent
541 @subsection Customizing C Indentation
542 @cindex style (for indentation)
544 C mode and related modes use a flexible mechanism for customizing
545 indentation. C mode indents a source line in two steps: first it
546 classifies the line syntactically according to its contents and
547 context; second, it determines the indentation offset associated by
548 your selected @dfn{style} with the syntactic construct and adds this
549 onto the indentation of the @dfn{anchor statement}.
552 @item C-c . @key{RET} @var{style} @key{RET}
553 Select a predefined style @var{style} (@code{c-set-style}).
556 A @dfn{style} is a named collection of customizations that can be
557 used in C mode and the related modes. @ref{Styles,,, ccmode, The CC
558 Mode Manual}, for a complete description. Emacs comes with several
559 predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
560 @code{stroustrup}, @code{linux}, @code{python}, @code{java},
561 @code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these
562 styles are primarily intended for one language, but any of them can be
563 used with any of the languages supported by these modes. To find out
564 what a style looks like, select it and reindent some code, e.g., by
565 typing @key{C-M-q} at the start of a function definition.
567 @kindex C-c . @r{(C mode)}
569 To choose a style for the current buffer, use the command @w{@kbd{C-c
570 .}}. Specify a style name as an argument (case is not significant).
571 This command affects the current buffer only, and it affects only
572 future invocations of the indentation commands; it does not reindent
573 the code already in the buffer. To reindent the whole buffer in the
574 new style, you can type @kbd{C-x h C-M-\}.
576 @vindex c-default-style
577 You can also set the variable @code{c-default-style} to specify the
578 default style for various major modes. Its value should be either the
579 style's name (a string) or an alist, in which each element specifies
580 one major mode and which indentation style to use for it. For
584 (setq c-default-style
585 '((java-mode . "java")
591 specifies explicit choices for Java and AWK modes, and the default
592 @samp{gnu} style for the other C-like modes. (These settings are
593 actually the defaults.) This variable takes effect when you select
594 one of the C-like major modes; thus, if you specify a new default
595 style for Java mode, you can make it take effect in an existing Java
596 mode buffer by typing @kbd{M-x java-mode} there.
598 The @code{gnu} style specifies the formatting recommended by the GNU
599 Project for C; it is the default, so as to encourage use of our
602 @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and
603 @ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more
604 information on customizing indentation for C and related modes,
605 including how to override parts of an existing style and how to define
609 @findex c-guess-install
610 As an alternative to specifying a style, you can tell Emacs to guess
611 a style by typing @kbd{M-x c-guess} in a sample code buffer. You can
612 then apply the guessed style to other buffers with @kbd{M-x
613 c-guess-install}. @xref{Guessing the Style,,, ccmode, the CC Mode
614 Manual}, for details.
617 @section Commands for Editing with Parentheses
620 @cindex unbalanced parentheses and quotes
621 This section describes the commands and features that take advantage
622 of the parenthesis structure in a program, or help you keep it
625 When talking about these facilities, the term ``parenthesis'' also
626 includes braces, brackets, or whatever delimiters are defined to match
627 in pairs. The major mode controls which delimiters are significant,
628 through the syntax table (@pxref{Syntax Tables,, Syntax Tables, elisp,
629 The Emacs Lisp Reference Manual}). In Lisp, only parentheses count;
630 in C, these commands apply to braces and brackets too.
632 You can use @kbd{M-x check-parens} to find any unbalanced
633 parentheses and unbalanced string quotes in the buffer.
636 * Expressions:: Expressions with balanced parentheses.
637 * Moving by Parens:: Commands for moving up, down and across
638 in the structure of parentheses.
639 * Matching:: Insertion of a close-delimiter flashes matching open.
643 @subsection Expressions with Balanced Parentheses
647 @cindex balanced expression
648 Each programming language mode has its own definition of a
649 @dfn{balanced expression}. Balanced expressions typically include
650 individual symbols, numbers, and string constants, as well as pieces
651 of code enclosed in a matching pair of delimiters. The following
652 commands deal with balanced expressions (in Emacs, such expressions
653 are referred to internally as @dfn{sexps}@footnote{The word ``sexp''
654 is used to refer to an expression in Lisp.}).
658 Move forward over a balanced expression (@code{forward-sexp}).
660 Move backward over a balanced expression (@code{backward-sexp}).
662 Kill balanced expression forward (@code{kill-sexp}).
664 Transpose expressions (@code{transpose-sexps}).
667 Put mark after following expression (@code{mark-sexp}).
673 @findex backward-sexp
674 To move forward over a balanced expression, use @kbd{C-M-f}
675 (@code{forward-sexp}). If the first significant character after point
676 is an opening delimiter (e.g., @samp{(}, @samp{[} or @samp{@{} in C),
677 this command moves past the matching closing delimiter. If the
678 character begins a symbol, string, or number, the command moves over
681 The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
682 balanced expression---like @kbd{C-M-f}, but in the reverse direction.
683 If the expression is preceded by any prefix characters (single-quote,
684 backquote and comma, in Lisp), the command moves back over them as
687 @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation
688 the specified number of times; with a negative argument means to move
689 in the opposite direction. In most modes, these two commands move
690 across comments as if they were whitespace. Note that their keys,
691 @kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b},
692 which move by characters (@pxref{Moving Point}), and @kbd{M-f} and
693 @kbd{M-b}, which move by words (@pxref{Words}).
695 @cindex killing expressions
698 To kill a whole balanced expression, type @kbd{C-M-k}
699 (@code{kill-sexp}). This kills the text that @kbd{C-M-f} would move
702 @cindex transposition of expressions
704 @findex transpose-sexps
705 @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the
706 previous balanced expression and the next one. It is analogous to the
707 @kbd{C-t} command, which transposes characters (@pxref{Transpose}).
708 An argument to @kbd{C-M-t} serves as a repeat count, moving the
709 previous expression over that many following ones. A negative
710 argument moves the previous balanced expression backwards across those
711 before it. An argument of zero, rather than doing nothing, transposes
712 the balanced expressions ending at or after point and the mark.
715 @kindex C-M-@key{SPC}
717 To operate on balanced expressions with a command which acts on the
718 region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}). This sets the
719 mark where @kbd{C-M-f} would move to. While the mark is active, each
720 successive call to this command extends the region by shifting the
721 mark by one expression. Positive or negative numeric arguments move
722 the mark forward or backward by the specified number of expressions.
723 The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}.
724 @xref{Marking Objects}, for more information about this and related
727 In languages that use infix operators, such as C, it is not possible
728 to recognize all balanced expressions because there can be multiple
729 possibilities at a given position. For example, C mode does not treat
730 @samp{foo + bar} as a single expression, even though it @emph{is} one
731 C expression; instead, it recognizes @samp{foo} as one expression and
732 @samp{bar} as another, with the @samp{+} as punctuation between them.
733 However, C mode recognizes @samp{(foo + bar)} as a single expression,
734 because of the parentheses.
736 @node Moving by Parens
737 @subsection Moving in the Parenthesis Structure
739 @cindex parenthetical groupings
740 @cindex parentheses, moving across
741 @cindex matching parenthesis and braces, moving to
742 @cindex braces, moving across
743 @cindex list commands
745 The following commands move over groupings delimited by parentheses
746 (or whatever else serves as delimiters in the language you are working
747 with). They ignore strings and comments, including any parentheses
748 within them, and also ignore parentheses that are ``quoted'' with an
749 escape character. These commands are mainly intended for editing
750 programs, but can be useful for editing any text containing
751 parentheses. They are referred to internally as ``list'' commands
752 because in Lisp these groupings are lists.
754 These commands assume that the starting point is not inside a string
755 or a comment. If you invoke them from inside a string or comment, the
756 results are unreliable.
760 Move forward over a parenthetical group (@code{forward-list}).
762 Move backward over a parenthetical group (@code{backward-list}).
764 Move up in parenthesis structure (@code{backward-up-list}).
766 Move down in parenthesis structure (@code{down-list}).
772 @findex backward-list
773 The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and
774 @kbd{C-M-p} (@code{backward-list}) move forward or backward over one
775 (or @var{n}) parenthetical groupings.
778 @findex backward-up-list
779 @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
780 parenthesis structure. To move @emph{up} one (or @var{n}) levels, use
781 @kbd{C-M-u} (@code{backward-up-list}). @kbd{C-M-u} moves backward up
782 past one unmatched opening delimiter. A positive argument serves as a
783 repeat count; a negative argument reverses the direction of motion, so
784 that the command moves forward and up one or more levels.
788 To move @emph{down} in the parenthesis structure, use @kbd{C-M-d}
789 (@code{down-list}). In Lisp mode, where @samp{(} is the only opening
790 delimiter, this is nearly the same as searching for a @samp{(}. An
791 argument specifies the number of levels to go down.
794 @subsection Matching Parentheses
795 @cindex matching parentheses
796 @cindex parentheses, displaying matches
798 Emacs has a number of @dfn{parenthesis matching} features, which
799 make it easy to see how and whether parentheses (or other delimiters)
802 Whenever you type a self-inserting character that is a closing
803 delimiter, the cursor moves momentarily to the location of the
804 matching opening delimiter, provided that is on the screen. If it is
805 not on the screen, Emacs displays some of the text near it in the echo
806 area. Either way, you can tell which grouping you are closing off.
807 If the opening delimiter and closing delimiter are mismatched---such
808 as in @samp{[x)}---a warning message is displayed in the echo area.
810 @vindex blink-matching-paren
811 @vindex blink-matching-paren-distance
812 @vindex blink-matching-delay
813 Three variables control the display of matching parentheses:
817 @code{blink-matching-paren} turns the feature on or off: @code{nil}
818 disables it, but the default is @code{t} to enable it.
821 @code{blink-matching-delay} says how many seconds to leave the cursor
822 on the matching opening delimiter, before bringing it back to the real
823 location of point. This may be an integer or floating-point number;
827 @code{blink-matching-paren-distance} specifies how many characters
828 back to search to find the matching opening delimiter. If the match
829 is not found in that distance, Emacs stops scanning and nothing is
830 displayed. The default is 102400.
833 @cindex Show Paren mode
834 @cindex highlighting matching parentheses
835 @findex show-paren-mode
836 Show Paren mode, a global minor mode, provides a more powerful kind
837 of automatic matching. Whenever point is before an opening delimiter
838 or after a closing delimiter, both that delimiter and its opposite
839 delimiter are highlighted. To toggle Show Paren mode, type @kbd{M-x
842 @cindex Electric Pair mode
843 @cindex inserting matching parentheses
844 @findex electric-pair-mode
845 Electric Pair mode, a global minor mode, provides a way to easily
846 insert matching delimiters. Whenever you insert an opening delimiter,
847 the matching closing delimiter is automatically inserted as well,
848 leaving point between the two. Conversely, when you insert a closing
849 delimiter over an existing one, no inserting takes places and that
850 position is simply skipped over. These variables control additional
851 features of Electric Pair mode:
855 @code{electric-pair-preserve-balance}, when non-@code{nil}, makes the
856 default pairing logic balance out the number of opening and closing
860 @code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes
861 backspacing between two adjacent delimiters also automatically delete
862 the closing delimiter.
865 @code{electric-pair-open-newline-between-pairs}, when non-@code{nil},
866 makes inserting inserting a newline between two adjacent pairs also
867 automatically open and extra newline after point.
870 @code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor
871 mode to skip whitespace forward before deciding whether to skip over
872 the closing delimiter.
875 To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}.
878 @section Manipulating Comments
881 Because comments are such an important part of programming, Emacs
882 provides special commands for editing and inserting comments. It can
883 also do spell checking on comments with Flyspell Prog mode
886 Some major modes have special rules for indenting different kinds of
887 comments. For example, in Lisp code, comments starting with two
888 semicolons are indented as if they were lines of code, while those
889 starting with three semicolons are supposed to be aligned to the left
890 margin and are often used for sectioning purposes. Emacs understand
891 these conventions; for instance, typing @key{TAB} on a comment line
892 will indent the comment to the appropriate position.
895 ;; This function is just an example.
896 ;;; Here either two or three semicolons are appropriate.
898 ;;; And now, the first part of the function:
899 ;; The following line adds one.
900 (1+ x)) ; This line adds one.
904 * Comment Commands:: Inserting, killing, and aligning comments.
905 * Multi-Line Comments:: Commands for adding and editing multi-line comments.
906 * Options for Comments::Customizing the comment features.
909 @node Comment Commands
910 @subsection Comment Commands
911 @cindex indentation for comments
912 @cindex alignment for comments
914 The following commands operate on comments:
918 Insert or realign comment on current line; if the region is active,
919 comment or uncomment the region instead (@code{comment-dwim}).
921 Kill comment on current line (@code{comment-kill}).
923 Set comment column (@code{comment-set-column}).
926 Like @key{RET} followed by inserting and aligning a comment
927 (@code{comment-indent-new-line}). @xref{Multi-Line Comments}.
928 @item @kbd{M-x comment-region}
929 @itemx @kbd{C-c C-c} (in C-like modes)
930 Add comment delimiters to all the lines in the region.
935 The command to create or align a comment is @kbd{M-;}
936 (@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What
937 I Mean''; it indicates that this command can be used for many
938 different jobs relating to comments, depending on the situation where
941 When a region is active (@pxref{Mark}), @kbd{M-;} either adds
942 comment delimiters to the region, or removes them. If every line in
943 the region is already a comment, it ``uncomments'' each of those lines
944 by removing their comment delimiters. Otherwise, it adds comment
945 delimiters to enclose the text in the region.
947 If you supply a prefix argument to @kbd{M-;} when a region is
948 active, that specifies the number of comment delimiters to add or
949 delete. A positive argument @var{n} adds @var{n} delimiters, while a
950 negative argument @var{-n} removes @var{n} delimiters.
952 If the region is not active, and there is no existing comment on the
953 current line, @kbd{M-;} adds a new comment to the current line. If
954 the line is blank (i.e., empty or containing only whitespace
955 characters), the comment is indented to the same position where
956 @key{TAB} would indent to (@pxref{Basic Indent}). If the line is
957 non-blank, the comment is placed after the last non-whitespace
958 character on the line; normally, Emacs tries putting it at the column
959 specified by the variable @code{comment-column} (@pxref{Options for
960 Comments}), but if the line already extends past that column, it puts
961 the comment at some suitable position, usually separated from the
962 non-comment text by at least one space. In each case, Emacs places
963 point after the comment's starting delimiter, so that you can start
964 typing the comment text right away.
966 You can also use @kbd{M-;} to align an existing comment. If a line
967 already contains the comment-start string, @kbd{M-;} realigns it to
968 the conventional alignment and moves point after the comment's
969 starting delimiter. As an exception, comments starting in column 0
970 are not moved. Even when an existing comment is properly aligned,
971 @kbd{M-;} is still useful for moving directly to the start of the
976 @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any
977 comment on the current line, along with the whitespace before it.
978 Since the comment is saved to the kill ring, you can reinsert it on
979 another line by moving to the end of that line, doing @kbd{C-y}, and
980 then @kbd{M-;} to realign the comment. You can achieve the same
981 effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill}
982 (@code{comment-dwim} actually calls @code{comment-kill} as a
983 subroutine when it is given a prefix argument).
985 @kindex C-c C-c (C mode)
986 @findex comment-region
987 @findex uncomment-region
988 The command @kbd{M-x comment-region} is equivalent to calling
989 @kbd{M-;} on an active region, except that it always acts on the
990 region, even if the mark is inactive. In C mode and related modes,
991 this command is bound to @kbd{C-c C-c}. The command @kbd{M-x
992 uncomment-region} uncomments each line in the region; a numeric prefix
993 argument specifies the number of comment delimiters to remove
994 (negative arguments specify the number of comment to delimiters to
997 For C-like modes, you can configure the exact effect of @kbd{M-;} by
998 setting the variables @code{c-indent-comment-alist} and
999 @code{c-indent-comments-syntactically-p}. For example, on a line
1000 ending in a closing brace, @kbd{M-;} puts the comment one space after
1001 the brace rather than at @code{comment-column}. For full details see
1002 @ref{Comment Commands,,, ccmode, The CC Mode Manual}.
1004 @node Multi-Line Comments
1005 @subsection Multiple Lines of Comments
1009 @cindex blank lines in programs
1010 @findex comment-indent-new-line
1011 @vindex comment-multi-line
1012 If you are typing a comment and wish to continue it to another line,
1013 type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}). This
1014 breaks the current line, and inserts the necessary comment delimiters
1015 and indentation to continue the comment.
1017 For languages with closing comment delimiters (e.g., @samp{*/} in
1018 C), the exact behavior of @kbd{M-j} depends on the value of the
1019 variable @code{comment-multi-line}. If the value is @code{nil}, the
1020 command closes the comment on the old line and starts a new comment on
1021 the new line. Otherwise, it opens a new line within the current
1024 When Auto Fill mode is on, going past the fill column while typing a
1025 comment also continues the comment, in the same way as an explicit
1026 invocation of @kbd{M-j}.
1028 To turn existing lines into comment lines, use @kbd{M-;} with the
1029 region active, or use @kbd{M-x comment-region}
1031 (@pxref{Comment Commands}).
1034 as described in the preceding section.
1037 You can configure C Mode such that when you type a @samp{/} at the
1038 start of a line in a multi-line block comment, this closes the
1039 comment. Enable the @code{comment-close-slash} clean-up for this.
1040 @xref{Clean-ups,,, ccmode, The CC Mode Manual}.
1042 @node Options for Comments
1043 @subsection Options Controlling Comments
1045 @vindex comment-column
1047 @findex comment-set-column
1048 As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command
1049 adds a comment to a line, it tries to place the comment at the column
1050 specified by the buffer-local variable @code{comment-column}. You can
1051 set either the local value or the default value of this buffer-local
1052 variable in the usual way (@pxref{Locals}). Alternatively, you can
1053 type @kbd{C-x ;} (@code{comment-set-column}) to set the value of
1054 @code{comment-column} in the current buffer to the column where point
1055 is currently located. @kbd{C-u C-x ;} sets the comment column to
1056 match the last comment before point in the buffer, and then does a
1057 @kbd{M-;} to align the current line's comment under the previous one.
1059 @vindex comment-start-skip
1060 The comment commands recognize comments based on the regular
1061 expression that is the value of the variable @code{comment-start-skip}.
1062 Make sure this regexp does not match the null string. It may match more
1063 than the comment starting delimiter in the strictest sense of the word;
1064 for example, in C mode the value of the variable is
1065 @c This stops M-q from breaking the line inside that @code.
1066 @code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and
1067 spaces after the @samp{/*} itself, and accepts C++ style comments
1068 also. (Note that @samp{\\} is needed in Lisp syntax to include a
1069 @samp{\} in the string, which is needed to deny the first star its
1070 special meaning in regexp syntax. @xref{Regexp Backslash}.)
1072 @vindex comment-start
1074 When a comment command makes a new comment, it inserts the value of
1075 @code{comment-start} as an opening comment delimiter. It also inserts
1076 the value of @code{comment-end} after point, as a closing comment
1077 delimiter. For example, in Lisp mode, @code{comment-start} is
1078 @samp{";"} and @code{comment-end} is @code{""} (the empty string). In
1079 C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is
1082 @vindex comment-padding
1083 The variable @code{comment-padding} specifies a string that the
1084 commenting commands should insert between the comment delimiter(s) and
1085 the comment text. The default, @samp{" "}, specifies a single space.
1086 Alternatively, the value can be a number, which specifies that number
1087 of spaces, or @code{nil}, which means no spaces at all.
1089 The variable @code{comment-multi-line} controls how @kbd{M-j} and
1090 Auto Fill mode continue comments over multiple lines.
1091 @xref{Multi-Line Comments}.
1093 @vindex comment-indent-function
1094 The variable @code{comment-indent-function} should contain a function
1095 that will be called to compute the alignment for a newly inserted
1096 comment or for aligning an existing comment. It is set differently by
1097 various major modes. The function is called with no arguments, but with
1098 point at the beginning of the comment, or at the end of a line if a new
1099 comment is to be inserted. It should return the column in which the
1100 comment ought to start. For example, in Lisp mode, the indent hook
1101 function bases its decision on how many semicolons begin an existing
1102 comment, and on the code in the preceding lines.
1105 @section Documentation Lookup
1107 Emacs provides several features you can use to look up the
1108 documentation of functions, variables and commands that you plan to
1109 use in your program.
1112 * Info Lookup:: Looking up library functions and commands in Info files.
1113 * Man Page:: Looking up man pages of library functions and commands.
1114 * Lisp Doc:: Looking up Emacs Lisp functions, etc.
1118 @subsection Info Documentation Lookup
1120 @findex info-lookup-symbol
1121 @findex info-lookup-file
1123 For major modes that apply to languages which have documentation in
1124 Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the
1125 Info documentation for a symbol used in the program. You specify the
1126 symbol with the minibuffer; the default is the symbol appearing in the
1127 buffer at point. For example, in C mode this looks for the symbol in
1128 the C Library Manual. The command only works if the appropriate
1129 manual's Info files are installed.
1131 The major mode determines where to look for documentation for the
1132 symbol---which Info files to look in, and which indices to search.
1133 You can also use @kbd{M-x info-lookup-file} to look for documentation
1136 If you use @kbd{C-h S} in a major mode that does not support it,
1137 it asks you to specify the ``symbol help mode''. You should enter
1138 a command such as @code{c-mode} that would select a major
1139 mode which @kbd{C-h S} does support.
1142 @subsection Man Page Lookup
1145 On Unix, the main form of on-line documentation was the @dfn{manual
1146 page} or @dfn{man page}. In the GNU operating system, we aim to
1147 replace man pages with better-organized manuals that you can browse
1148 with Info (@pxref{Misc Help}). This process is not finished, so it is
1149 still useful to read manual pages.
1151 @findex manual-entry
1152 You can read the man page for an operating system command, library
1153 function, or system call, with the @kbd{M-x man} command. This
1154 prompts for a topic, with completion (@pxref{Completion}), and runs
1155 the @command{man} program to format the corresponding man page. If
1156 the system permits, it runs @command{man} asynchronously, so that you
1157 can keep on editing while the page is being formatted. The result
1158 goes in a buffer named @file{*Man @var{topic}*}. These buffers use a
1159 special major mode, Man mode, that facilitates scrolling and jumping
1160 to other manual pages. For details, type @kbd{C-h m} while in a Man
1163 @cindex sections of manual pages
1164 Each man page belongs to one of ten or more @dfn{sections}, each
1165 named by a digit or by a digit and a letter. Sometimes there are man
1166 pages with the same name in different sections. To read a man page
1167 from a specific section, type @samp{@var{topic}(@var{section})} or
1168 @samp{@var{section} @var{topic}} when @kbd{M-x manual-entry} prompts
1169 for the topic. For example, the man page for the C library function
1170 @code{chmod} is in section 2, but there is a shell command of the same
1171 name, whose man page is in section 1; to view the former, type
1172 @kbd{M-x manual-entry @key{RET} chmod(2) @key{RET}}.
1174 @vindex Man-switches
1175 @kindex M-n @r{(Man mode)}
1176 @kindex M-p @r{(Man mode)}
1177 If you do not specify a section, @kbd{M-x man} normally displays
1178 only the first man page found. On some systems, the @code{man}
1179 program accepts a @samp{-a} command-line option, which tells it to
1180 display all the man pages for the specified topic. To make use of
1181 this, change the value of the variable @code{Man-switches} to
1182 @samp{"-a"}. Then, in the Man mode buffer, you can type @kbd{M-n} and
1183 @kbd{M-p} to switch between man pages in different sections. The mode
1184 line shows how many manual pages are available.
1187 @cindex manual pages, on MS-DOS/MS-Windows
1188 An alternative way of reading manual pages is the @kbd{M-x woman}
1189 command. Unlike @kbd{M-x man}, it does not run any external programs
1190 to format and display the man pages; the formatting is done by Emacs,
1191 so it works on systems such as MS-Windows where the @command{man}
1192 program may be unavailable. It prompts for a man page, and displays
1193 it in a buffer named @file{*WoMan @var{section} @var{topic}}.
1195 @kbd{M-x woman} computes the completion list for manpages the first
1196 time you invoke the command. With a numeric argument, it recomputes
1197 this list; this is useful if you add or delete manual pages.
1199 If you type a name of a manual page and @kbd{M-x woman} finds that
1200 several manual pages by the same name exist in different sections, it
1201 pops up a window with possible candidates asking you to choose one of
1204 For more information about setting up and using @kbd{M-x woman}, see
1206 @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The
1210 the WoMan Info manual, which is distributed with Emacs.
1214 @subsection Emacs Lisp Documentation Lookup
1216 When editing Emacs Lisp code, you can use the commands @kbd{C-h f}
1217 (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable})
1218 to view the built-in documentation for the Lisp functions and
1219 variables that you want to use. @xref{Name Help}.
1223 Eldoc is a buffer-local minor mode that helps with looking up Lisp
1224 documentation. When it is enabled, the echo area displays some useful
1225 information whenever there is a Lisp function or variable at point;
1226 for a function, it shows the argument list, and for a variable it
1227 shows the first line of the variable's documentation string. To
1228 toggle Eldoc mode, type @kbd{M-x eldoc-mode}. Eldoc mode can be used
1229 with the Emacs Lisp and Lisp Interaction major modes.
1232 @section Hideshow minor mode
1233 @cindex Hideshow mode
1234 @cindex mode, Hideshow
1236 @findex hs-minor-mode
1237 Hideshow mode is a buffer-local minor mode that allows you to
1238 selectively display portions of a program, which are referred to as
1239 @dfn{blocks}. Type @kbd{M-x hs-minor-mode} to toggle this minor mode
1240 (@pxref{Minor Modes}).
1242 When you use Hideshow mode to hide a block, the block disappears
1243 from the screen, to be replaced by an ellipsis (three periods in a
1244 row). Just what constitutes a block depends on the major mode. In C
1245 mode and related modes, blocks are delimited by braces, while in Lisp
1246 mode they are delimited by parentheses. Multi-line comments also
1249 Hideshow mode provides the following commands:
1252 @findex hs-hide-block
1254 @findex hs-show-block
1255 @findex hs-show-region
1256 @findex hs-hide-level
1257 @findex hs-minor-mode
1260 @kindex C-c @@ C-M-h
1261 @kindex C-c @@ C-M-s
1267 Hide the current block (@code{hs-hide-block}).
1269 Show the current block (@code{hs-show-block}).
1271 Either hide or show the current block (@code{hs-toggle-hiding}).
1273 Toggle hiding for the block you click on (@code{hs-mouse-toggle-hiding}).
1275 Hide all top-level blocks (@code{hs-hide-all}).
1277 Show all blocks in the buffer (@code{hs-show-all}).
1279 Hide all blocks @var{n} levels below this block
1280 (@code{hs-hide-level}).
1283 @vindex hs-hide-comments-when-hiding-all
1284 @vindex hs-isearch-open
1285 @vindex hs-special-modes-alist
1286 These variables can be used to customize Hideshow mode:
1289 @item hs-hide-comments-when-hiding-all
1290 If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides
1293 @item hs-isearch-open
1294 This variable specifies the conditions under which incremental search
1295 should unhide a hidden block when matching text occurs within the
1296 block. Its value should be either @code{code} (unhide only code
1297 blocks), @code{comment} (unhide only comments), @code{t} (unhide both
1298 code blocks and comments), or @code{nil} (unhide neither code blocks
1299 nor comments). The default value is @code{code}.
1302 @node Symbol Completion
1303 @section Completion for Symbol Names
1304 @cindex completion (symbol names)
1306 Completion is normally done in the minibuffer (@pxref{Completion}),
1307 but you can also complete symbol names in ordinary Emacs buffers.
1311 In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}}
1312 to complete the partial symbol before point. On graphical displays,
1313 the @kbd{M-@key{TAB}} key is usually reserved by the window manager
1314 for switching graphical windows, so you should type @kbd{C-M-i} or
1315 @kbd{@key{ESC} @key{TAB}} instead.
1317 @cindex tags-based completion
1318 @findex completion-at-point
1319 @cindex Lisp symbol completion
1320 @cindex completion (Lisp symbols)
1321 In most programming language modes, @kbd{C-M-i} (or
1322 @kbd{M-@key{TAB}}) invokes the command @code{completion-at-point},
1323 which generates its completion list in a flexible way. If Semantic
1324 mode is enabled, it tries to use the Semantic parser data for
1325 completion (@pxref{Semantic}). If Semantic mode is not enabled or
1326 fails at performing completion, it tries to complete using the
1327 selected tags table (@pxref{Tags}). If in Emacs Lisp mode, it
1328 performs completion using the function, variable, or property names
1329 defined in the current Emacs session.
1331 In all other respects, in-buffer symbol completion behaves like
1332 minibuffer completion. For instance, if Emacs cannot complete to a
1333 unique symbol, it displays a list of completion alternatives in
1334 another window. @xref{Completion}.
1336 In Text mode and related modes, @kbd{M-@key{TAB}} completes words
1337 based on the spell-checker's dictionary. @xref{Spelling}.
1339 @node MixedCase Words
1340 @section MixedCase Words
1343 Some programming styles make use of mixed-case (or ``CamelCase'')
1344 symbols like @samp{unReadableSymbol}. (In the GNU project, we recommend
1345 using underscores to separate words within an identifier, rather than
1346 using case distinctions.) Emacs has various features to make it easier
1347 to deal with such symbols.
1349 @cindex Glasses mode
1350 @findex mode, Glasses
1351 Glasses mode is a buffer-local minor mode that makes it easier to read
1352 such symbols, by altering how they are displayed. By default, it
1353 displays extra underscores between each lower-case letter and the
1354 following capital letter. This does not alter the buffer text, only how
1357 To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor
1358 Modes}). When Glasses mode is enabled, the minor mode indicator
1359 @samp{o^o} appears in the mode line. For more information about
1360 Glasses mode, type @kbd{C-h P glasses @key{RET}}.
1362 @cindex Subword mode
1363 @findex subword-mode
1364 Subword mode is another buffer-local minor mode. In subword mode,
1365 Emacs's word commands recognize upper case letters in
1366 @samp{StudlyCapsIdentifiers} as word boundaries. When Subword mode is
1367 enabled, the minor mode indicator @samp{,} appears in the mode line.
1368 See also the similar @code{superword-mode} (@pxref{Misc for Programs}).
1372 @cindex Semantic package
1374 Semantic is a package that provides language-aware editing commands
1375 based on @code{source code parsers}. This section provides a brief
1376 description of Semantic; for full details,
1378 see @ref{Top, Semantic,, semantic, Semantic}.
1381 see the Semantic Info manual, which is distributed with Emacs.
1384 Most of the ``language aware'' features in Emacs, such as Font Lock
1385 mode (@pxref{Font Lock}), rely on ``rules of thumb''@footnote{Regular
1386 expressions and syntax tables.} that usually give good results but are
1387 never completely exact. In contrast, the parsers used by Semantic
1388 have an exact understanding of programming language syntax. This
1389 allows Semantic to provide search, navigation, and completion commands
1390 that are powerful and precise.
1392 @cindex Semantic mode
1393 @cindex mode, Semantic
1394 To begin using Semantic, type @kbd{M-x semantic-mode} or click on
1395 the menu item named @samp{Source Code Parsers (Semantic)} in the
1396 @samp{Tools} menu. This enables Semantic mode, a global minor mode.
1398 When Semantic mode is enabled, Emacs automatically attempts to
1399 parse each file you visit. Currently, Semantic understands C, C++,
1400 Scheme, Javascript, Java, HTML, and Make. Within each parsed buffer,
1401 the following commands are available:
1406 Prompt for the name of a function defined in the current file, and
1407 move point there (@code{semantic-complete-jump-local}).
1411 Prompt for the name of a function defined in any file Emacs has
1412 parsed, and move point there (@code{semantic-complete-jump}).
1414 @item C-c , @key{SPC}
1415 @kindex C-c , @key{SPC}
1416 Display a list of possible completions for the symbol at point
1417 (@code{semantic-complete-analyze-inline}). This also activates a set
1418 of special key bindings for choosing a completion: @key{RET} accepts
1419 the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible
1420 completions, @key{TAB} completes as far as possible and then cycles,
1421 and @kbd{C-g} or any other key aborts completion.
1425 Display a list of the possible completions of the symbol at point, in
1426 another window (@code{semantic-analyze-possible-completions}).
1430 In addition to the above commands, the Semantic package provides a
1431 variety of other ways to make use of parser information. For
1432 instance, you can use it to display a list of completions when Emacs
1435 @xref{Top, Semantic,, semantic, Semantic}, for details.
1438 @node Misc for Programs
1439 @section Other Features Useful for Editing Programs
1441 Some Emacs commands that aren't designed specifically for editing
1442 programs are useful for that nonetheless.
1444 The Emacs commands that operate on words, sentences and paragraphs
1445 are useful for editing code. Most symbols names contain words
1446 (@pxref{Words}), while sentences can be found in strings and comments
1447 (@pxref{Sentences}). As for paragraphs, they are defined in most
1448 programming language modes to begin and end at blank lines
1449 (@pxref{Paragraphs}). Therefore, judicious use of blank lines to make
1450 the program clearer will also provide useful chunks of text for the
1451 paragraph commands to work on. Auto Fill mode, if enabled in a
1452 programming language major mode, indents the new lines which it
1455 @findex superword-mode
1456 Superword mode is a buffer-local minor mode that causes editing and
1457 motion commands to treat symbols (e.g., @samp{this_is_a_symbol}) as words.
1458 When Subword mode is enabled, the minor mode indicator
1465 appears in the mode line. See also the similar @code{subword-mode}
1466 (@pxref{MixedCase Words}).
1468 @findex electric-layout-mode
1469 Electric Layout mode (@kbd{M-x electric-layout-mode}) is a global
1470 minor mode that automatically inserts newlines when you type certain
1471 characters; for example, @samp{@{}, @samp{@}} and @samp{;} in Javascript
1474 Apart from Hideshow mode (@pxref{Hideshow}), another way to
1475 selectively display parts of a program is to use the selective display
1476 feature (@pxref{Selective Display}). Programming modes often also
1477 support Outline minor mode (@pxref{Outline Mode}), which can be used
1478 with the Foldout package (@pxref{Foldout}).
1481 The ``automatic typing'' features may be useful for writing programs.
1482 @xref{Top,,Autotyping, autotype, Autotyping}.
1486 @section C and Related Modes
1491 @cindex CORBA IDL mode
1492 @cindex Objective C mode
1498 @cindex mode, Objective C
1499 @cindex mode, CORBA IDL
1503 This section gives a brief description of the special features
1504 available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
1505 (These are called ``C mode and related modes''.)
1507 @xref{Top,, CC Mode, ccmode, CC Mode}, for more details.
1510 For more details, see the CC mode Info manual, which is distributed
1515 * Motion in C:: Commands to move by C statements, etc.
1516 * Electric C:: Colon and other chars can automatically reindent.
1517 * Hungry Delete:: A more powerful DEL command.
1518 * Other C Commands:: Filling comments, viewing expansion of macros,
1519 and other neat features.
1523 @subsection C Mode Motion Commands
1525 This section describes commands for moving point, in C mode and
1531 @findex c-beginning-of-defun
1532 @findex c-end-of-defun
1533 Move point to the beginning or end of the current function or
1534 top-level definition. In languages with enclosing scopes (such as
1535 C++'s classes) the @dfn{current function} is the immediate one,
1536 possibly inside a scope. Otherwise it is the one defined by the least
1537 enclosing braces. (By contrast, @code{beginning-of-defun} and
1538 @code{end-of-defun} search for braces in column zero.) @xref{Moving
1542 @kindex C-c C-u @r{(C mode)}
1543 @findex c-up-conditional
1544 Move point back to the containing preprocessor conditional, leaving the
1545 mark behind. A prefix argument acts as a repeat count. With a negative
1546 argument, move point forward to the end of the containing
1547 preprocessor conditional.
1549 @samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so
1550 the function will stop at a @samp{#elif} when going backward, but not
1554 @kindex C-c C-p @r{(C mode)}
1555 @findex c-backward-conditional
1556 Move point back over a preprocessor conditional, leaving the mark
1557 behind. A prefix argument acts as a repeat count. With a negative
1558 argument, move forward.
1561 @kindex C-c C-n @r{(C mode)}
1562 @findex c-forward-conditional
1563 Move point forward across a preprocessor conditional, leaving the mark
1564 behind. A prefix argument acts as a repeat count. With a negative
1565 argument, move backward.
1568 @kindex M-a (C mode)
1569 @findex c-beginning-of-statement
1570 Move point to the beginning of the innermost C statement
1571 (@code{c-beginning-of-statement}). If point is already at the beginning
1572 of a statement, move to the beginning of the preceding statement. With
1573 prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
1575 In comments or in strings which span more than one line, this command
1576 moves by sentences instead of statements.
1579 @kindex M-e (C mode)
1580 @findex c-end-of-statement
1581 Move point to the end of the innermost C statement or sentence; like
1582 @kbd{M-a} except that it moves in the other direction
1583 (@code{c-end-of-statement}).
1587 @subsection Electric C Characters
1589 In C mode and related modes, certain printing characters are
1590 @dfn{electric}---in addition to inserting themselves, they also
1591 reindent the current line, and optionally also insert newlines. The
1592 ``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#},
1593 @kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and
1596 You might find electric indentation inconvenient if you are editing
1597 chaotically indented code. If you are new to CC Mode, you might find
1598 it disconcerting. You can toggle electric action with the command
1599 @kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line
1600 after the mode name:
1604 @kindex C-c C-l @r{(C mode)}
1605 @findex c-toggle-electric-state
1606 Toggle electric action (@code{c-toggle-electric-state}). With a
1607 positive prefix argument, this command enables electric action, with a
1608 negative one it disables it.
1611 Electric characters insert newlines only when, in addition to the
1612 electric state, the @dfn{auto-newline} feature is enabled (indicated
1613 by @samp{/la} in the mode line after the mode name). You can turn
1614 this feature on or off with the command @kbd{C-c C-a}:
1618 @kindex C-c C-a @r{(C mode)}
1619 @findex c-toggle-auto-newline
1620 Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a
1621 prefix argument, this command turns the auto-newline feature on if the
1622 argument is positive, and off if it is negative.
1625 Usually the CC Mode style configures the exact circumstances in
1626 which Emacs inserts auto-newlines. You can also configure this
1627 directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}.
1630 @subsection Hungry Delete Feature in C
1631 @cindex hungry deletion (C Mode)
1633 If you want to delete an entire block of whitespace at point, you
1634 can use @dfn{hungry deletion}. This deletes all the contiguous
1635 whitespace either before point or after point in a single operation.
1636 @dfn{Whitespace} here includes tabs and newlines, but not comments or
1637 preprocessor commands.
1640 @item C-c C-@key{DEL}
1641 @itemx C-c @key{DEL}
1642 @findex c-hungry-delete-backwards
1643 @kindex C-c C-@key{DEL} (C Mode)
1644 @kindex C-c @key{DEL} (C Mode)
1645 Delete the entire block of whitespace preceding point (@code{c-hungry-delete-backwards}).
1648 @itemx C-c C-@key{DELETE}
1649 @itemx C-c @key{DELETE}
1650 @findex c-hungry-delete-forward
1651 @kindex C-c C-d (C Mode)
1652 @kindex C-c C-@key{DELETE} (C Mode)
1653 @kindex C-c @key{DELETE} (C Mode)
1654 Delete the entire block of whitespace after point (@code{c-hungry-delete-forward}).
1657 As an alternative to the above commands, you can enable @dfn{hungry
1658 delete mode}. When this feature is enabled (indicated by @samp{/h} in
1659 the mode line after the mode name), a single @key{DEL} deletes all
1660 preceding whitespace, not just one space, and a single @kbd{C-c C-d}
1661 (but @emph{not} plain @key{DELETE}) deletes all following whitespace.
1664 @item M-x c-toggle-hungry-state
1665 @findex c-toggle-hungry-state
1666 Toggle the hungry-delete feature
1667 (@code{c-toggle-hungry-state}). With a prefix argument,
1668 this command turns the hungry-delete feature on if the argument is
1669 positive, and off if it is negative.
1672 @vindex c-hungry-delete-key
1673 The variable @code{c-hungry-delete-key} controls whether the
1674 hungry-delete feature is enabled.
1676 @node Other C Commands
1677 @subsection Other Commands for C Mode
1680 @item M-x c-context-line-break
1681 @findex c-context-line-break
1682 This command inserts a line break and indents the new line in a manner
1683 appropriate to the context. In normal code, it does the work of
1684 @kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it
1685 additionally inserts a @samp{\} at the line break, and within comments
1686 it's like @kbd{M-j} (@code{c-indent-new-comment-line}).
1688 @code{c-context-line-break} isn't bound to a key by default, but it
1689 needs a binding to be useful. The following code will bind it to
1690 @kbd{C-j}. We use @code{c-initialization-hook} here to make sure
1691 the keymap is loaded before we try to change it.
1694 (defun my-bind-clb ()
1695 (define-key c-mode-base-map "\C-j"
1696 'c-context-line-break))
1697 (add-hook 'c-initialization-hook 'my-bind-clb)
1701 Put mark at the end of a function definition, and put point at the
1702 beginning (@code{c-mark-function}).
1705 @kindex M-q @r{(C mode)}
1706 @findex c-fill-paragraph
1707 Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
1708 If any part of the current line is a comment or within a comment, this
1709 command fills the comment or the paragraph of it that point is in,
1710 preserving the comment indentation and comment delimiters.
1713 @cindex macro expansion in C
1714 @cindex expansion of C macros
1715 @findex c-macro-expand
1716 @kindex C-c C-e @r{(C mode)}
1717 Run the C preprocessor on the text in the region, and show the result,
1718 which includes the expansion of all the macro calls
1719 (@code{c-macro-expand}). The buffer text before the region is also
1720 included in preprocessing, for the sake of macros defined there, but the
1721 output from this part isn't shown.
1723 When you are debugging C code that uses macros, sometimes it is hard to
1724 figure out precisely how the macros expand. With this command, you
1725 don't have to figure it out; you can see the expansions.
1728 @findex c-backslash-region
1729 @kindex C-c C-\ @r{(C mode)}
1730 Insert or align @samp{\} characters at the ends of the lines of the
1731 region (@code{c-backslash-region}). This is useful after writing or
1732 editing a C macro definition.
1734 If a line already ends in @samp{\}, this command adjusts the amount of
1735 whitespace before it. Otherwise, it inserts a new @samp{\}. However,
1736 the last line in the region is treated specially; no @samp{\} is
1737 inserted on that line, and any @samp{\} there is deleted.
1739 @item M-x cpp-highlight-buffer
1740 @cindex preprocessor highlighting
1741 @findex cpp-highlight-buffer
1742 Highlight parts of the text according to its preprocessor conditionals.
1743 This command displays another buffer named @file{*CPP Edit*}, which
1744 serves as a graphic menu for selecting how to display particular kinds
1745 of conditionals and their contents. After changing various settings,
1746 click on @samp{[A]pply these settings} (or go to that buffer and type
1747 @kbd{a}) to rehighlight the C mode buffer accordingly.
1750 @findex c-show-syntactic-information
1751 @kindex C-c C-s @r{(C mode)}
1752 Display the syntactic information about the current source line
1753 (@code{c-show-syntactic-information}). This information directs how
1754 the line is indented.
1756 @item M-x cwarn-mode
1757 @itemx M-x global-cwarn-mode
1759 @findex global-cwarn-mode
1760 @vindex global-cwarn-mode
1762 @cindex suspicious constructions in C, C++
1763 CWarn minor mode highlights certain suspicious C and C++ constructions:
1767 Assignments inside expressions.
1769 Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
1770 (except after a @samp{do @dots{} while} statement);
1772 C++ functions with reference parameters.
1776 You can enable the mode for one buffer with the command @kbd{M-x
1777 cwarn-mode}, or for all suitable buffers with the command @kbd{M-x
1778 global-cwarn-mode} or by customizing the variable
1779 @code{global-cwarn-mode}. You must also enable Font Lock mode to make
1782 @item M-x hide-ifdef-mode
1783 @findex hide-ifdef-mode
1784 @cindex Hide-ifdef mode
1785 @vindex hide-ifdef-shadow
1786 Hide-ifdef minor mode hides selected code within @samp{#if} and
1787 @samp{#ifdef} preprocessor blocks. If you change the variable
1788 @code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode
1789 ``shadows'' preprocessor blocks by displaying them with a less
1790 prominent face, instead of hiding them entirely. See the
1791 documentation string of @code{hide-ifdef-mode} for more information.
1793 @item M-x ff-find-related-file
1794 @cindex related files
1795 @findex ff-find-related-file
1796 @vindex ff-related-file-alist
1797 Find a file ``related'' in a special way to the file visited by the
1798 current buffer. Typically this will be the header file corresponding
1799 to a C/C++ source file, or vice versa. The variable
1800 @code{ff-related-file-alist} specifies how to compute related file
1808 @cindex assembler mode
1809 Asm mode is a major mode for editing files of assembler code. It
1810 defines these commands:
1814 @code{tab-to-tab-stop}.
1816 Insert a newline and then indent using @code{tab-to-tab-stop}.
1818 Insert a colon and then remove the indentation from before the label
1819 preceding colon. Then do @code{tab-to-tab-stop}.
1821 Insert or align a comment.
1824 The variable @code{asm-comment-char} specifies which character
1825 starts comments in assembler syntax.
1828 @include fortran-xtra.texi