programs.texi

@c -*- coding: utf-8 -*-
@c This is part of the Emacs manual.
@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2019 Free Software
@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Programs
@chapter Editing Programs
@cindex Lisp editing
@cindex C editing
@cindex program editing

  This chapter describes Emacs features for facilitating editing
programs.  Some of the things these features can do are:

@itemize @bullet
@item
Find or move over top-level definitions (@pxref{Defuns}).
@item
Apply the usual indentation conventions of the language
(@pxref{Program Indent}).
@item
Balance parentheses (@pxref{Parentheses}).
@item
Insert, kill or align comments (@pxref{Comments}).
@item
Highlight program syntax (@pxref{Font Lock}).
@end itemize

@menu
* Program Modes::       Major modes for editing programs.
* Defuns::              Commands to operate on major top-level parts
                          of a program.
* Program Indent::      Adjusting indentation to show the nesting.
* Parentheses::         Commands that operate on parentheses.
* Comments::            Inserting, killing, and aligning comments.
* Documentation::       Getting documentation of functions you plan to call.
* Hideshow::            Displaying blocks selectively.
* Symbol Completion::   Completion on symbol names of your program or language.
* MixedCase Words::     Dealing with identifiersLikeThis.
* Semantic::            Suite of editing tools based on source code parsing.
* Misc for Programs::   Other Emacs features useful for editing programs.
* C Modes::             Special commands of C, C++, Objective-C, Java,
                          IDL, Pike and AWK modes.
* Asm Mode::            Asm mode and its special features.
@ifnottex
* Fortran::             Fortran mode and its special features.
@end ifnottex
@end menu

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

  Emacs has specialized major modes (@pxref{Major Modes}) for many
programming languages.  A programming language mode typically
specifies the syntax of expressions, the customary rules for
indentation, how to do syntax highlighting for the language, and how
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}.

@cindex Perl mode
@cindex Icon mode
@cindex Makefile mode
@cindex Tcl mode
@cindex CPerl mode
@cindex DSSSL mode
@cindex Octave mode
@cindex Metafont mode
@cindex Modula2 mode
@cindex Prolog mode
@cindex Python mode
@cindex Ruby mode
@cindex Simula mode
@cindex Verilog mode
@cindex VHDL mode
@cindex M4 mode
@cindex Shell-script mode
@cindex OPascal mode
@cindex PostScript mode
@cindex Conf mode
@cindex DNS mode
@cindex Javascript mode
@cindex Awk mode
  Emacs has programming language modes for Lisp, Scheme, the
Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++,
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.

  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.

@kindex DEL @r{(programming modes)}
@findex backward-delete-char-untabify
  In most programming languages, indentation should vary from line to
line to illustrate the structure of the program.  Therefore, in most
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.

@cindex mode hook, and major modes
@vindex c-mode-hook
@vindex lisp-mode-hook
@vindex emacs-lisp-mode-hook
@vindex lisp-interaction-mode-hook
@vindex scheme-mode-hook
  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.

@ifnottex
  Separate manuals are available for the modes for Ada (@pxref{Top,,
Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba
IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), Octave, VHDL,
and IDLWAVE (@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}).
@end ifnottex
@iftex
  The Emacs distribution contains Info manuals for the major modes for
Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, Octave, VHDL, and
IDLWAVE@.  For Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized
Emacs Features}.
@end iftex

@node Defuns
@section Top-Level Definitions, or Defuns

  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.

@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

@node Left Margin Paren
@subsection Left Margin Convention

