2268 lines
92 KiB
Plaintext
2268 lines
92 KiB
Plaintext
@c -*- coding: utf-8 -*-
|
|
@c This is part of the Emacs manual.
|
|
@c Copyright (C) 1985--1987, 1993--1995, 1997, 1999--2024 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
|
|
@cindex C# mode
|
|
@cindex IDLWAVE mode
|
|
@cindex JSON mode
|
|
@cindex SQL mode
|
|
@cindex TypeScript mode
|
|
@cindex CSS mode
|
|
@cindex Dockerfile mode
|
|
@cindex CMake mode
|
|
@cindex TOML mode
|
|
Emacs has programming language modes for Lisp, Scheme, the
|
|
Scheme-based DSSSL expression language, Ada, ASM, AWK, C, 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, TypeScript, 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, JSON, DNS master
|
|
files, CSS (Cascading Style Sheets), Dockerfiles, CMake 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.
|
|
|
|
@cindex tree-sitter library, supported major modes
|
|
If Emacs has been compiled with the @samp{tree-sitter} library, it
|
|
offers several optional editing modes based on that library, which
|
|
utilize the incremental parsing capabilities provided by
|
|
@samp{tree-sitter}. These modes have @samp{-ts-} in their names; for
|
|
example @code{c-ts-mode}, @code{python-ts-mode}, etc.
|
|
|
|
@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.
|
|
* Moving by Sentences:: Commands to move over certain code units.
|
|
* 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 have traditionally assumed that any
|
|
opening parenthesis or brace found at the left margin is the start of
|
|
a top-level definition, or defun. So, by default, commands which seek
|
|
the beginning of a defun accept such a delimiter as signifying that
|
|
position.
|
|
|
|
@vindex open-paren-in-column-0-is-defun-start
|
|
If you want to override this convention, you can do so by setting
|
|
the user option @code{open-paren-in-column-0-is-defun-start} to
|
|
@code{nil}. If this option is set to @code{t} (the default), commands
|
|
seeking the start of a defun will stop at opening parentheses or
|
|
braces at column zero which aren't in a comment or string. When it is
|
|
@code{nil}, defuns are found by searching for parens or braces at the
|
|
outermost level. Since low-level Emacs routines no longer depend on
|
|
this convention, you usually won't need to change
|
|
@code{open-paren-in-column-0-is-defun-start} from its default.
|
|
|
|
@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.
|
|
|
|
@cindex nested defuns
|
|
@vindex treesit-defun-tactic
|
|
Some programming languages supported @dfn{nested defuns}, whereby a
|
|
defun (such as a function or a method or a class) can be defined
|
|
inside (i.e., as part of the body) of another defun. The commands
|
|
described above by default find the beginning and the end of the
|
|
@emph{innermost} defun around point. Major modes based on the
|
|
tree-sitter library provide control of this behavior: if the variable
|
|
@code{treesit-defun-tactic} is set to the value @code{top-level}, the
|
|
defun commands will find the @emph{outermost} defuns instead.
|
|
|
|
@node Moving by Sentences
|
|
@subsection Moving by Sentences
|
|
@cindex sentences, in programming languages
|
|
|
|
These commands move point or set up the region based on units of
|
|
code, also called @dfn{sentences}. Even though sentences are usually
|
|
considered when writing human languages, Emacs can use the same
|
|
commands to move over certain constructs in programming languages
|
|
(@pxref{Sentences}, @pxref{Moving by Defuns}). In a programming
|
|
language a sentence is usually a complete language construct smaller
|
|
than defuns, but larger than sexps (@pxref{List Motion,,, elisp, The
|
|
Emacs Lisp Reference Manual}). What exactly is a sentence in this
|
|
case depends on the programming language, but usually it is a complete
|
|
statement, such as a variable definition and initialization, or a
|
|
conditional statement. An example of a sentence in the C language
|
|
could be
|
|
|
|
@example
|
|
int x = 5;
|
|
@end example
|
|
|
|
@noindent
|
|
or in the JavaScript language it could look like
|
|
|
|
@example
|
|
@group
|
|
const thing = () => console.log("Hi");
|
|
@end group
|
|
@group
|
|
const foo = [1] == '1'
|
|
? "No way"
|
|
: "...";
|
|
@end group
|
|
|
|
@end example
|
|
|
|
@table @kbd
|
|
@item M-a
|
|
Move to beginning of current or preceding sentence
|
|
(@code{backward-sentence}).
|
|
@item M-e
|
|
Move to end of current or following sentence (@code{forward-sentence}).
|
|
@end table
|
|
|
|
@cindex move to beginning or end of sentence
|
|
@cindex sentence, move to beginning or end
|
|
@kindex M-a @r{(programming modes)}
|
|
@kindex M-e @r{(programming modes)}
|
|
@findex backward-sentence @r{(programming modes)}
|
|
@findex forward-sentence @r{(programming modes)}
|
|
The commands to move to the beginning and end of the current
|
|
sentence are @kbd{M-a} (@code{backward-sentence}) and @kbd{M-e}
|
|
(@code{forward-sentence}). If you repeat one of these commands, or
|
|
use a positive numeric argument, each repetition moves to the next
|
|
sentence in the direction of motion.
|
|
|
|
@kbd{M-a} with a negative argument @minus{}@var{n} moves forward
|
|
@var{n} times to the next end of a sentence. Likewise, @kbd{M-e} with
|
|
a negative argument moves back to the start of a sentence.
|
|
|
|
@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 useful both in programming-language major modes,
|
|
where the definitions are variables, functions, etc., and 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
|
|
@vindex imenu-flatten
|
|
If you type @kbd{M-g i} (@code{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 displays the
|
|
list of matching valid names in the completions buffer. If the index is
|
|
hierarchical, then by default the completion candidates are also shown
|
|
hierarchically, as a nested list: first you need to choose a section,
|
|
then a subsection, etc., and finally the name of the definition.
|
|
However, if you set @code{imenu-flatten} to a non-@code{nil} value, then
|
|
instead of the nested menu you can select a completion candidate from a
|
|
flattened list of definitions. How the sections and subsections are
|
|
shown in the flattened list of completion candidates depends on the
|
|
value of @code{imenu-flatten}, which can be one of the following:
|
|
|
|
@table @code
|
|
@vindex imenu-level-separator
|
|
@item prefix
|
|
This shows each candidate prefixed by names of its section, subsection,
|
|
subsubsection, etc., with each level separated from the next by the
|
|
string that is the value of @code{imenu-level-separator}, by default
|
|
@samp{:}.
|
|
|
|
@item annotation
|
|
This shows the section names as annotations, following each definition
|
|
name.
|
|
|
|
@item group
|
|
This shows the completion candidates grouped by their sections.
|
|
@end table
|
|
|
|
@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
|
|
@vindex imenu-max-index-time
|
|
@code{imenu-auto-rescan} will be disabled in buffers that are larger
|
|
than @code{imenu-auto-rescan-maxout} in bytes, and scanning is
|
|
stopped if it takes more than @code{imenu-max-index-time} seconds.
|
|
|
|
@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.
|
|
|
|
You can also customize how Imenu completions are sorted by changing
|
|
the variable @code{completion-category-overrides} and setting its
|
|
@code{display-sort-function} for the category @code{imenu}.
|
|
|
|
If Eglot is activated for the current buffer's project
|
|
(@pxref{Projects}) and the current buffer's major mode, Eglot provides
|
|
its own facility for producing the buffer's index based on the
|
|
analysis of the program source by the language-server which manages
|
|
the current buffer. @xref{Eglot Features,,, eglot, Eglot: The Emacs
|
|
LSP Client}.
|
|
|
|
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 or header
|
|
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.
|
|
|
|
@vindex which-func-display
|
|
By default, Which Function mode displays the current function name
|
|
using the mode line. Customize @code{which-func-display} to
|
|
@code{header}, @code{mode}, or @code{mode-and-header} to use the
|
|
header line, mode line, or both, respectively.
|
|
|
|
@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 M-q
|
|
Fill a single paragraph in a defun, or reindent all the lines within
|
|
that defun.
|
|
@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 M-q
|
|
@findex prog-fill-reindent-defun
|
|
@vindex beginning-of-defun-function
|
|
@vindex end-of-defun-function
|
|
@vindex fill-paragraph-function
|
|
To reindent the entire defun around point, type @kbd{M-q}
|
|
(@code{prog-fill-reindent-defun}). If point is in a comment or a
|
|
string, this command fills and indents the comment or string instead.
|
|
What exactly constitutes a comment, a string, or a defun depends on
|
|
the major mode: the bounds of a defun are decided by the variables
|
|
@code{beginning-of-defun-function} and @code{end-of-defun-function}
|
|
(@pxref{List Motion,,, elisp, The Emacs Lisp Reference Manual}),
|
|
and the filling mechanism is decided by @code{fill-paragraph-function}
|
|
(@pxref{Filling,,, elisp, The Emacs Lisp Reference Manual}).
|
|
|
|
@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}.
|
|
|
|
In Emacs Lisp, lists are usually indented as if they are
|
|
function-like forms:
|
|
|
|
@lisp
|
|
(setq foo '(bar zot
|
|
gazonk))
|
|
@end lisp
|
|
|
|
However, if you add a space after the opening parenthesis, this tells
|
|
Emacs that it's a data list instead of a piece of code, and Emacs will
|
|
then indent it like this:
|
|
|
|
@lisp
|
|
(setq foo '( bar zot
|
|
gazonk))
|
|
@end lisp
|
|
|
|
@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
|
|
@findex c-ts-mode-indent-defun
|
|
Reindent the current top-level function definition or aggregate type
|
|
declaration (@code{c-indent-defun} in CC mode,
|
|
@code{c-ts-mode-indent-defun} in @code{c-ts-mode} based on tree-sitter).
|
|
|
|
@item C-M-q
|
|
@kindex C-M-q @r{(C mode)}
|
|
@findex c-indent-exp
|
|
@findex prog-indent-sexp
|
|
Reindent each line in the balanced expression (@pxref{Expressions}),
|
|
also known as ``sexp'', that follows point. In CC mode, this invokes
|
|
@code{c-indent-exp}; in tree-sitter based @code{c-ts-mode} this
|
|
invokes a more general @code{prog-indent-sexp}. A prefix argument
|
|
inhibits warning messages about invalid syntax.
|
|
|
|
@item @key{TAB}
|
|
@findex c-indent-line-or-region
|
|
Reindent the current line, active region, or block starting on this
|
|
line (@code{c-indent-line-or-region}). With prefix argument, rigidly
|
|
reindent the balanced expression which starts on the current line, if
|
|
the current line needs reindentation.
|
|
|
|
@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} in CC mode,
|
|
@code{c-ts-mode-set-style} in @code{c-ts-mode} based on tree-sitter).
|
|
@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
|
|
@findex c-ts-mode-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
|
|
When using CC mode, 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.
|
|
|
|
@vindex c-ts-mode-indent-style
|
|
When using the tree-sitter based @code{c-ts-mode}, you can set the
|
|
default indentation style by customizing the variable
|
|
@code{c-ts-mode-indent-style}.
|
|
|
|
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
|
|
@findex show-paren-local-mode
|
|
Show Paren mode is a minor mode that 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 globally, type @kbd{M-x show-paren-mode}. To toggle it
|
|
only in the current buffer, type @kbd{M-x show-paren-local-mode}.
|
|
|
|
@vindex show-paren-predicate
|
|
By default, this mode is switched on in all buffers that are meant
|
|
for editing, but is not enabled in buffers that show data. This is
|
|
controlled by the @code{show-paren-predicate} user option.
|
|
|
|
To customize the mode, type @w{@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 is 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 text 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 in the
|
|
window, 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 inside of the parentheses. The
|
|
default is @code{nil}.
|
|
|
|
@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 of a
|
|
line and there is a paren at the first or last non-whitespace position
|
|
on the line, or when point is at the end of a line and there is a
|
|
paren at the last non-whitespace position on the line.
|
|
|
|
@item
|
|
@vindex show-paren-context-when-offscreen
|
|
@code{show-paren-context-when-offscreen}, when non-@code{nil}, shows
|
|
some context in the echo area when point is in a closing delimiter and
|
|
the opening delimiter is offscreen. The context is usually the line
|
|
that contains the opening delimiter, except if the opening delimiter
|
|
is on its own line, in which case the context includes the previous
|
|
nonblank 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{default-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 @minus{}@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 argument
|
|
@minus{}@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) when the
|
|
region is not active 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). Invoking
|
|
@code{comment-dwim} with a prefix numeric argument, as in @w{@kbd{C-u
|
|
@var{n} M-;}}, when there's no active region, tells
|
|
@code{comment-kill} to kill comments on @var{n} lines.
|
|
|
|
@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
|
|
(negative arguments specify the number of comment delimiters to add).
|
|
|
|
For C-like modes, you can configure the exact effect of @kbd{M-;} by
|
|
setting the variables @code{c-indent-comment-alist} and
|
|
@code{c-indent-comments-syntactically-p}. For example, on a line
|
|
ending in a closing brace, @kbd{M-;} puts the comment one space after
|
|
the brace rather than at @code{comment-column}. For full details see
|
|
@ref{Comment Commands,,, ccmode, The CC Mode Manual}.
|
|
|
|
@node Multi-Line Comments
|
|
@subsection Multiple Lines of Comments
|
|
|
|
@kindex C-M-j
|
|
@kindex M-j
|
|
@cindex blank lines in programs
|
|
@findex default-indent-new-line
|
|
@vindex comment-multi-line
|
|
If you are typing a comment and wish to continue it to another line,
|
|
type @kbd{M-j} or @kbd{C-M-j} (@code{default-indent-new-line}). This
|
|
breaks the current line, and inserts the necessary comment delimiters
|
|
and indentation to continue the comment.
|
|
|
|
For languages with closing comment delimiters (e.g., @samp{*/} in
|
|
C), the exact behavior of @kbd{M-j} depends on the value of the
|
|
variable @code{comment-multi-line}. If the value is @code{nil}, the
|
|
command closes the comment on the old line and starts a new comment on
|
|
the new line. Otherwise, it opens a new line within the current
|
|
comment delimiters.
|
|
|
|
When Auto Fill mode is on, going past the fill column while typing a
|
|
comment also continues the comment, in the same way as an explicit
|
|
invocation of @kbd{M-j}.
|
|
|
|
To turn existing lines into comment lines, use @kbd{M-;} with the
|
|
region active, or use @kbd{M-x comment-region}
|
|
@ifinfo
|
|
(@pxref{Comment Commands}).
|
|
@end ifinfo
|
|
@ifnotinfo
|
|
as described in the preceding section.
|
|
@end ifnotinfo
|
|
|
|
You can configure C Mode such that when you type a @samp{/} at the
|
|
start of a line in a multi-line block comment, this closes the
|
|
comment. Enable the @code{comment-close-slash} clean-up for this.
|
|
@xref{Clean-ups,,, ccmode, The CC Mode Manual}.
|
|
|
|
@node Options for Comments
|
|
@subsection Options Controlling Comments
|
|
|
|
@vindex comment-column
|
|
@vindex comment-fill-column
|
|
@kindex C-x ;
|
|
@findex comment-set-column
|
|
As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command
|
|
adds a comment to a line, it tries to place the comment between the
|
|
columns specified by the buffer-local variables @code{comment-column}
|
|
and @code{comment-fill-column} (or if that is @code{nil}, then the
|
|
value of @code{fill-column}, @pxref{Fill Commands}). You can set
|
|
either the local value or the default value of these buffer-local
|
|
variables in the usual way (@pxref{Locals}). Alternatively, you can
|
|
type @kbd{C-x ;} (@code{comment-set-column}) to set the value of
|
|
@code{comment-column} in the current buffer to the column where point
|
|
is currently located. @kbd{C-u C-x ;} sets the comment column to
|
|
match the last comment before point in the buffer, and then does a
|
|
@kbd{M-;} to align the current line's comment under the previous one.
|
|
|
|
@vindex comment-start-skip
|
|
The comment commands recognize comments based on the regular
|
|
expression that is the value of the variable @code{comment-start-skip}.
|
|
Make sure this regexp does not match the null string. It may match more
|
|
than the comment starting delimiter in the strictest sense of the word;
|
|
for example, in C mode the value of the variable could be
|
|
@c This stops M-q from breaking the line inside that @code.
|
|
@code{@w{"/\\*+[ \t]*\\|//+[ \t]*"}}, which matches extra stars and
|
|
spaces after the @samp{/*} itself, and accepts C++ style (@samp{//})
|
|
comments also. (Note that @samp{\\} is needed in Lisp syntax to
|
|
include a @samp{\} in the string, which is needed to deny the first
|
|
star its special meaning in regexp syntax. @xref{Regexp Backslash}.)
|
|
|
|
@vindex comment-start
|
|
@vindex comment-end
|
|
When a comment command makes a new comment, it inserts the value of
|
|
@code{comment-start} as an opening comment delimiter. It also inserts
|
|
the value of @code{comment-end} after point, as a closing comment
|
|
delimiter. For example, in Lisp mode, @code{comment-start} is
|
|
@samp{";"} and @code{comment-end} is @code{""} (the empty string). In
|
|
C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is
|
|
@code{" */"}.
|
|
|
|
@vindex comment-padding
|
|
The variable @code{comment-padding} specifies a string that the
|
|
commenting commands should insert between the comment delimiter(s) and
|
|
the comment text. The default, @samp{" "}, specifies a single space.
|
|
Alternatively, the value can be a number, which specifies that number
|
|
of spaces, or @code{nil}, which means no spaces at all.
|
|
|
|
The variable @code{comment-multi-line} controls how @kbd{M-j} and
|
|
Auto Fill mode continue comments over multiple lines.
|
|
@xref{Multi-Line Comments}.
|
|
|
|
@vindex comment-indent-function
|
|
The variable @code{comment-indent-function} should contain a function
|
|
that will be called to compute the alignment for a newly inserted
|
|
comment or for aligning an existing comment. It is set differently by
|
|
various major modes. The function is called with no arguments, but with
|
|
point at the beginning of the comment, or at the end of a line if a new
|
|
comment is to be inserted. It should return the column in which the
|
|
comment ought to start. For example, the default function bases its
|
|
decision on how many comment characters begin an existing comment.
|
|
|
|
Emacs also tries to align comments on adjacent lines. To override
|
|
this, the function may return a cons of two (possibly equal) integers
|
|
to indicate an acceptable range of indentation.
|
|
|
|
@node Documentation
|
|
@section Documentation Lookup
|
|
|
|
Emacs provides several features you can use to look up the
|
|
documentation of functions, variables and commands that you plan to
|
|
use in your program.
|
|
|
|
@menu
|
|
* Info Lookup:: Looking up library functions and commands in Info files.
|
|
* Man Page:: Looking up man pages of library functions and commands.
|
|
* Programming Language Doc:: Looking up program functions, variables, etc.
|
|
@end menu
|
|
|
|
@node Info Lookup
|
|
@subsection Info Documentation Lookup
|
|
|
|
@findex info-lookup-file
|
|
For major modes that apply to languages which have documentation in
|
|
Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the
|
|
Info documentation for a symbol used in the program. You specify the
|
|
symbol with the minibuffer; the default is the symbol appearing in the
|
|
buffer at point. For example, in C mode this looks for the symbol in
|
|
the C Library Manual. The command only works if the appropriate
|
|
manual's Info files are installed.
|
|
|
|
Emacs determines where to look for documentation for the
|
|
symbol---which Info files to look in, and which indices to
|
|
search---based on the major mode. You can also use @kbd{M-x
|
|
info-lookup-file} to look for documentation for a file name.
|
|
|
|
If you use @kbd{C-h S} in a major mode that does not support it,
|
|
it asks you to specify the symbol help mode. You should enter
|
|
a command such as @code{c-mode} that would select a major
|
|
mode which @kbd{C-h S} does support.
|
|
|
|
@node Man Page
|
|
@subsection Man Page Lookup
|
|
|
|
@cindex man page
|
|
On Unix, the main form of on-line documentation was the @dfn{manual
|
|
page} or @dfn{man page}. In the GNU operating system, we aim to
|
|
replace man pages with better-organized manuals that you can browse
|
|
with Info (@pxref{Misc Help}). This process is not finished, so it is
|
|
still useful to read manual pages.
|
|
|
|
@findex man
|
|
You can read the man page for an operating system command, library
|
|
function, or system call, with the @kbd{M-x man} command. This
|
|
prompts for a topic, with completion (@pxref{Completion}), and runs
|
|
the @command{man} program to format the corresponding man page. If
|
|
the system permits, it runs @command{man} asynchronously, so that you
|
|
can keep on editing while the page is being formatted. The result
|
|
goes in a buffer named @file{*Man @var{topic}*}. These buffers use a
|
|
special major mode, Man mode, that facilitates scrolling and jumping
|
|
to other manual pages. For details, type @kbd{C-h m} while in a Man
|
|
mode buffer.
|
|
|
|
@cindex sections of manual pages
|
|
Each man page belongs to one of ten or more @dfn{sections}, each
|
|
named by a digit or by a digit and a letter. Sometimes there are man
|
|
pages with the same name in different sections. To read a man page
|
|
from a specific section, type @samp{@var{topic}(@var{section})} or
|
|
@samp{@var{section} @var{topic}} when @kbd{M-x man} prompts for the
|
|
topic. For example, the man page for the C library function
|
|
@code{chmod} is in section 2, but there is a shell command of the same
|
|
name, whose man page is in section 1; to view the former, type
|
|
@w{@kbd{M-x man @key{RET} chmod(2) @key{RET}}}.
|
|
|
|
@vindex Man-switches
|
|
@kindex M-n @r{(Man mode)}
|
|
@kindex M-p @r{(Man mode)}
|
|
If you do not specify a section, @kbd{M-x man} normally displays
|
|
only the first man page found. On some systems, the @code{man}
|
|
program accepts a @samp{-a} command-line option, which tells it to
|
|
display all the man pages for the specified topic. To make use of
|
|
this, change the value of the variable @code{Man-switches} to
|
|
@samp{"-a"}. Then, in the Man mode buffer, you can type @kbd{M-n} and
|
|
@kbd{M-p} to switch between man pages in different sections. The mode
|
|
line shows how many manual pages are available.
|
|
|
|
@vindex Man-prefer-synchronous-call
|
|
By default, @kbd{M-x man} calls the @code{man} program
|
|
asynchronously. You can force the invocation to be synchronous by
|
|
customizing @code{Man-prefer-synchronous-calls} to a non-@code{nil}
|
|
value.
|
|
|
|
@vindex Man-support-remote-systems
|
|
If the user option @code{Man-support-remote-systems} is
|
|
non-@code{nil}, and @code{default-directory} indicates a remote system
|
|
(@pxref{Remote Files}), the man page is taken from the remote system.
|
|
Calling the @code{man} command with a prefix like @kbd{C-u M-x man}
|
|
reverts the value of @code{Man-support-remote-systems} for that call.
|
|
|
|
@findex woman
|
|
@cindex manual pages, on MS-DOS/MS-Windows
|
|
An alternative way of reading manual pages is the @kbd{M-x woman}
|
|
command. Unlike @kbd{M-x man}, it does not run any external programs
|
|
to format and display the man pages; the formatting is done by Emacs,
|
|
so it works on systems such as MS-Windows where the @command{man}
|
|
program may be unavailable. It prompts for a man page, and displays
|
|
it in a buffer named @file{*WoMan @var{section} @var{topic}}.
|
|
|
|
@kbd{M-x woman} computes the completion list for manpages the first
|
|
time you invoke the command. With a numeric argument, it recomputes
|
|
this list; this is useful if you add or delete manual pages.
|
|
|
|
If you type a name of a manual page and @kbd{M-x woman} finds that
|
|
several manual pages by the same name exist in different sections, it
|
|
pops up a window with possible candidates asking you to choose one of
|
|
them.
|
|
|
|
Note that @kbd{M-x woman} doesn't yet support the latest features of
|
|
modern man pages, so we recommend using @kbd{M-x man} if that is
|
|
available on your system.
|
|
|
|
For more information about setting up and using @kbd{M-x woman}, see
|
|
@ifinfo
|
|
@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The
|
|
WoMan Manual}.
|
|
@end ifinfo
|
|
@ifnotinfo
|
|
the WoMan Info manual, which is distributed with Emacs.
|
|
@end ifnotinfo
|
|
|
|
@node Programming Language Doc
|
|
@subsection Programming Language Documentation Lookup
|
|
@cindex documentation for program symbols
|
|
@cindex program functions and variables, documentation lookup
|
|
|
|
When editing Emacs Lisp code, you can use the commands @kbd{C-h f}
|
|
(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable})
|
|
to view the built-in documentation for the Lisp functions and
|
|
variables that you want to use. @xref{Name Help}.
|
|
|
|
@cindex ElDoc mode
|
|
@cindex at-point documentation for program symbols
|
|
@findex eldoc-mode
|
|
@findex global-eldoc-mode
|
|
ElDoc@footnote{
|
|
The name ``ElDoc'' is a historical accident: this mode started by
|
|
supporting Emacs Lisp buffers.
|
|
} is a buffer-local minor mode that helps with looking up
|
|
documentation of symbols (functions, methods, classes, variables,
|
|
etc.) in your program. When this mode is enabled, the echo area
|
|
displays useful information whenever there is a documented symbol at
|
|
point. For example, in buffers under the Emacs Lisp mode, it shows
|
|
the argument list of a function at point, and for a Lisp variable it
|
|
shows the first line of the variable's documentation string.
|
|
|
|
To toggle ElDoc mode, type @kbd{M-x eldoc-mode}. There's also a
|
|
Global ElDoc mode, which is turned on by default, and turns on the
|
|
ElDoc mode in buffers whose major mode sets the variables described
|
|
below. Use @w{@kbd{M-x global-eldoc-mode}} to turn it off globally.
|
|
|
|
Various major modes configure the Global ElDoc mode to use their
|
|
documentation functions. Examples include Emacs Lisp mode, Python
|
|
mode, and Cfengine mode. In addition, Emacs features that provide
|
|
support for several major modes configure ElDoc to use their
|
|
facilities for retrieving the documentation. Examples include Eglot
|
|
(@pxref{Eglot Features,,, eglot, Eglot: The Emacs LSP Client}), which
|
|
provides documentation based on information from language servers;
|
|
Semantic's Idle Summary mode (@pxref{Idle Summary Mode,,, semantic,
|
|
Semantic Manual}); and Flymake, which uses ElDoc to show diagnostics
|
|
at point (@pxref{Finding diagnostics,,, flymake, GNU Flymake manual}).
|
|
|
|
The ElDoc mode works by scheduling the display of the available
|
|
documentation for the symbol at point after Emacs has been idle for
|
|
some short time. This avoids annoying flickering of documentation
|
|
messages in the echo area or the mode line when you type quickly and
|
|
without delay.
|
|
|
|
@findex eldoc-print-current-symbol-info
|
|
You can also trigger the display of documentation for a symbol at
|
|
point by using the command @kbd{M-x eldoc-print-current-symbol-info}.
|
|
|
|
The following variables can be used to configure ElDoc mode:
|
|
|
|
@vtable @code
|
|
@item eldoc-idle-delay
|
|
The value of this user option controls the amount of idle time before
|
|
the at-point documentation is displayed. It should be set to the
|
|
number of seconds to wait; the value of zero means to display without
|
|
any delay. The default is 0.5 sec.
|
|
|
|
@item eldoc-print-after-edit
|
|
If this user option is non-@code{nil}, ElDoc will show documentation
|
|
only after some editing command, like inserting or deleting some
|
|
text. This comes in handy if you want Emacs to display documentation
|
|
only about symbols that you type, but not about symbols that are
|
|
already in the buffer (so just reading the source code will not show
|
|
documentation). The default value is @code{nil}. If you change the
|
|
value, you need to toggle @code{eldoc-mode} off and on again.
|
|
|
|
@item eldoc-echo-area-use-multiline-p
|
|
This user option controls whether and how to truncate documentation
|
|
text if it is longer than the echo-area can display as a single screen
|
|
line. If the value is a positive number, it specifies the number of
|
|
screen lines that ElDoc is allowed to display in the echo area without
|
|
truncating the documentation. A positive integer specifies the
|
|
absolute maximum number of screen lines to use; a floating-point
|
|
number specifies the number of screen lines as a fraction of the
|
|
frame's height. The value of @code{t} means never truncate the
|
|
documentation (the echo-area will be resized up to the height allowed
|
|
by @code{max-mini-window-height}, @pxref{Minibuffer Edit}), whereas
|
|
the value of @code{nil} means truncate if the documentation is longer
|
|
than a single screen line. Finally, the special value
|
|
@code{truncate-sym-name-if-fit} (the default) means to truncate the
|
|
part of the documentation that represents a symbol's name if doing
|
|
that will allow the documentation to fit on a single screen line.
|
|
|
|
@item eldoc-echo-area-display-truncation-message
|
|
If non-@code{nil} (the default), and documentation shown in the echo
|
|
area is truncated because it's too long, follow the documentation by
|
|
instructions about how to view the complete documentation text. If
|
|
@code{nil}, just indicate with @samp{@dots{}} that the documentation
|
|
was truncated.
|
|
|
|
@findex eldoc-doc-buffer
|
|
@item eldoc-echo-area-prefer-doc-buffer
|
|
If the value of this user option is @code{t}, ElDoc will not show the
|
|
documentation in the echo area if the ElDoc buffer with the
|
|
documentation is already displayed in some window. (You can use the
|
|
command @kbd{M-x eldoc-doc-buffer} any time to show the ElDoc buffer.)
|
|
If the value of this option is the symbol @code{maybe}, the
|
|
documentation will not be displayed in the echo area if the ElDoc
|
|
buffer is shown in some window, and the documentation text has to be
|
|
truncated if displayed in the echo area. Finally, the value of
|
|
@code{nil} (the default) means always show the documentation in the
|
|
echo area.
|
|
|
|
@item eldoc-documentation-strategy
|
|
This customizable variable's value is the function which is used to
|
|
retrieve and display documentation for the symbol at point. The
|
|
documentation is produced by the functions in the hook
|
|
@code{eldoc-documentation-functions}. The default value of
|
|
@code{eldoc-documentation-strategy} specifies that ElDoc should
|
|
display the first documentation text produced by functions in the
|
|
@code{eldoc-documentation-functions} hook, but you can customize
|
|
@code{eldoc-documentation-strategy} to work in other ways, such as
|
|
displaying all of the documentation texts concatenated together.
|
|
|
|
@item eldoc-documentation-functions
|
|
This abnormal hook's value is a list of functions that can produce
|
|
documentation for the symbol at point as appropriate for the current
|
|
buffer's major-mode. These functions act as a collection of backends
|
|
for ElDoc. Major modes register their documentation lookup functions
|
|
with ElDoc by adding their functions to the buffer-local value of this
|
|
variable.
|
|
@end vtable
|
|
|
|
@node Hideshow
|
|
@section Hideshow minor mode
|
|
@cindex Hideshow mode
|
|
@cindex mode, Hideshow
|
|
|
|
@findex hs-minor-mode
|
|
Hideshow mode is a buffer-local minor mode that allows you to
|
|
selectively display portions of a program, which are referred to as
|
|
@dfn{blocks}. Type @kbd{M-x hs-minor-mode} to toggle this minor mode
|
|
(@pxref{Minor Modes}).
|
|
|
|
When you use Hideshow mode to hide a block, the block disappears
|
|
from the screen, to be replaced by an ellipsis (three periods in a
|
|
row). Just what constitutes a block depends on the major mode. In C
|
|
mode and related modes, blocks are delimited by braces, while in Lisp
|
|
mode they are delimited by parentheses. Multi-line comments also
|
|
count as blocks.
|
|
|
|
Hideshow mode provides the following commands:
|
|
|
|
@findex hs-hide-all
|
|
@findex hs-hide-block
|
|
@findex hs-show-all
|
|
@findex hs-show-block
|
|
@findex hs-show-region
|
|
@findex hs-hide-level
|
|
@findex hs-toggle-hiding
|
|
@findex hs-toggle-hiding
|
|
@kindex C-c @@ C-h
|
|
@kindex C-c @@ C-s
|
|
@kindex C-c @@ C-c
|
|
@kindex C-c @@ C-M-h
|
|
@kindex C-c @@ C-M-s
|
|
@kindex C-c @@ C-r
|
|
@kindex C-c @@ C-l
|
|
@kindex S-mouse-2
|
|
@table @kbd
|
|
@item C-c @@ C-h
|
|
@itemx C-c @@ C-d
|
|
Hide the current block (@code{hs-hide-block}).
|
|
@item C-c @@ C-s
|
|
Show the current block (@code{hs-show-block}).
|
|
@item C-c @@ C-c
|
|
@itemx C-c @@ C-e
|
|
@itemx S-mouse-2
|
|
Either hide or show the current block (@code{hs-toggle-hiding}).
|
|
@item C-c @@ C-M-h
|
|
@itemx C-c @@ C-t
|
|
Hide all top-level blocks (@code{hs-hide-all}).
|
|
@item C-c @@ C-M-s
|
|
@itemx C-c @@ C-a
|
|
Show all blocks in the buffer (@code{hs-show-all}).
|
|
@item C-u @var{n} C-c @@ C-l
|
|
Hide all blocks @var{n} levels below this block
|
|
(@code{hs-hide-level}).
|
|
@end table
|
|
|
|
@vindex hs-hide-comments-when-hiding-all
|
|
@vindex hs-isearch-open
|
|
@vindex hs-special-modes-alist
|
|
These variables can be used to customize Hideshow mode:
|
|
|
|
@table @code
|
|
@item hs-hide-comments-when-hiding-all
|
|
If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides
|
|
comments too.
|
|
|
|
@item hs-isearch-open
|
|
This variable specifies the conditions under which incremental search
|
|
should unhide a hidden block when matching text occurs within the
|
|
block. Its value should be either @code{code} (unhide only code
|
|
blocks), @code{comment} (unhide only comments), @code{t} (unhide both
|
|
code blocks and comments), or @code{nil} (unhide neither code blocks
|
|
nor comments). The default value is @code{code}.
|
|
@end table
|
|
|
|
@node Symbol Completion
|
|
@section Completion for Symbol Names
|
|
@cindex completion (symbol names)
|
|
|
|
Completion is normally done in the minibuffer (@pxref{Completion}),
|
|
but you can also complete symbol names in ordinary Emacs buffers.
|
|
|
|
@cindex tags-based completion
|
|
@kindex M-TAB
|
|
@kindex C-M-i
|
|
@findex completion-at-point@r{, in programming language modes}
|
|
@cindex Lisp symbol completion
|
|
@cindex completion (Lisp symbols)
|
|
In most programming language modes, @kbd{C-M-i} (or
|
|
@kbd{M-@key{TAB}}@footnote{
|
|
On graphical displays, the @kbd{M-@key{TAB}} key is usually reserved
|
|
by the window manager for switching graphical windows, so you should
|
|
type @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} instead.
|
|
}) invokes the command @code{completion-at-point}, which generates the
|
|
list of possible completions for the symbol at point. This command
|
|
uses the available support facilities to come up with the completion
|
|
candidates:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If Eglot is activated for the current buffer's project
|
|
(@pxref{Projects}) and the current buffer's major mode, the command
|
|
tries to use the corresponding language server for producing the list
|
|
of completion candidates. @xref{Eglot Features,,, eglot, Eglot: The
|
|
Emacs LSP Client}.
|
|
|
|
@item
|
|
If Semantic mode is enabled (@pxref{Semantic}), the command tries to
|
|
use the Semantic parser data for completion.
|
|
|
|
@item
|
|
If Semantic mode is not enabled or fails at performing completion, the
|
|
command tries to complete using the selected tags table (@pxref{Tags
|
|
Tables}); you need to visit the tags table with @w{@kbd{M-x
|
|
visit-tags-table}} for that to work.
|
|
|
|
@item
|
|
In Emacs Lisp mode, the command performs completion using the
|
|
function, variable, or property names defined in the current Emacs
|
|
session.
|
|
@end itemize
|
|
|
|
In all other respects, in-buffer symbol completion behaves like
|
|
minibuffer completion. For instance, if Emacs cannot complete to
|
|
a unique symbol, it displays a list of completion alternatives in
|
|
another window. Then you can use the keys @kbd{M-@key{DOWN}} and
|
|
@kbd{M-@key{UP}} to navigate through the completions displayed
|
|
in the completions buffer without leaving the original buffer,
|
|
and the key @kbd{M-@key{RET}} to insert the currently highlighted
|
|
completion to the buffer. @xref{Completion}.
|
|
|
|
In Text mode and related modes, @kbd{M-@key{TAB}} completes words
|
|
based on the spell-checker's dictionary. @xref{Spelling}.
|
|
|
|
@cindex completion preview
|
|
@cindex preview completion
|
|
@cindex suggestion preview
|
|
@cindex Completion Preview mode
|
|
@findex completion-preview-mode
|
|
@findex global-completion-preview-mode
|
|
Completion Preview mode is a minor mode that shows completion
|
|
suggestions as you type. You can enable it for the current buffer with
|
|
@kbd{M-x completion-preview-mode}, or globally with @w{@kbd{M-x
|
|
global-completion-preview-mode}}. When Completion Preview mode is on,
|
|
Emacs automatically displays the suggested completion for text around
|
|
point as an in-line preview right after point; type @key{TAB} to accept
|
|
the suggestion.
|
|
|
|
@node MixedCase Words
|
|
@section MixedCase Words
|
|
@cindex camel case
|
|
|
|
Some programming styles make use of mixed-case (or ``CamelCase'')
|
|
symbols like @samp{unReadableSymbol}. (In the GNU project, we recommend
|
|
using underscores to separate words within an identifier, rather than
|
|
using case distinctions.) Emacs has various features to make it easier
|
|
to deal with such symbols.
|
|
|
|
@cindex Glasses mode
|
|
@cindex mode, Glasses
|
|
Glasses mode is a buffer-local minor mode that makes it easier to read
|
|
such symbols, by altering how they are displayed. By default, it
|
|
displays extra underscores between each lower-case letter and the
|
|
following capital letter. This does not alter the buffer text, only how
|
|
it is displayed.
|
|
|
|
To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor
|
|
Modes}). When Glasses mode is enabled, the minor mode indicator
|
|
@samp{o^o} appears in the mode line. For more information about
|
|
Glasses mode, type @kbd{C-h P glasses @key{RET}}.
|
|
|
|
@cindex Subword mode
|
|
@findex subword-mode
|
|
Subword mode is another buffer-local minor mode. In subword mode,
|
|
Emacs's word commands recognize upper case letters in
|
|
@samp{StudlyCapsIdentifiers} as word boundaries. When Subword mode is
|
|
enabled, the minor mode indicator @samp{,} appears in the mode line.
|
|
See also the similar @code{superword-mode} (@pxref{Misc for Programs}).
|
|
|
|
@node Semantic
|
|
@section Semantic
|
|
@cindex Semantic package
|
|
|
|
Semantic is a package that provides language-aware editing commands
|
|
based on @code{source code parsers}. This section provides a brief
|
|
description of Semantic; for full details,
|
|
@ifnottex
|
|
see @ref{Top, Semantic,, semantic, Semantic}.
|
|
@end ifnottex
|
|
@iftex
|
|
see the Semantic Info manual, which is distributed with Emacs.
|
|
@end iftex
|
|
|
|
Most of the language-aware features in Emacs, such as Font Lock
|
|
mode (@pxref{Font Lock}), rely on rules of thumb@footnote{Regular
|
|
expressions and syntax tables.} that usually give good results but are
|
|
never completely exact. In contrast, the parsers used by Semantic
|
|
have an exact understanding of programming language syntax. This
|
|
allows Semantic to provide search, navigation, and completion commands
|
|
that are powerful and precise.
|
|
|
|
@cindex Semantic mode
|
|
@cindex mode, Semantic
|
|
To begin using Semantic, type @kbd{M-x semantic-mode} or click on
|
|
the menu item named @samp{Source Code Parsers (Semantic)} in the
|
|
@samp{Tools} menu. This enables Semantic mode, a global minor mode.
|
|
|
|
When Semantic mode is enabled, Emacs automatically attempts to
|
|
parse each file you visit. Currently, Semantic understands C, C++,
|
|
HTML, Java, Javascript, Make, Python, Scheme, SRecode, and Texinfo.
|
|
Within each parsed buffer, the following commands are available:
|
|
|
|
@table @kbd
|
|
@item C-c , j
|
|
@kindex C-c , j
|
|
Prompt for the name of a function defined in the current file, and
|
|
move point there (@code{semantic-complete-jump-local}).
|
|
|
|
@item C-c , J
|
|
@kindex C-c , J
|
|
Prompt for the name of a function defined in any file Emacs has
|
|
parsed, and move point there (@code{semantic-complete-jump}).
|
|
|
|
@item C-c , @key{SPC}
|
|
@kindex C-c , SPC
|
|
Display a list of possible completions for the symbol at point
|
|
(@code{semantic-complete-analyze-inline}). This also activates a set
|
|
of special key bindings for choosing a completion: @kbd{@key{RET}}
|
|
accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through
|
|
possible completions, @kbd{@key{TAB}} completes as far as possible and
|
|
then cycles, and @kbd{C-g} or any other key aborts completion.
|
|
|
|
@item C-c , l
|
|
@kindex C-c , l
|
|
Display a list of the possible completions of the symbol at point, in
|
|
another window (@code{semantic-analyze-possible-completions}).
|
|
@end table
|
|
|
|
@noindent
|
|
In addition to the above commands, the Semantic package provides a
|
|
variety of other ways to make use of parser information. For
|
|
instance, you can use it to display a list of completions when Emacs
|
|
is idle.
|
|
@ifnottex
|
|
@xref{Top, Semantic,, semantic, Semantic}, for details.
|
|
@end ifnottex
|
|
|
|
@node Misc for Programs
|
|
@section Other Features Useful for Editing Programs
|
|
|
|
Some Emacs commands that aren't designed specifically for editing
|
|
programs are useful for that nonetheless.
|
|
|
|
The Emacs commands that operate on words, sentences and paragraphs
|
|
are useful for editing code. Most symbol names contain words
|
|
(@pxref{Words}), while sentences can be found in strings and comments
|
|
(@pxref{Sentences}). As for paragraphs, they are defined in most
|
|
programming language modes to begin and end at blank lines
|
|
(@pxref{Paragraphs}). Therefore, judicious use of blank lines to make
|
|
the program clearer will also provide useful chunks of text for the
|
|
paragraph commands to work on. Auto Fill mode, if enabled in a
|
|
programming language major mode, indents the new lines which it
|
|
creates.
|
|
|
|
@findex superword-mode
|
|
Superword mode is a buffer-local minor mode that causes editing and
|
|
motion commands to treat symbols (e.g., @samp{this_is_a_symbol}) as words.
|
|
When Superword mode is enabled, the minor mode indicator
|
|
@iftex
|
|
@samp{@math{^2}}
|
|
@end iftex
|
|
@ifnottex
|
|
@samp{²}
|
|
@end ifnottex
|
|
appears in the mode line. See also the similar @code{subword-mode}
|
|
(@pxref{MixedCase Words}).
|
|
|
|
@findex electric-layout-mode
|
|
Electric Layout mode (@kbd{M-x electric-layout-mode}) is a global
|
|
minor mode that automatically inserts newlines when you type certain
|
|
characters; for example, @samp{@{}, @samp{@}} and @samp{;} in Javascript
|
|
mode.
|
|
|
|
Apart from Hideshow mode (@pxref{Hideshow}), another way to
|
|
selectively display parts of a program is to use the selective display
|
|
feature (@pxref{Selective Display}). Programming modes often also
|
|
support Outline minor mode (@pxref{Outline Mode}), which can be used
|
|
with the Foldout package (@pxref{Foldout}).
|
|
|
|
@ifinfo
|
|
The automatic typing features may be useful for writing programs.
|
|
@xref{Top,,Autotyping, autotype, Autotyping}.
|
|
@end ifinfo
|
|
|
|
@findex prettify-symbols-mode
|
|
Prettify Symbols mode is a buffer-local minor mode that replaces
|
|
certain strings with more attractive versions for display purposes.
|
|
For example, in Emacs Lisp mode, it replaces the string @samp{lambda}
|
|
with the Greek lambda character @samp{λ}. In a @TeX{} buffer, it will
|
|
replace @samp{\alpha} @dots{} @samp{\omega} and other math macros with
|
|
their Unicode characters. You may wish to use this in non-programming
|
|
modes as well. You can customize the mode by adding more entries to
|
|
@code{prettify-symbols-alist}. More elaborate customization is
|
|
available via customizing @code{prettify-symbols-compose-predicate} if
|
|
its default value @code{prettify-symbols-default-compose-p} is not
|
|
appropriate. There is also a global version,
|
|
@code{global-prettify-symbols-mode}, which enables the mode in all
|
|
buffers that support it.
|
|
|
|
The symbol at point can be shown in its original form. This is
|
|
controlled by the variable @code{prettify-symbols-unprettify-at-point}:
|
|
if non-@code{nil}, the original form of symbol at point will be
|
|
restored for as long as point is at it.
|
|
|
|
|
|
@node C Modes
|
|
@section C and Related Modes
|
|
@cindex C mode
|
|
@cindex Java mode
|
|
@cindex Pike mode
|
|
@cindex IDL mode
|
|
@cindex CORBA IDL mode
|
|
@cindex Objective C mode
|
|
@cindex C++ mode
|
|
@cindex AWK mode
|
|
@cindex mode, Java
|
|
@cindex mode, C
|
|
@cindex mode, C++
|
|
@cindex mode, Objective C
|
|
@cindex mode, CORBA IDL
|
|
@cindex mode, Pike
|
|
@cindex mode, AWK
|
|
|
|
This section gives a brief description of the special features
|
|
available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
|
|
(These are called ``C mode and related modes''.)
|
|
@ifinfo
|
|
@xref{Top,, CC Mode, ccmode, CC Mode}, for more details.
|
|
@end ifinfo
|
|
@ifnotinfo
|
|
For more details, see the CC mode Info manual, which is distributed
|
|
with Emacs.
|
|
@end ifnotinfo
|
|
|
|
@menu
|
|
* Motion in C:: Commands to move by C statements, etc.
|
|
* Electric C:: Colon and other chars can automatically reindent.
|
|
* Hungry Delete:: A more powerful DEL command.
|
|
* Other C Commands:: Filling comments, viewing expansion of macros,
|
|
and other neat features.
|
|
@end menu
|
|
|
|
@node Motion in C
|
|
@subsection C Mode Motion Commands
|
|
|
|
This section describes commands for moving point, in C mode and
|
|
related modes.
|
|
|
|
@table @code
|
|
@item C-M-a
|
|
@itemx C-M-e
|
|
@findex c-beginning-of-defun
|
|
@findex c-end-of-defun
|
|
Move point to the beginning or end of the current function or
|
|
top-level definition. In languages with enclosing scopes (such as
|
|
C++'s classes) the @dfn{current function} is the immediate one,
|
|
possibly inside a scope. Otherwise it is the one defined by the least
|
|
enclosing braces. (By contrast, @code{beginning-of-defun} and
|
|
@code{end-of-defun} search for braces in column zero.) @xref{Moving
|
|
by Defuns}.
|
|
|
|
@item C-c C-u
|
|
@kindex C-c C-u @r{(C mode)}
|
|
@findex c-up-conditional
|
|
Move point back to the containing preprocessor conditional, leaving the
|
|
mark behind. A prefix argument acts as a repeat count. With a negative
|
|
argument, move point forward to the end of the containing
|
|
preprocessor conditional.
|
|
|
|
@samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so
|
|
the function will stop at a @samp{#elif} when going backward, but not
|
|
when going forward.
|
|
|
|
@item C-c C-p
|
|
@kindex C-c C-p @r{(C mode)}
|
|
@findex c-backward-conditional
|
|
Move point back over a preprocessor conditional, leaving the mark
|
|
behind. A prefix argument acts as a repeat count. With a negative
|
|
argument, move forward.
|
|
|
|
@item C-c C-n
|
|
@kindex C-c C-n @r{(C mode)}
|
|
@findex c-forward-conditional
|
|
Move point forward across a preprocessor conditional, leaving the mark
|
|
behind. A prefix argument acts as a repeat count. With a negative
|
|
argument, move backward.
|
|
|
|
@item M-a
|
|
@kindex M-a @r{(C mode)}
|
|
@findex c-beginning-of-statement
|
|
Move point to the beginning of the innermost C statement
|
|
(@code{c-beginning-of-statement}). If point is already at the beginning
|
|
of a statement, move to the beginning of the preceding statement. With
|
|
prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
|
|
|
|
In comments or in strings which span more than one line, this command
|
|
moves by sentences instead of statements.
|
|
|
|
@item M-e
|
|
@kindex M-e @r{(C mode)}
|
|
@findex c-end-of-statement
|
|
Move point to the end of the innermost C statement or sentence; like
|
|
@kbd{M-a} except that it moves in the other direction
|
|
(@code{c-end-of-statement}).
|
|
@end table
|
|
|
|
@node Electric C
|
|
@subsection Electric C Characters
|
|
|
|
In C mode and related modes, certain printing characters are
|
|
@dfn{electric}---in addition to inserting themselves, they also
|
|
reindent the current line, and optionally also insert newlines. The
|
|
electric characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#},
|
|
@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and
|
|
@kbd{)}.
|
|
|
|
You might find electric indentation inconvenient if you are editing
|
|
chaotically indented code. If you are new to CC Mode, you might find
|
|
it disconcerting. You can toggle electric action with the command
|
|
@kbd{C-c C-l}; when it is enabled, @samp{/@var{c}l} appears in the
|
|
mode line after the mode name (where @var{c}, if present, is @samp{*}
|
|
or @samp{/}, depending on whether the comment style is block or line).
|
|
@xref{Minor Modes,,, ccmode, The CC Mode Manual}, for more about
|
|
mode-line indicators in CC Mode.
|
|
|
|
@table @kbd
|
|
@item C-c C-l
|
|
@kindex C-c C-l @r{(C mode)}
|
|
@findex c-toggle-electric-state
|
|
Toggle electric action (@code{c-toggle-electric-state}). With a
|
|
positive prefix argument, this command enables electric action, with a
|
|
negative one it disables it.
|
|
@end table
|
|
|
|
Electric characters insert newlines only when, in addition to the
|
|
electric state, the @dfn{auto-newline} feature is enabled (indicated
|
|
by @samp{/@var{c}la} in the mode line after the mode name). You can
|
|
turn this feature on or off with the command @kbd{C-c C-a}:
|
|
|
|
@table @kbd
|
|
@item C-c C-a
|
|
@kindex C-c C-a @r{(C mode)}
|
|
@findex c-toggle-auto-newline
|
|
Toggle the auto-newline feature (@code{c-toggle-auto-newline}). With a
|
|
prefix argument, this command turns the auto-newline feature on if the
|
|
argument is positive, and off if it is negative.
|
|
@end table
|
|
|
|
Usually the CC Mode style configures the exact circumstances in
|
|
which Emacs inserts auto-newlines. You can also configure this
|
|
directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}.
|
|
|
|
@node Hungry Delete
|
|
@subsection Hungry Delete Feature in C
|
|
@cindex hungry deletion (C Mode)
|
|
|
|
If you want to delete an entire block of whitespace at point, you
|
|
can use @dfn{hungry deletion}. This deletes all the contiguous
|
|
whitespace either before point or after point in a single operation.
|
|
@dfn{Whitespace} here includes tabs and newlines, but not comments or
|
|
preprocessor commands.
|
|
|
|
@table @kbd
|
|
@item C-c C-@key{DEL}
|
|
@itemx C-c @key{DEL}
|
|
@findex c-hungry-delete-backwards
|
|
@kindex C-c C-DEL @r{(C Mode)}
|
|
@kindex C-c DEL @r{(C Mode)}
|
|
Delete the entire block of whitespace preceding point (@code{c-hungry-delete-backwards}).
|
|
|
|
@item C-c C-d
|
|
@itemx C-c C-@key{Delete}
|
|
@itemx C-c @key{Delete}
|
|
@findex c-hungry-delete-forward
|
|
@kindex C-c C-d @r{(C Mode)}
|
|
@kindex C-c C-Delete @r{(C Mode)}
|
|
@kindex C-c Delete @r{(C Mode)}
|
|
Delete the entire block of whitespace after point (@code{c-hungry-delete-forward}).
|
|
@end table
|
|
|
|
As an alternative to the above commands, you can enable @dfn{hungry
|
|
delete mode}. When this feature is enabled (indicated by @samp{h}
|
|
after a @samp{/} in the mode line after the mode name), a single
|
|
@kbd{@key{DEL}} deletes all preceding whitespace, not just one space,
|
|
and a single @kbd{C-d} (but @emph{not} plain @kbd{@key{Delete}})
|
|
deletes all following whitespace.
|
|
|
|
@table @kbd
|
|
@item M-x c-toggle-hungry-state
|
|
@findex c-toggle-hungry-state
|
|
Toggle the hungry-delete feature
|
|
(@code{c-toggle-hungry-state}). With a prefix argument,
|
|
this command turns the hungry-delete feature on if the argument is
|
|
positive, and off if it is negative.
|
|
@end table
|
|
|
|
@vindex c-hungry-delete-key
|
|
The variable @code{c-hungry-delete-key} controls whether the
|
|
hungry-delete feature is enabled.
|
|
|
|
@node Other C Commands
|
|
@subsection Other Commands for C Mode
|
|
|
|
@table @kbd
|
|
@item M-x c-context-line-break
|
|
@findex c-context-line-break
|
|
This command inserts a line break and indents the new line in a manner
|
|
appropriate to the context. In normal code, it does the work of
|
|
@kbd{@key{RET}} (@code{newline}), in a C preprocessor line it additionally
|
|
inserts a @samp{\} at the line break, and within comments it's like
|
|
@kbd{M-j} (@code{c-indent-new-comment-line}).
|
|
|
|
@code{c-context-line-break} isn't bound to a key by default, but it
|
|
needs a binding to be useful. The following code will bind it to
|
|
@kbd{@key{RET}}. We use @code{c-initialization-hook} here to make
|
|
sure the keymap is loaded before we try to change it.
|
|
|
|
@example
|
|
(defun my-bind-clb ()
|
|
(keymap-set c-mode-base-map "RET"
|
|
'c-context-line-break))
|
|
(add-hook 'c-initialization-hook 'my-bind-clb)
|
|
@end example
|
|
|
|
@item C-M-h
|
|
Put mark at the end of a function definition, and put point at the
|
|
beginning (@code{c-mark-function}).
|
|
|
|
@item M-q
|
|
@kindex M-q @r{(C mode)}
|
|
@findex c-fill-paragraph
|
|
Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
|
|
If any part of the current line is a comment or within a comment, this
|
|
command fills the comment or the paragraph of it that point is in,
|
|
preserving the comment indentation and comment delimiters.
|
|
|
|
@item C-c C-e
|
|
@cindex macro expansion in C
|
|
@cindex expansion of C macros
|
|
@findex c-macro-expand
|
|
@kindex C-c C-e @r{(C mode)}
|
|
Run the C preprocessor on the text in the region, and show the result,
|
|
which includes the expansion of all the macro calls
|
|
(@code{c-macro-expand}). The buffer text before the region is also
|
|
included in preprocessing, for the sake of macros defined there, but the
|
|
output from this part isn't shown.
|
|
|
|
When you are debugging C code that uses macros, sometimes it is hard to
|
|
figure out precisely how the macros expand. With this command, you
|
|
don't have to figure it out; you can see the expansions.
|
|
|
|
@item C-c C-\
|
|
@findex c-backslash-region
|
|
@kindex C-c C-\ @r{(C mode)}
|
|
Insert or align @samp{\} characters at the ends of the lines of the
|
|
region (@code{c-backslash-region}). This is useful after writing or
|
|
editing a C macro definition.
|
|
|
|
If a line already ends in @samp{\}, this command adjusts the amount of
|
|
whitespace before it. Otherwise, it inserts a new @samp{\}. However,
|
|
the last line in the region is treated specially; no @samp{\} is
|
|
inserted on that line, and any @samp{\} there is deleted.
|
|
|
|
@item M-x cpp-highlight-buffer
|
|
@cindex preprocessor highlighting
|
|
@findex cpp-highlight-buffer
|
|
Highlight parts of the text according to its preprocessor conditionals.
|
|
This command displays another buffer named @file{*CPP Edit*}, which
|
|
serves as a graphic menu for selecting how to display particular kinds
|
|
of conditionals and their contents. After changing various settings,
|
|
click on @samp{[A]pply these settings} (or go to that buffer and type
|
|
@kbd{a}) to rehighlight the C mode buffer accordingly.
|
|
|
|
@item C-c C-s
|
|
@findex c-show-syntactic-information
|
|
@kindex C-c C-s @r{(C mode)}
|
|
Display the syntactic information about the current source line
|
|
(@code{c-show-syntactic-information}). This information directs how
|
|
the line is indented.
|
|
|
|
@item M-x cwarn-mode
|
|
@itemx M-x global-cwarn-mode
|
|
@findex cwarn-mode
|
|
@findex global-cwarn-mode
|
|
@vindex global-cwarn-mode
|
|
@cindex CWarn mode
|
|
@cindex suspicious constructions in C, C++
|
|
CWarn minor mode highlights certain suspicious C and C++ constructions:
|
|
|
|
@itemize @bullet{}
|
|
@item
|
|
Assignments inside expressions.
|
|
@item
|
|
Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
|
|
(except after a @samp{do @dots{} while} statement);
|
|
@item
|
|
C++ functions with reference parameters.
|
|
@end itemize
|
|
|
|
@noindent
|
|
You can enable the mode for one buffer with the command @kbd{M-x
|
|
cwarn-mode}, or for all suitable buffers with the command @kbd{M-x
|
|
global-cwarn-mode} or by customizing the variable
|
|
@code{global-cwarn-mode}. You must also enable Font Lock mode to make
|
|
it work.
|
|
|
|
@item M-x hide-ifdef-mode
|
|
@findex hide-ifdef-mode
|
|
@cindex Hide-ifdef mode
|
|
@vindex hide-ifdef-shadow
|
|
Hide-ifdef minor mode hides selected code within @samp{#if} and
|
|
@samp{#ifdef} preprocessor blocks. If you change the variable
|
|
@code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode
|
|
shadows preprocessor blocks by displaying them with a less
|
|
prominent face, instead of hiding them entirely. See the
|
|
documentation string of @code{hide-ifdef-mode} for more information.
|
|
|
|
@item M-x ff-find-related-file
|
|
@cindex related files
|
|
@findex ff-find-related-file
|
|
@vindex ff-related-file-alist
|
|
Find a file related in a special way to the file visited by the
|
|
current buffer. Typically this will be the header file corresponding
|
|
to a C/C++ source file, or vice versa. The variable
|
|
@code{ff-related-file-alist} specifies how to compute related file
|
|
names.
|
|
@end table
|
|
|
|
@node Asm Mode
|
|
@section Asm Mode
|
|
|
|
@cindex Asm mode
|
|
@cindex assembler mode
|
|
Asm mode is a major mode for editing files of assembler code. It
|
|
defines these commands:
|
|
|
|
@table @kbd
|
|
@item @key{TAB}
|
|
@code{tab-to-tab-stop}.
|
|
@c FIXME: Maybe this should be consistent with other programming modes.
|
|
|
|
@item C-j
|
|
Insert a newline and then indent using @code{tab-to-tab-stop}.
|
|
|
|
@item :
|
|
Insert a colon and then remove the indentation from before the label
|
|
preceding colon. Then do @code{tab-to-tab-stop}.
|
|
|
|
@item ;
|
|
Insert or align a comment.
|
|
@end table
|
|
|
|
The variable @code{asm-comment-char} specifies which character
|
|
starts comments in assembler syntax.
|
|
|
|
@ifnottex
|
|
@include fortran-xtra.texi
|
|
@end ifnottex
|