programs.texi 77.5 KB
Newer Older
1
@c -*- coding: utf-8 -*-
Dave Love's avatar
#  
Dave Love committed
2
@c This is part of the Emacs manual.
Paul Eggert's avatar
Paul Eggert committed
3
@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2019 Free Software
4
@c Foundation, Inc.
Dave Love's avatar
#  
Dave Love committed
5
@c See file emacs.texi for copying conditions.
6
@node Programs
Dave Love's avatar
#  
Dave Love committed
7 8 9 10 11
@chapter Editing Programs
@cindex Lisp editing
@cindex C editing
@cindex program editing

12
  This chapter describes Emacs features for facilitating editing
13
programs.  Some of the things these features can do are:
Dave Love's avatar
#  
Dave Love committed
14 15 16

@itemize @bullet
@item
17
Find or move over top-level definitions (@pxref{Defuns}).
Dave Love's avatar
#  
Dave Love committed
18
@item
19 20
Apply the usual indentation conventions of the language
(@pxref{Program Indent}).
Dave Love's avatar
#  
Dave Love committed
21
@item
22
Balance parentheses (@pxref{Parentheses}).
23
@item
24 25
Insert, kill or align comments (@pxref{Comments}).
@item
26
Highlight program syntax (@pxref{Font Lock}).
Dave Love's avatar
#  
Dave Love committed
27 28 29 30
@end itemize

@menu
* Program Modes::       Major modes for editing programs.
31 32
* Defuns::              Commands to operate on major top-level parts
                          of a program.
Dave Love's avatar
#  
Dave Love committed
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 43
* C Modes::             Special commands of C, C++, Objective-C, Java,
                          IDL, Pike and AWK modes.
44
* Asm Mode::            Asm mode and its special features.
45 46 47
@ifnottex
* Fortran::             Fortran mode and its special features.
@end ifnottex
Dave Love's avatar
#  
Dave Love committed
48 49 50 51 52
@end menu

@node Program Modes
@section Major Modes for Programming Languages
@cindex modes for programming languages
53

54 55
  Emacs has specialized major modes (@pxref{Major Modes}) for many
programming languages.  A programming language mode typically
56 57
specifies the syntax of expressions, the customary rules for
indentation, how to do syntax highlighting for the language, and how
58 59 60 61
to find the beginning or end of a function definition.  It often has
features for compiling and debugging programs as well.  The major mode
for each language is named after the language; for instance, the major
mode for the C programming language is @code{c-mode}.
62

Dave Love's avatar
#  
Dave Love committed
63 64 65 66 67
@cindex Perl mode
@cindex Icon mode
@cindex Makefile mode
@cindex Tcl mode
@cindex CPerl mode
Dave Love's avatar
Dave Love committed
68 69 70 71 72
@cindex DSSSL mode
@cindex Octave mode
@cindex Metafont mode
@cindex Modula2 mode
@cindex Prolog mode
73
@cindex Python mode
74
@cindex Ruby mode
Dave Love's avatar
Dave Love committed
75
@cindex Simula mode
76
@cindex Verilog mode
Dave Love's avatar
Dave Love committed
77 78 79
@cindex VHDL mode
@cindex M4 mode
@cindex Shell-script mode
Glenn Morris's avatar
Glenn Morris committed
80
@cindex OPascal mode
81
@cindex PostScript mode
82 83
@cindex Conf mode
@cindex DNS mode
84
@cindex Javascript mode
85
@cindex Awk mode
86
  Emacs has programming language modes for Lisp, Scheme, the
Glenn Morris's avatar
Glenn Morris committed
87
Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++,
88 89 90 91 92 93 94 95
Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, M4, Makefiles,
Metafont (@TeX{}'s companion for font creation), Modula2, Object
Pascal, Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog,
Python, Ruby, Simula, SQL, Tcl, Verilog, and VHDL@.  An alternative
mode for Perl is called CPerl mode.  Modes are also available for the
scripting languages of the common GNU and Unix shells, and
MS-DOS/MS-Windows @samp{BAT} files, and for makefiles, DNS master
files, and various sorts of configuration files.
96 97 98 99 100

  Ideally, Emacs should have a major mode for each programming
language that you might want to edit.  If it doesn't have a mode for
your favorite language, the mode might be implemented in a package not
distributed with Emacs (@pxref{Packages}); or you can contribute one.
Dave Love's avatar
#  
Dave Love committed
101

102
@kindex DEL @r{(programming modes)}
103
@findex backward-delete-char-untabify
104
  In most programming languages, indentation should vary from line to
105
line to illustrate the structure of the program.  Therefore, in most
106 107 108 109 110 111 112
programming language modes, typing @kbd{@key{TAB}} updates the
indentation of the current line (@pxref{Program Indent}).
Furthermore, @kbd{@key{DEL}} is usually bound to
@code{backward-delete-char-untabify}, which deletes backward treating
each tab as if it were the equivalent number of spaces, so that you
can delete one column of indentation without worrying whether the
whitespace consists of spaces or tabs.
113

114
@cindex mode hook, and major modes
Dave Love's avatar
#  
Dave Love committed
115 116 117 118 119
@vindex c-mode-hook
@vindex lisp-mode-hook
@vindex emacs-lisp-mode-hook
@vindex lisp-interaction-mode-hook
@vindex scheme-mode-hook
120 121 122 123 124 125
  Entering a programming language mode runs the custom Lisp functions
specified in the hook variable @code{prog-mode-hook}, followed by
those specified in the mode's own mode hook (@pxref{Major Modes}).
For instance, entering C mode runs the hooks @code{prog-mode-hook} and
@code{c-mode-hook}.  @xref{Hooks}, for information about hooks.

126
@ifnottex
127 128
  Separate manuals are available for the modes for Ada (@pxref{Top,,
Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba
129 130
IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), Octave, VHDL,
and IDLWAVE (@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}).
131 132
@end ifnottex
@iftex
133
  The Emacs distribution contains Info manuals for the major modes for
134 135 136
Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, Octave, VHDL, and
IDLWAVE@.  For Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized
Emacs Features}.
137
@end iftex
Dave Love's avatar
#  
Dave Love committed
138

139 140
@node Defuns
@section Top-Level Definitions, or Defuns
Dave Love's avatar
#  
Dave Love committed
141