@cindex open-parenthesis in leftmost column
@cindex ( in leftmost column
  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.

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

  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
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:

@example
  (insert "Foo:
\(bar)
")
@end example

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

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

  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.

@node Moving by Defuns
@subsection Moving by Defuns
@cindex defuns

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

@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

@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
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.

@kindex C-M-h @r{(C mode)}
@findex c-mark-function
  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
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}.

  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
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.

@node Imenu
@subsection Imenu
@cindex index of buffer definitions
@cindex buffer definitions index

  The Imenu facility offers a way to find the major definitions in
a file by name.  It is also useful in text formatter major modes,
where it treats each chapter, section, etc., as a definition.
(@xref{Xref}, for a more powerful feature that handles multiple files
together.)

@findex imenu
  If you type @kbd{M-x imenu}, it reads the name of a definition using
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.

@findex imenu-add-menubar-index
  Alternatively, you can bind the command @code{imenu} to a mouse
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
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.

@vindex imenu-auto-rescan
  When you change the contents of a buffer, if you add or delete
definitions, you can update the buffer's index based on the
new contents by invoking the @samp{*Rescan*} item in the menu.
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
changes in the text.

@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.

@vindex imenu-sort-function
  You can customize the way the menus are sorted by setting the
variable @code{imenu-sort-function}.  By default, names are ordered as
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.

  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
@cindex current function name in mode line

  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.

@findex which-function-mode
@vindex which-func-modes
  To either enable or disable Which Function mode, use the command
@kbd{M-x which-function-mode}.  Which Function mode is a global minor
mode.  By default, it takes effect in all major modes that
know how to support it (i.e., all the major modes that support
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.

@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
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.

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

@menu
* Basic Indent::        Indenting a single line.
* Multi-line Indent::   Commands to reindent many lines at once.
* 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.
@end menu

@cindex pretty-printer
  Emacs also provides a Lisp pretty-printer in the @code{pp} package,
which reformats Lisp objects with nice-looking indentation.
@xref{Output Functions, pp,, elisp, The Emacs Lisp Reference Manual}.

@node Basic Indent
@subsection Basic Program Indentation Commands

@table @kbd
@item @key{TAB}
Adjust indentation of current line (@code{indent-for-tab-command}).
@item @key{RET}
Insert a newline, then adjust indentation of following line
(@code{newline}).
@end table

@kindex TAB @r{(programming modes)}
@findex indent-line-function
  The basic indentation command is @kbd{@key{TAB}}
(@code{indent-for-tab-command}), which was documented in
@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.

  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.

  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
manually give one of these lines a nonstandard indentation (e.g., for
aesthetic purposes), the lines below will follow it.

  The indentation commands for most programming language modes assume
that an open-parenthesis, open-brace or other opening delimiter at the
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
Paren}.

@node Multi-line Indent
@subsection Indenting Several Lines

  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
region is non-empty, @kbd{@key{TAB}} indents every line in the region.
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:

@table @kbd
@item C-M-q
Reindent all the lines within one parenthetical grouping.
@item C-u @key{TAB}
Shift an entire parenthetical grouping rigidly sideways so that its
first line is properly indented.
@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.
@end table

@kindex C-M-q
@findex indent-pp-sexp
  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
grouping, without affecting its overall indentation (i.e., the
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,
etc.  To correct the overall indentation as well, type @kbd{@key{TAB}}
first.

@kindex C-u TAB
  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,
@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.

@findex indent-code-rigidly
  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.

@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
  Certain functions override the standard pattern.  Functions whose
names start with @code{def} treat the second lines as the start of
a @dfn{body}, by indenting the second line @code{lisp-body-indent}
additional columns beyond the open-parenthesis that starts the
expression.

@cindex @code{lisp-indent-function} property
  You can override the standard pattern in various ways for individual
functions, according to the @code{lisp-indent-function} property of
the function name.  This is normally done for macro definitions, using
the @code{declare} construct.  @xref{Defining Macros,,, elisp, The
Emacs Lisp Reference Manual}.

@node C Indent
@subsection Commands for C Indentation

  Here are special features for indentation in C mode and related modes:

@table @kbd
@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
(@code{c-indent-exp}).  A prefix argument inhibits warning messages
about invalid syntax.

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

@vindex c-tab-always-indent
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
line, and also insert a tab if within a comment or a string.
@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
@cindex style (for indentation)

  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}.

@table @kbd
@item C-c . @var{style} @key{RET}
Select a predefined style @var{style} (@code{c-set-style}).
@end table

  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
predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
@code{stroustrup}, @code{linux}, @code{python}, @code{java},
@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
typing @kbd{C-M-q} at the start of a function definition.

@kindex C-c . @r{(C mode)}
@findex c-set-style
  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).
This command affects the current buffer only, and it affects only
future invocations of the indentation commands; it does not reindent
the code already in the buffer.  To reindent the whole buffer in the
new style, you can type @kbd{C-x h C-M-\}.

@vindex c-default-style
  You can also set the variable @code{c-default-style} to specify the
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,

@example
(setq c-default-style
      '((java-mode . "java")
        (awk-mode . "awk")
        (other . "gnu")))
@end example

@noindent
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.

  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.

  @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,
including how to override parts of an existing style and how to define
your own styles.

@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
c-guess-install}.  @xref{Guessing the Style,,, ccmode, the CC Mode
Manual}, for details.

@node Parentheses
@section Commands for Editing with Parentheses

@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.

  When talking about these facilities, the term ``parenthesis'' also
includes braces, brackets, or whatever delimiters are defined to match
in pairs.  The major mode controls which delimiters are significant,
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.

  You can use @kbd{M-x check-parens} to find any unbalanced
parentheses and unbalanced string quotes in the buffer.

@menu
* Expressions::         Expressions with balanced parentheses.
* Moving by Parens::    Commands for moving up, down and across
                          in the structure of parentheses.
* Matching::            Insertion of a close-delimiter flashes matching open.
@end menu

@node Expressions
@subsection Expressions with Balanced Parentheses

@cindex sexp
@cindex expression
@cindex balanced expression
  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.}).

@table @kbd
@item C-M-f
Move forward over a balanced expression (@code{forward-sexp}).
@item C-M-b
Move backward over a balanced expression (@code{backward-sexp}).
@item C-M-k
Kill balanced expression forward (@code{kill-sexp}).
@item C-M-t
Transpose expressions (@code{transpose-sexps}).
@item C-M-@@
@itemx C-M-@key{SPC}
Put mark after following expression (@code{mark-sexp}).
@end table

