@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#, Elixir, Fortran, Icon, IDL (CORBA), HEEx, IDLWAVE, Java, Javascript, Lua, M4, Makefiles, Metafont (@TeX{}'s companion for font creation), Modula2, Object Pascal, Objective-C, Octave, Pascal, Perl, PHP, Pike, PostScript, Prolog, Python, Ruby, Simula, SQL, Tcl, TypeScript, Verilog, and VHDL@. The recommended 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. If you provide a prefix argument when inserting a delimiter, the numeric value of that prefix argument specifies the number of pairs to insert. 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-call} 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