142 143 144
  In Emacs, a major definition at the top level in the buffer, such as
a function, is called a @dfn{defun}.  The name comes from Lisp, but in
Emacs we use it for all languages.
Dave Love's avatar
#  
Dave Love committed
145

146 147 148 149 150 151 152
@menu
* Left Margin Paren::   An open-paren or similar opening delimiter
                          starts a defun if it is at the left margin.
* Moving by Defuns::    Commands to move over or mark a major definition.
* Imenu::               Making buffer indexes as menus.
* Which Function::      Which Function mode shows which function you are in.
@end menu
Dave Love's avatar
#  
Dave Love committed
153

154 155
@node Left Margin Paren
@subsection Left Margin Convention
Dave Love's avatar
#  
Dave Love committed
156

157 158
@cindex open-parenthesis in leftmost column
@cindex ( in leftmost column
159 160 161 162 163 164 165 166 167 168
  Many programming-language modes assume by default that any opening
delimiter found at the left margin is the start of a top-level
definition, or defun.  Therefore, @strong{don't put an opening
delimiter at the left margin unless it should have that significance}.
For instance, never put an open-parenthesis at the left margin in a
Lisp file unless it is the start of a top-level list.

  The convention speeds up many Emacs operations, which would
otherwise have to scan back to the beginning of the buffer to analyze
the syntax of the code.
169 170 171

  If you don't follow this convention, not only will you have trouble
when you explicitly use the commands for motion by defuns; other
172 173 174
features that use them will also give you trouble.  This includes the
indentation commands (@pxref{Program Indent}) and Font Lock mode
(@pxref{Font Lock}).
175 176 177

  The most likely problem case is when you want an opening delimiter
at the start of a line inside a string.  To avoid trouble, put an
178 179 180 181
escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some
other Lisp dialects) before the opening delimiter.  This will not
affect the contents of the string, but will prevent that opening
delimiter from starting a defun.  Here's an example:
Dave Love's avatar
#  
Dave Love committed
182

183 184 185 186 187
@example
  (insert "Foo:
\(bar)
")
@end example
Dave Love's avatar
#  
Dave Love committed
188

189 190 191 192
  To help you catch violations of this convention, Font Lock mode
highlights confusing opening delimiters (those that ought to be
quoted) in bold red.

193
@vindex open-paren-in-column-0-is-defun-start
194
  If you need to override this convention, you can do so by setting
195
the variable @code{open-paren-in-column-0-is-defun-start}.
196
If this user option is set to @code{t} (the default), opening
197
parentheses or braces at column zero always start defuns.  When it is
198 199 200
@code{nil}, defuns are found by searching for parens or braces at the
outermost level.

201 202 203 204 205 206 207 208
  Usually, you should leave this option at its default value of
@code{t}.  If your buffer contains parentheses or braces in column
zero which don't start defuns, and it is somehow impractical to remove
these parentheses or braces, it might be helpful to set the option to
@code{nil}.  Be aware that this might make scrolling and display in
large buffers quite sluggish.  Furthermore, the parentheses and braces
must be correctly matched throughout the buffer for it to work
properly.
209 210 211

@node Moving by Defuns
@subsection Moving by Defuns
Dave Love's avatar
#  
Dave Love committed
212 213
@cindex defuns

214 215
  These commands move point or set up the region based on top-level
major definitions, also called @dfn{defuns}.
216

Dave Love's avatar
#  
Dave Love committed
217 218 219 220 221 222 223 224 225 226
@table @kbd
@item C-M-a
Move to beginning of current or preceding defun
(@code{beginning-of-defun}).
@item C-M-e
Move to end of current or following defun (@code{end-of-defun}).
@item C-M-h
Put region around whole current or following defun (@code{mark-defun}).
@end table

227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244
@cindex move to beginning or end of function
@cindex function, move to beginning or end
@kindex C-M-a
@kindex C-M-e
@kindex C-M-h
@findex beginning-of-defun
@findex end-of-defun
@findex mark-defun
  The commands to move to the beginning and end of the current defun
are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e}
(@code{end-of-defun}).  If you repeat one of these commands, or use a
positive numeric argument, each repetition moves to the next defun in
the direction of motion.

  @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward
@var{n} times to the next beginning of a defun.  This is not exactly
the same place that @kbd{C-M-e} with argument @var{n} would move to;
the end of this defun is not usually exactly the same place as the
245 246 247 248
beginning of the following defun.  (Whitespace, comments, and perhaps
declarations can separate them.)  Likewise, @kbd{C-M-e} with a
negative argument moves back to an end of a defun, which is not quite
the same as @kbd{C-M-a} with a positive argument.
249

250
@kindex C-M-h @r{(C mode)}
Dave Love's avatar
#  
Dave Love committed
251
@findex c-mark-function
252 253 254 255
  To operate on the current defun, use @kbd{C-M-h}
(@code{mark-defun}), which sets the mark at the end of the current
defun and puts point at its beginning.  @xref{Marking Objects}.  This
is the easiest way to get ready to kill the defun in order to move it
256 257 258 259 260 261 262 263 264
to a different place in the file.  If the defun is directly preceded
by comments (with no intervening blank lines), they are marked, too.
If you use the command while point is between defuns, it uses the
following defun.  If you use the command while the mark is already
active, it extends the end of the region to include one more defun.
With a prefix argument, it marks that many defuns or extends the
region by the appropriate number of defuns.  With negative prefix
argument it marks defuns in the opposite direction and also changes
the direction of selecting for subsequent uses of @code{mark-defun}.
265 266 267 268

  In C mode, @kbd{C-M-h} runs the function @code{c-mark-function},
which is almost the same as @code{mark-defun}; the difference is that
it backs up over the argument declarations, function name and returned
Richard M. Stallman's avatar
Richard M. Stallman committed
269 270 271 272 273
data type so that the entire C function is inside the region.  This is
an example of how major modes adjust the standard key bindings so that
they do their standard jobs in a way better fitting a particular
language.  Other major modes may replace any or all of these key
bindings for that purpose.
Dave Love's avatar
#  
Dave Love committed
274

275 276
@node Imenu
@subsection Imenu
Richard M. Stallman's avatar
Richard M. Stallman committed
277 278
@cindex index of buffer definitions
@cindex buffer definitions index
279