@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
is an opening delimiter (e.g., @samp{(}, @samp{[} or @samp{@{} in C),
this command moves past the matching closing delimiter.  If the
character begins a symbol, string, or number, the command moves over
that.

  The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
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}).

@cindex killing expressions
@kindex C-M-k
@findex kill-sexp
  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.

@cindex transposition of expressions
@kindex C-M-t
@findex transpose-sexps
  @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.

@kindex C-M-SPC
  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.

  In languages that use infix operators, such as C, it is not possible
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.

@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

  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
within them, and also ignore parentheses that are quoted with an
escape character.  These commands are mainly intended for editing
programs, but can be useful for editing any text containing
parentheses.  They are referred to internally as ``list commands''
because in Lisp these groupings are lists.

  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.

@table @kbd
@item C-M-n
Move forward over a parenthetical group (@code{forward-list}).
@item C-M-p
Move backward over a parenthetical group (@code{backward-list}).
@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}).
@end table

@kindex C-M-n
@kindex C-M-p
@findex forward-list
@findex backward-list
  The list commands @kbd{C-M-n} (@code{forward-list}) and
@kbd{C-M-p} (@code{backward-list}) move forward or backward over one
(or @var{n}) parenthetical groupings.

@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
that the command moves forward and up one or more levels.

@kindex C-M-d
@findex down-list
  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.

@node Matching
@subsection Matching Parentheses
@cindex matching parentheses
@cindex parentheses, displaying matches

  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
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.

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

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

@item
@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.

@item
@code{blink-matching-paren-distance} specifies how many characters
back to search to find the matching opening delimiter.  If the match
is not found in that distance, Emacs stops scanning and nothing is
displayed.  The default is 102400.
@end itemize

@cindex Show Paren mode
@cindex highlighting matching parentheses
@findex show-paren-mode
  Show Paren mode, a global minor mode, provides a more powerful kind
of automatic matching.  Whenever point is before an opening delimiter
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
@vindex show-paren-highlight-openparen
@code{show-paren-highlight-openparen} controls whether to highlight
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
@vindex show-paren-style
@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
@vindex show-paren-when-point-inside-paren
@code{show-paren-when-point-inside-paren}, when non-@code{nil}, causes
highlighting also when point is on the inside of a parenthesis.

@item
@vindex show-paren-when-point-in-periphery
@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

@cindex Electric Pair mode
@cindex inserting matching parentheses
@findex electric-pair-mode
  Electric Pair mode, a global minor mode, provides a way to easily
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:

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

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

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

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

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}.

@node Comments
@section Manipulating Comments
@cindex comments

  Because comments are such an important part of programming, Emacs
provides special commands for editing and inserting comments.  It can
also do spell checking on comments with Flyspell Prog mode
(@pxref{Spelling}).

  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
margin and are often used for sectioning purposes.  Emacs understands
these conventions; for instance, typing @kbd{@key{TAB}} on a comment
line will indent the comment to the appropriate position.

@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

@menu
* Comment Commands::    Inserting, killing, and aligning comments.
* Multi-Line Comments:: Commands for adding and editing multi-line comments.
* Options for Comments::Customizing the comment features.
@end menu

@node Comment Commands
@subsection Comment Commands
@cindex indentation for comments
@cindex alignment for comments

  The following commands operate on comments:

@table @asis
@item @kbd{M-;}
Insert or realign comment on current line; if the region is active,
comment or uncomment the region instead (@code{comment-dwim}).
@item @kbd{C-x C-;}
Comment or uncomment the current line (@code{comment-line}).  If the
region is active, comment or uncomment the lines in the region
instead.
@item @kbd{C-u M-;}
Kill comment on current line (@code{comment-kill}).
@item @kbd{C-x ;}
Set comment column (@code{comment-set-column}).
@item @kbd{C-M-j}
@itemx @kbd{M-j}
Like @kbd{@key{RET}} followed by inserting and aligning a comment
(@code{comment-indent-new-line}).  @xref{Multi-Line Comments}.
@item @kbd{M-x comment-region}
@itemx @kbd{C-c C-c} (in C-like modes)
Add comment delimiters to all the lines in the region.
@end table

@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.

  When a region is active (@pxref{Mark}), @kbd{M-;} either adds
comment delimiters to the region, or removes them.  If every line in
the region is already a comment, it uncomments each of those lines
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
the line is blank (i.e., empty or containing only whitespace
characters), the comment is indented to the same position where
@kbd{@key{TAB}} would indent to (@pxref{Basic Indent}).  If the line
is non-blank, the comment is placed after the last non-whitespace
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.

  You can also use @kbd{M-;} to align an existing comment.  If a line
already contains the comment-start string, @kbd{M-;} realigns it to
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.

@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.

@findex comment-kill
@kindex C-u M-;
  @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
then @kbd{M-;} to realign the comment.  You can achieve the same
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).

@kindex C-c C-c @r{(C mode)}
@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