Pavel Janík's avatar
Pavel Janík committed
280
  The Imenu facility offers a way to find the major definitions in
281 282
a file by name.  It is also useful in text formatter major modes,
where it treats each chapter, section, etc., as a definition.
283
(@xref{Xref}, for a more powerful feature that handles multiple files
284
together.)
285 286

@findex imenu
287
  If you type @kbd{M-x imenu}, it reads the name of a definition using
Richard M. Stallman's avatar
Richard M. Stallman committed
288 289 290
the minibuffer, then moves point to that definition.  You can use
completion to specify the name; the command always displays the whole
list of valid names.
291

292
@findex imenu-add-menubar-index
293
  Alternatively, you can bind the command @code{imenu} to a mouse
Richard M. Stallman's avatar
Richard M. Stallman committed
294 295 296 297 298
click.  Then it displays mouse menus for you to select a definition
name.  You can also add the buffer's index to the menu bar by calling
@code{imenu-add-menubar-index}.  If you want to have this menu bar
item available for all buffers in a certain major mode, you can do
this by adding @code{imenu-add-menubar-index} to its mode hook.  But
Richard M. Stallman's avatar
Richard M. Stallman committed
299 300 301
if you have done that, you will have to wait a little while each time
you visit a file in that mode, while Emacs finds all the definitions
in that buffer.
302 303 304

@vindex imenu-auto-rescan
  When you change the contents of a buffer, if you add or delete
Richard M. Stallman's avatar
Richard M. Stallman committed
305
definitions, you can update the buffer's index based on the
306
new contents by invoking the @samp{*Rescan*} item in the menu.
Eli Zaretskii's avatar
Eli Zaretskii committed
307 308
Rescanning happens automatically if you set @code{imenu-auto-rescan} to
a non-@code{nil} value.  There is no need to rescan because of small
Richard M. Stallman's avatar
Richard M. Stallman committed
309
changes in the text.
310

311 312 313 314
@vindex imenu-auto-rescan-maxout
  @code{imenu-auto-rescan} will be disabled in buffers that are larger
than @code{imenu-auto-rescan-maxout} in bytes.

315
@vindex imenu-sort-function
316
  You can customize the way the menus are sorted by setting the
Richard M. Stallman's avatar
Richard M. Stallman committed
317
variable @code{imenu-sort-function}.  By default, names are ordered as
318 319 320
they occur in the buffer; if you want alphabetic sorting, use the
symbol @code{imenu--sort-by-name} as the value.  You can also
define your own comparison function by writing Lisp code.
321 322 323 324 325 326 327 328 329 330 331 332

  Imenu provides the information to guide Which Function mode
@ifnottex
(@pxref{Which Function}).
@end ifnottex
@iftex
(see below).
@end iftex
The Speedbar can also use it (@pxref{Speedbar}).

@node Which Function
@subsection Which Function Mode
333
@cindex current function name in mode line
334

335 336 337
  Which Function mode is a global minor mode (@pxref{Minor Modes})
which displays the current function name in the mode line, updating it
as you move around in a buffer.
338 339 340

@findex which-function-mode
@vindex which-func-modes
Karl Berry's avatar
Karl Berry committed
341
  To either enable or disable Which Function mode, use the command
342
@kbd{M-x which-function-mode}.  Which Function mode is a global minor
343
mode.  By default, it takes effect in all major modes that
344
know how to support it (i.e., all the major modes that support
345 346 347 348
Imenu).  You can restrict it to a specific list of major modes by
changing the value of the variable @code{which-func-modes} from
@code{t} (which means to support all available major modes) to a list
of major mode names.
Dave Love's avatar
#  
Dave Love committed
349 350 351 352 353 354

@node Program Indent
@section Indentation for Programs
@cindex indentation for programs

  The best way to keep a program properly indented is to use Emacs to
355 356 357
reindent it as you change it.  Emacs has commands to indent either a
single line, a specified number of lines, or all of the lines inside a
single parenthetical grouping.
Dave Love's avatar
#  
Dave Love committed
358

359 360 361 362
  @xref{Indentation}, for general information about indentation.  This
section describes indentation features specific to programming
language modes.

Dave Love's avatar
#  
Dave Love committed
363
@menu
364
* Basic Indent::        Indenting a single line.
Dave Love's avatar
#  
Dave Love committed
365
* Multi-line Indent::   Commands to reindent many lines at once.
366 367 368
* Lisp Indent::         Specifying how each Lisp function should be indented.
* C Indent::            Extra features for indenting C and related modes.
* Custom C Indent::     Controlling indentation style for C and related modes.
Dave Love's avatar
#  
Dave Love committed
369 370
@end menu

371
@cindex pretty-printer
372 373
  Emacs also provides a Lisp pretty-printer in the @code{pp} package,
which reformats Lisp objects with nice-looking indentation.
374
@xref{Output Functions, pp,, elisp, The Emacs Lisp Reference Manual}.
Dave Love's avatar
#  
Dave Love committed
375 376 377 378 379 380

@node Basic Indent
@subsection Basic Program Indentation Commands

@table @kbd
@item @key{TAB}
381
Adjust indentation of current line (@code{indent-for-tab-command}).
382
@item @key{RET}
383
Insert a newline, then adjust indentation of following line
384
(@code{newline}).
Dave Love's avatar
#  
Dave Love committed
385 386
@end table

387
@kindex TAB @r{(programming modes)}
388
@findex indent-line-function
389
  The basic indentation command is @kbd{@key{TAB}}
390
(@code{indent-for-tab-command}), which was documented in
391 392 393 394 395
@ref{Indentation}.  In programming language modes, @kbd{@key{TAB}}
indents the current line, based on the indentation and syntactic
content of the preceding lines; if the region is active,
@kbd{@key{TAB}} indents each line within the region, not just the
current line.
Dave Love's avatar
#  
Dave Love committed
396

397 398 399 400
  The command @kbd{@key{RET}} (@code{newline}), which was documented
in @ref{Inserting Text}, does the same as @kbd{C-j} followed by
@kbd{@key{TAB}}: it inserts a new line, then adjusts the line's
indentation.
401 402 403 404

  When indenting a line that starts within a parenthetical grouping,
Emacs usually places the start of the line under the preceding line
within the group, or under the text after the parenthesis.  If you
405
manually give one of these lines a nonstandard indentation (e.g., for
406 407 408
aesthetic purposes), the lines below will follow it.

  The indentation commands for most programming language modes assume
409
that an open-parenthesis, open-brace or other opening delimiter at the
410 411 412 413
left margin is the start of a function.  If the code you are editing
violates this assumption---even if the delimiters occur in strings or
comments---you must set @code{open-paren-in-column-0-is-defun-start}
to @code{nil} for indentation to work properly.  @xref{Left Margin
414
Paren}.
Dave Love's avatar
#  
Dave Love committed
415 416 417 418

@node Multi-line Indent
@subsection Indenting Several Lines

419 420
  Sometimes, you may want to reindent several lines of code at a time.
One way to do this is to use the mark; when the mark is active and the
421
region is non-empty, @kbd{@key{TAB}} indents every line in the region.
422 423 424 425 426 427
Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents
every line in the region, whether or not the mark is active
(@pxref{Indentation Commands}).

  In addition, Emacs provides the following commands for indenting
large chunks of code:
Dave Love's avatar
#  
Dave Love committed
428 429 430

@table @kbd
@item C-M-q
431
Reindent all the lines within one parenthetical grouping.
Dave Love's avatar
#  
Dave Love committed
432
@item C-u @key{TAB}
433 434
Shift an entire parenthetical grouping rigidly sideways so that its
first line is properly indented.
435 436 437
@item M-x indent-code-rigidly
Shift all the lines in the region rigidly sideways, but do not alter
lines that start inside comments and strings.
Dave Love's avatar
#  
Dave Love committed
438 439 440
@end table

@kindex C-M-q
441
@findex indent-pp-sexp
442 443 444
  To reindent the contents of a single parenthetical grouping,
position point before the beginning of the grouping and type
@kbd{C-M-q}.  This changes the relative indentation within the
445
grouping, without affecting its overall indentation (i.e., the
446 447 448
indentation of the line where the grouping starts).  The function that
@kbd{C-M-q} runs depends on the major mode; it is
@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode,
449
etc.  To correct the overall indentation as well, type @kbd{@key{TAB}}
450 451
first.

452
@kindex C-u TAB
453 454 455
  If you like the relative indentation within a grouping but not the
indentation of its first line, move point to that first line and type
@kbd{C-u @key{TAB}}.  In Lisp, C, and some other major modes,
456 457 458 459 460 461
@kbd{@key{TAB}} with a numeric argument reindents the current line as
usual, then reindents by the same amount all the lines in the
parenthetical grouping starting on the current line.  It is clever,
though, and does not alter lines that start inside strings.  Neither
does it alter C preprocessor lines when in C mode, but it does
reindent any continuation lines that may be attached to them.
Dave Love's avatar
#  
Dave Love committed
462

463
@findex indent-code-rigidly
464 465 466 467 468 469
  The command @kbd{M-x indent-code-rigidly} rigidly shifts all the
lines in the region sideways, like @code{indent-rigidly} does
(@pxref{Indentation Commands}).  It doesn't alter the indentation of
lines that start inside a string, unless the region also starts inside
that string.  The prefix arg specifies the number of columns to
indent.
Dave Love's avatar
#  
Dave Love committed
470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492

@node Lisp Indent
@subsection Customizing Lisp Indentation
@cindex customizing Lisp indentation

  The indentation pattern for a Lisp expression can depend on the function
called by the expression.  For each Lisp function, you can choose among
several predefined patterns of indentation, or define an arbitrary one with
a Lisp program.

  The standard pattern of indentation is as follows: the second line of the
expression is indented under the first argument, if that is on the same
line as the beginning of the expression; otherwise, the second line is
indented underneath the function name.  Each following line is indented
under the previous line whose nesting depth is the same.

@vindex lisp-indent-offset
  If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
the usual indentation pattern for the second line of an expression, so that
such lines are always indented @code{lisp-indent-offset} more columns than
the containing list.

@vindex lisp-body-indent
493
  Certain functions override the standard pattern.  Functions whose
Pavel Janík's avatar
Pavel Janík committed
494
names start with @code{def} treat the second lines as the start of
495 496 497
a @dfn{body}, by indenting the second line @code{lisp-body-indent}
additional columns beyond the open-parenthesis that starts the
expression.
Dave Love's avatar
#  
Dave Love committed
498

499
@cindex @code{lisp-indent-function} property
500
  You can override the standard pattern in various ways for individual
501
functions, according to the @code{lisp-indent-function} property of
502
the function name.  This is normally done for macro definitions, using
503
the @code{declare} construct.  @xref{Defining Macros,,, elisp, The
504
Emacs Lisp Reference Manual}.
Dave Love's avatar
#  
Dave Love committed
505 506 507 508

@node C Indent
@subsection Commands for C Indentation

509
  Here are special features for indentation in C mode and related modes:
Dave Love's avatar
#  
Dave Love committed
510

511
@table @kbd
Dave Love's avatar
#  
Dave Love committed
512 513 514 515 516 517 518 519 520 521
@item C-c C-q
@kindex C-c C-q @r{(C mode)}
@findex c-indent-defun
Reindent the current top-level function definition or aggregate type
declaration (@code{c-indent-defun}).

@item C-M-q
@kindex C-M-q @r{(C mode)}
@findex c-indent-exp
Reindent each line in the balanced expression that follows point
522 523
(@code{c-indent-exp}).  A prefix argument inhibits warning messages
about invalid syntax.
Dave Love's avatar
#  
Dave Love committed
524 525 526 527 528 529

@item @key{TAB}
@findex c-indent-command
Reindent the current line, and/or in some cases insert a tab character
(@code{c-indent-command}).

530
@vindex c-tab-always-indent
Dave Love's avatar
#  
Dave Love committed
531 532 533 534 535 536 537 538 539
If @code{c-tab-always-indent} is @code{t}, this command always reindents
the current line and does nothing else.  This is the default.

If that variable is @code{nil}, this command reindents the current line
only if point is at the left margin or in the line's indentation;
otherwise, it inserts a tab (or the equivalent number of spaces,
if @code{indent-tabs-mode} is @code{nil}).

Any other value (not @code{nil} or @code{t}) means always reindent the
540
line, and also insert a tab if within a comment or a string.
Dave Love's avatar
#  
Dave Love committed
541 542 543 544 545 546 547 548 549 550 551
@end table

  To reindent the whole current buffer, type @kbd{C-x h C-M-\}.  This
first selects the whole buffer as the region, then reindents that
region.

  To reindent the current block, use @kbd{C-M-u C-M-q}.  This moves
to the front of the block and then reindents it all.

@node Custom C Indent
@subsection Customizing C Indentation
552
@cindex style (for indentation)
Dave Love's avatar
#  
Dave Love committed
553

554 555 556 557 558 559
  C mode and related modes use a flexible mechanism for customizing
indentation.  C mode indents a source line in two steps: first it
classifies the line syntactically according to its contents and
context; second, it determines the indentation offset associated by
your selected @dfn{style} with the syntactic construct and adds this
onto the indentation of the @dfn{anchor statement}.
Dave Love's avatar
#  
Dave Love committed
560

561
@table @kbd
562
@item C-c . @var{style} @key{RET}
563
Select a predefined style @var{style} (@code{c-set-style}).
564
@end table
Dave Love's avatar
#  
Dave Love committed
565

566 567 568
  A @dfn{style} is a named collection of customizations that can be
used in C mode and the related modes.  @ref{Styles,,, ccmode, The CC
Mode Manual}, for a complete description.  Emacs comes with several
569 570
predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
@code{stroustrup}, @code{linux}, @code{python}, @code{java},
571 572 573 574
@code{whitesmith}, @code{ellemtel}, and @code{awk}.  Some of these
styles are primarily intended for one language, but any of them can be
used with any of the languages supported by these modes.  To find out
what a style looks like, select it and reindent some code, e.g., by
575
typing @kbd{C-M-q} at the start of a function definition.
Dave Love's avatar
#  
Dave Love committed
576

577
@kindex C-c . @r{(C mode)}
578
@findex c-set-style
Richard M. Stallman's avatar
Richard M. Stallman committed
579 580
  To choose a style for the current buffer, use the command @w{@kbd{C-c
.}}.  Specify a style name as an argument (case is not significant).
581 582
This command affects the current buffer only, and it affects only
future invocations of the indentation commands; it does not reindent
583 584
the code already in the buffer.  To reindent the whole buffer in the
new style, you can type @kbd{C-x h C-M-\}.
Dave Love's avatar
#  
Dave Love committed
585

586 587
@vindex c-default-style
  You can also set the variable @code{c-default-style} to specify the
588 589 590 591
default style for various major modes.  Its value should be either the
style's name (a string) or an alist, in which each element specifies
one major mode and which indentation style to use for it.  For
example,
Dave Love's avatar
#  
Dave Love committed
592 593

@example
594
(setq c-default-style
595 596 597
      '((java-mode . "java")
        (awk-mode . "awk")
        (other . "gnu")))
Dave Love's avatar
#  
Dave Love committed
598 599
@end example

600
@noindent
601 602 603 604 605 606
specifies explicit choices for Java and AWK modes, and the default
@samp{gnu} style for the other C-like modes.  (These settings are
actually the defaults.)  This variable takes effect when you select
one of the C-like major modes; thus, if you specify a new default
style for Java mode, you can make it take effect in an existing Java
mode buffer by typing @kbd{M-x java-mode} there.
Dave Love's avatar
#  
Dave Love committed
607

608 609 610
  The @code{gnu} style specifies the formatting recommended by the GNU
Project for C; it is the default, so as to encourage use of our
recommended style.
Dave Love's avatar
#  
Dave Love committed
611

612 613 614
  @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and
@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more
information on customizing indentation for C and related modes,
615 616
including how to override parts of an existing style and how to define
your own styles.
Dave Love's avatar
#  
Dave Love committed
617

618 619 620 621 622
@findex c-guess
@findex c-guess-install
  As an alternative to specifying a style, you can tell Emacs to guess
a style by typing @kbd{M-x c-guess} in a sample code buffer.  You can
then apply the guessed style to other buffers with @kbd{M-x
623
c-guess-install}.  @xref{Guessing the Style,,, ccmode, the CC Mode
624
Manual}, for details.
625

626 627
@node Parentheses
@section Commands for Editing with Parentheses
Dave Love's avatar
#  
Dave Love committed
628

629 630 631 632 633
@findex check-parens
@cindex unbalanced parentheses and quotes
  This section describes the commands and features that take advantage
of the parenthesis structure in a program, or help you keep it
balanced.
Dave Love's avatar
#  
Dave Love committed
634

635 636
  When talking about these facilities, the term ``parenthesis'' also
includes braces, brackets, or whatever delimiters are defined to match
Richard M. Stallman's avatar
Richard M. Stallman committed
637
in pairs.  The major mode controls which delimiters are significant,
638 639 640
through the syntax table (@pxref{Syntax Tables,, Syntax Tables, elisp,
The Emacs Lisp Reference Manual}).  In Lisp, only parentheses count;
in C, these commands apply to braces and brackets too.
Dave Love's avatar
#  
Dave Love committed
641

642 643
  You can use @kbd{M-x check-parens} to find any unbalanced
parentheses and unbalanced string quotes in the buffer.
Dave Love's avatar
#  
Dave Love committed
644

645 646 647 648
@menu
* Expressions::         Expressions with balanced parentheses.
* Moving by Parens::    Commands for moving up, down and across
                          in the structure of parentheses.
649
* Matching::            Insertion of a close-delimiter flashes matching open.
650
@end menu
Dave Love's avatar
#  
Dave Love committed
651

652 653
@node Expressions
@subsection Expressions with Balanced Parentheses
Dave Love's avatar
#  
Dave Love committed
654

655 656 657
@cindex sexp
@cindex expression
@cindex balanced expression
658 659 660 661 662 663 664
  Each programming language mode has its own definition of a
@dfn{balanced expression}.  Balanced expressions typically include
individual symbols, numbers, and string constants, as well as pieces
of code enclosed in a matching pair of delimiters.  The following
commands deal with balanced expressions (in Emacs, such expressions
are referred to internally as @dfn{sexps}@footnote{The word ``sexp''
is used to refer to an expression in Lisp.}).
Dave Love's avatar
#  
Dave Love committed
665

666 667 668 669
@table @kbd
@item C-M-f
Move forward over a balanced expression (@code{forward-sexp}).
@item C-M-b
670
Move backward over a balanced expression (@code{backward-sexp}).
671 672 673 674 675
@item C-M-k
Kill balanced expression forward (@code{kill-sexp}).
@item C-M-t
Transpose expressions (@code{transpose-sexps}).
@item C-M-@@
676
@itemx C-M-@key{SPC}
677 678
Put mark after following expression (@code{mark-sexp}).
@end table
Dave Love's avatar
#  
Dave Love committed
679

680 681 682 683 684 685
@kindex C-M-f
@kindex C-M-b
@findex forward-sexp
@findex backward-sexp
  To move forward over a balanced expression, use @kbd{C-M-f}
(@code{forward-sexp}).  If the first significant character after point
686
is an opening delimiter (e.g., @samp{(}, @samp{[} or @samp{@{} in C),
687 688 689
this command moves past the matching closing delimiter.  If the
character begins a symbol, string, or number, the command moves over
that.
Dave Love's avatar
#  
Dave Love committed
690

691
  The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
692 693 694 695 696 697 698 699 700 701 702 703
balanced expression---like @kbd{C-M-f}, but in the reverse direction.
If the expression is preceded by any prefix characters (single-quote,
backquote and comma, in Lisp), the command moves back over them as
well.

  @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation
the specified number of times; with a negative argument means to move
in the opposite direction.  In most modes, these two commands move
across comments as if they were whitespace.  Note that their keys,
@kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b},
which move by characters (@pxref{Moving Point}), and @kbd{M-f} and
@kbd{M-b}, which move by words (@pxref{Words}).
Dave Love's avatar
#  
Dave Love committed
704

705 706 707
@cindex killing expressions
@kindex C-M-k
@findex kill-sexp
708 709 710
  To kill a whole balanced expression, type @kbd{C-M-k}
(@code{kill-sexp}).  This kills the text that @kbd{C-M-f} would move
over.
Dave Love's avatar
#  
Dave Love committed
711

712 713 714
@cindex transposition of expressions
@kindex C-M-t
@findex transpose-sexps
715 716 717 718 719 720 721 722
  @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the
previous balanced expression and the next one.  It is analogous to the
@kbd{C-t} command, which transposes characters (@pxref{Transpose}).
An argument to @kbd{C-M-t} serves as a repeat count, moving the
previous expression over that many following ones.  A negative
argument moves the previous balanced expression backwards across those
before it.  An argument of zero, rather than doing nothing, transposes
the balanced expressions ending at or after point and the mark.
Dave Love's avatar
#  
Dave Love committed
723

724
@kindex C-M-SPC
725 726 727 728 729 730 731 732 733
  To operate on balanced expressions with a command which acts on the
region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}).  This sets the
mark where @kbd{C-M-f} would move to.  While the mark is active, each
successive call to this command extends the region by shifting the
mark by one expression.  Positive or negative numeric arguments move
the mark forward or backward by the specified number of expressions.
The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}.
@xref{Marking Objects}, for more information about this and related
commands.
734 735

  In languages that use infix operators, such as C, it is not possible
736 737 738 739 740 741 742
to recognize all balanced expressions because there can be multiple
possibilities at a given position.  For example, C mode does not treat
@samp{foo + bar} as a single expression, even though it @emph{is} one
C expression; instead, it recognizes @samp{foo} as one expression and
@samp{bar} as another, with the @samp{+} as punctuation between them.
However, C mode recognizes @samp{(foo + bar)} as a single expression,
because of the parentheses.
743 744 745 746 747 748 749 750 751

@node Moving by Parens
@subsection Moving in the Parenthesis Structure

@cindex parenthetical groupings
@cindex parentheses, moving across
@cindex matching parenthesis and braces, moving to
@cindex braces, moving across
@cindex list commands
752

753 754 755
  The following commands move over groupings delimited by parentheses
(or whatever else serves as delimiters in the language you are working
with).  They ignore strings and comments, including any parentheses
Paul Eggert's avatar
Paul Eggert committed
756
within them, and also ignore parentheses that are quoted with an
757 758
escape character.  These commands are mainly intended for editing
programs, but can be useful for editing any text containing
Paul Eggert's avatar
Paul Eggert committed
759
parentheses.  They are referred to internally as ``list commands''
760
because in Lisp these groupings are lists.
Dave Love's avatar
#  
Dave Love committed
761

762 763 764
  These commands assume that the starting point is not inside a string
or a comment.  If you invoke them from inside a string or comment, the
results are unreliable.
765

Dave Love's avatar
#  
Dave Love committed
766
@table @kbd
767 768 769
@item C-M-n
Move forward over a parenthetical group (@code{forward-list}).
@item C-M-p
770
Move backward over a parenthetical group (@code{backward-list}).
771 772 773 774
@item C-M-u
Move up in parenthesis structure (@code{backward-up-list}).
@item C-M-d
Move down in parenthesis structure (@code{down-list}).
Dave Love's avatar
#  
Dave Love committed
775 776
@end table

777 778 779 780
@kindex C-M-n
@kindex C-M-p
@findex forward-list
@findex backward-list
Paul Eggert's avatar
Paul Eggert committed
781
  The list commands @kbd{C-M-n} (@code{forward-list}) and
782 783
@kbd{C-M-p} (@code{backward-list}) move forward or backward over one
(or @var{n}) parenthetical groupings.
Dave Love's avatar
#  
Dave Love committed
784

785 786 787 788 789 790 791
@kindex C-M-u
@findex backward-up-list
  @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
parenthesis structure.  To move @emph{up} one (or @var{n}) levels, use
@kbd{C-M-u} (@code{backward-up-list}).  @kbd{C-M-u} moves backward up
past one unmatched opening delimiter.  A positive argument serves as a
repeat count; a negative argument reverses the direction of motion, so
792
that the command moves forward and up one or more levels.
793

Richard M. Stallman's avatar
Richard M. Stallman committed
794 795
@kindex C-M-d
@findex down-list
796 797 798 799
  To move @emph{down} in the parenthesis structure, use @kbd{C-M-d}
(@code{down-list}).  In Lisp mode, where @samp{(} is the only opening
delimiter, this is nearly the same as searching for a @samp{(}.  An
argument specifies the number of levels to go down.
Dave Love's avatar
#  
Dave Love committed
800 801

@node Matching
802
@subsection Matching Parentheses
Dave Love's avatar
#  
Dave Love committed
803 804 805
@cindex matching parentheses
@cindex parentheses, displaying matches

806 807 808 809 810
  Emacs has a number of @dfn{parenthesis matching} features, which
make it easy to see how and whether parentheses (or other delimiters)
match up.

  Whenever you type a self-inserting character that is a closing
Dmitry Gutov's avatar
Dmitry Gutov committed
811 812 813 814 815 816
delimiter, Emacs briefly indicates the location of the matching
opening delimiter, provided that is on the screen.  If it is not on
the screen, Emacs displays some of the text near it in the echo area.
Either way, you can tell which grouping you are closing off.  If the
opening delimiter and closing delimiter are mismatched---such as in
@samp{[x)}---a warning message is displayed in the echo area.
Dave Love's avatar
#  
Dave Love committed
817 818 819 820

@vindex blink-matching-paren
@vindex blink-matching-paren-distance
@vindex blink-matching-delay
821
  Three variables control the display of matching parentheses:
822

823 824 825
@itemize @bullet
@item
@code{blink-matching-paren} turns the feature on or off: @code{nil}
826
disables it, but the default is @code{t} to enable it.  Set it to
827
@code{jump} to make indication work by momentarily moving the cursor
828 829
to the matching opening delimiter.  Set it to @code{jump-offscreen} to
make the cursor jump, even if the opening delimiter is off screen.
830

831
@item
832 833 834
@code{blink-matching-delay} says how many seconds to keep indicating
the matching opening delimiter.  This may be an integer or
floating-point number; the default is 1.
835

836 837
@item
@code{blink-matching-paren-distance} specifies how many characters
838
back to search to find the matching opening delimiter.  If the match
839 840 841
is not found in that distance, Emacs stops scanning and nothing is
displayed.  The default is 102400.
@end itemize
Dave Love's avatar
#  
Dave Love committed
842 843

@cindex Show Paren mode
844
@cindex highlighting matching parentheses
Dave Love's avatar
#  
Dave Love committed
845
@findex show-paren-mode
846 847
  Show Paren mode, a global minor mode, provides a more powerful kind
of automatic matching.  Whenever point is before an opening delimiter
848 849 850 851 852 853 854 855
or after a closing delimiter, the delimiter, its matching delimiter,
and optionally the text between them are highlighted.  To toggle Show
Paren mode, type @kbd{M-x show-paren-mode}.  To customize it, type
@kbd{M-x customize-group @key{RET} paren-showing}.  The customizable
options which control the operation of this mode include:

@itemize @bullet
@item
Eli Zaretskii's avatar
Eli Zaretskii committed
856 857
@vindex show-paren-highlight-openparen
@code{show-paren-highlight-openparen} controls whether to highlight
858 859 860 861
an open paren when point stands just before it, and hence its position
is marked by the cursor anyway.  The default is non-@code{nil} (yes).

@item
Eli Zaretskii's avatar
Eli Zaretskii committed
862
@vindex show-paren-style
863 864 865 866 867 868 869 870
@code{show-paren-style} controls whether just the two parens, or also
the space between them get highlighted.  The valid options here are
@code{parenthesis} (show the matching paren), @code{expression}
(highlight the entire expression enclosed by the parens), and
@code{mixed} (highlight the matching paren if it is visible, the
expression otherwise).

@item
Eli Zaretskii's avatar
Eli Zaretskii committed
871
@vindex show-paren-when-point-inside-paren
872 873 874 875
@code{show-paren-when-point-inside-paren}, when non-@code{nil}, causes
highlighting also when point is on the inside of a parenthesis.

@item
Eli Zaretskii's avatar
Eli Zaretskii committed
876
@vindex show-paren-when-point-in-periphery
877 878 879 880 881
@code{show-paren-when-point-in-periphery}, when non-@code{nil}, causes
highlighting also when point is in whitespace at the beginning or end
of a line, and there is a paren at, respectively, the first or last,
or the last, non-whitespace position on the line.
@end itemize
882 883 884 885 886

@cindex Electric Pair mode
@cindex inserting matching parentheses
@findex electric-pair-mode
  Electric Pair mode, a global minor mode, provides a way to easily
887 888 889 890 891 892 893 894 895 896 897
insert matching delimiters: parentheses, braces, brackets, etc.
Whenever you insert an opening delimiter, the matching closing
delimiter is automatically inserted as well, leaving point between the
two.  Conversely, when you insert a closing delimiter over an existing
one, no insertion takes places, and that position is simply skipped
over.  If the region is active (@pxref{Mark}), insertion of a
delimiter operates on the region: the characters in the region are
enclosed in a pair of matching delimiters, leaving point after the
delimiter you typed.

These variables control additional features of Electric Pair mode:
898 899 900

@itemize @bullet
@item
901
@vindex electric-pair-preserve-balance
902 903 904 905 906
@code{electric-pair-preserve-balance}, when non-@code{nil}, makes the
default pairing logic balance out the number of opening and closing
delimiters.

@item
907
@vindex electric-pair-delete-adjacent-pairs
908 909 910 911 912
@code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes
backspacing between two adjacent delimiters also automatically delete
the closing delimiter.

@item
913
@vindex electric-pair-open-newline-between-pairs
914
@code{electric-pair-open-newline-between-pairs}, when non-@code{nil},
915 916
makes inserting a newline between two adjacent pairs also
automatically open an extra newline after point.
917 918

@item
919
@vindex electric-pair-skip-whitespace
920
@code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor
921 922 923 924
mode to skip whitespace forward before deciding whether to skip over
the closing delimiter.
@end itemize

Tom Willemse's avatar
Tom Willemse committed
925 926 927
To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}.  To
toggle the mode in a single buffer, use @kbd{M-x
electric-pair-local-mode}.
Dave Love's avatar
#  
Dave Love committed
928 929 930 931 932 933

@node Comments
@section Manipulating Comments
@cindex comments

  Because comments are such an important part of programming, Emacs
934 935 936
provides special commands for editing and inserting comments.  It can
also do spell checking on comments with Flyspell Prog mode
(@pxref{Spelling}).
Dave Love's avatar
#  
Dave Love committed
937

938 939 940 941
  Some major modes have special rules for indenting different kinds of
comments.  For example, in Lisp code, comments starting with two
semicolons are indented as if they were lines of code, while those
starting with three semicolons are supposed to be aligned to the left
942
margin and are often used for sectioning purposes.  Emacs understands
943 944
these conventions; for instance, typing @kbd{@key{TAB}} on a comment
line will indent the comment to the appropriate position.
945 946 947 948 949 950 951 952 953 954

@example
;; This function is just an example.
;;; Here either two or three semicolons are appropriate.
(defun foo (x)
;;;  And now, the first part of the function:
  ;; The following line adds one.
  (1+ x))           ; This line adds one.
@end example

Dave Love's avatar
#  
Dave Love committed
955
@menu
956
* Comment Commands::    Inserting, killing, and aligning comments.
957 958
* Multi-Line Comments:: Commands for adding and editing multi-line comments.
* Options for Comments::Customizing the comment features.
Dave Love's avatar
#  
Dave Love committed
959 960 961 962 963
@end menu

@node Comment Commands
@subsection Comment Commands
@cindex indentation for comments
964
@cindex alignment for comments
Dave Love's avatar
#  
Dave Love committed
965

966
  The following commands operate on comments:
Dave Love's avatar
#  
Dave Love committed
967

968 969
@table @asis
@item @kbd{M-;}
970 971
Insert or realign comment on current line; if the region is active,
comment or uncomment the region instead (@code{comment-dwim}).
Eli Zaretskii's avatar
Eli Zaretskii committed
972
@item @kbd{C-x C-;}
973 974 975
Comment or uncomment the current line (@code{comment-line}).  If the
region is active, comment or uncomment the lines in the region
instead.
976
@item @kbd{C-u M-;}
977
Kill comment on current line (@code{comment-kill}).
978
@item @kbd{C-x ;}
979
Set comment column (@code{comment-set-column}).
980 981
@item @kbd{C-M-j}
@itemx @kbd{M-j}
982
Like @kbd{@key{RET}} followed by inserting and aligning a comment
983
(@code{comment-indent-new-line}).  @xref{Multi-Line Comments}.
984 985
@item @kbd{M-x comment-region}
@itemx @kbd{C-c C-c} (in C-like modes)
986
Add comment delimiters to all the lines in the region.
Dave Love's avatar
#  
Dave Love committed
987 988
@end table

989 990 991 992 993 994 995 996
@kindex M-;
@findex comment-dwim
  The command to create or align a comment is @kbd{M-;}
(@code{comment-dwim}).  The word ``dwim'' is an acronym for ``Do What
I Mean''; it indicates that this command can be used for many
different jobs relating to comments, depending on the situation where
you use it.

997 998
  When a region is active (@pxref{Mark}), @kbd{M-;} either adds
comment delimiters to the region, or removes them.  If every line in
Paul Eggert's avatar
Paul Eggert committed
999
the region is already a comment, it uncomments each of those lines
1000 1001 1002 1003 1004 1005 1006 1007 1008 1009
by removing their comment delimiters.  Otherwise, it adds comment
delimiters to enclose the text in the region.

  If you supply a prefix argument to @kbd{M-;} when a region is
active, that specifies the number of comment delimiters to add or
delete.  A positive argument @var{n} adds @var{n} delimiters, while a
negative argument @var{-n} removes @var{n} delimiters.

  If the region is not active, and there is no existing comment on the
current line, @kbd{M-;} adds a new comment to the current line.  If
1010
the line is blank (i.e., empty or containing only whitespace
1011
characters), the comment is indented to the same position where
1012 1013
@kbd{@key{TAB}} would indent to (@pxref{Basic Indent}).  If the line
is non-blank, the comment is placed after the last non-whitespace
1014 1015 1016 1017 1018 1019 1020
character on the line.  Emacs tries to fit the comment between the
columns specified by the variables @code{comment-column} and
@code{comment-fill-column} (@pxref{Options for Comments}), if
possible.  Otherwise, it will choose some other suitable position,
usually separated from the non-comment text by at least one space.  In
each case, Emacs places point after the comment's starting delimiter,
so that you can start typing the comment text right away.
1021 1022

  You can also use @kbd{M-;} to align an existing comment.  If a line
1023
already contains the comment-start string, @kbd{M-;} realigns it to
1024 1025 1026 1027 1028
the conventional alignment and moves point after the comment's
starting delimiter.  As an exception, comments starting in column 0
are not moved.  Even when an existing comment is properly aligned,
@kbd{M-;} is still useful for moving directly to the start of the
comment text.
1029

Eli Zaretskii's avatar
Eli Zaretskii committed
1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041
@findex comment-line
@kindex C-x C-;
  @kbd{C-x C-;} (@code{comment-line}) comments or uncomments complete
lines.  When a region is active (@pxref{Mark}), @kbd{C-x C-;} either
comments or uncomments the lines in the region.  If the region is not
active, this command comments or uncomments the line point is on.
With a positive prefix argument @var{n}, it operates on @var{n} lines
starting with the current one; with a negative @var{n}, it affects
@var{n} preceding lines.  After invoking this command with a negative
argument, successive invocations with a positive argument will operate
on preceding lines as if the argument were negated.

1042 1043
@findex comment-kill
@kindex C-u M-;
1044 1045 1046 1047
  @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any
comment on the current line, along with the whitespace before it.
Since the comment is saved to the kill ring, you can reinsert it on
another line by moving to the end of that line, doing @kbd{C-y}, and
1048
then @kbd{M-;} to realign the comment.  You can achieve the same
1049 1050 1051
effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill}
(@code{comment-dwim} actually calls @code{comment-kill} as a
subroutine when it is given a prefix argument).
Dave Love's avatar
#  
Dave Love committed
1052

1053
@kindex C-c C-c @r{(C mode)}
1054 1055 1056 1057 1058 1059 1060 1061
@findex comment-region
@findex uncomment-region
  The command @kbd{M-x comment-region} is equivalent to calling
@kbd{M-;} on an active region, except that it always acts on the
region, even if the mark is inactive.  In C mode and related modes,
this command is bound to @kbd{C-c C-c}.  The command @kbd{M-x
uncomment-region} uncomments each line in the region; a numeric prefix
argument specifies the number of comment delimiters to remove
1062 </