0001: @c -*- coding: utf-8 -*-
0002: @c This is part of the Emacs manual.
0003: @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2019 Free Software
0004: @c Foundation, Inc.
0005: @c See file emacs.texi for copying conditions.
0006: @node Programs
0007: @chapter Editing Programs
0008: @cindex Lisp editing
0009: @cindex C editing
0010: @cindex program editing
0011: 
0012:   This chapter describes Emacs features for facilitating editing
0013: programs.  Some of the things these features can do are:
0014: 
0015: @itemize @bullet
0016: @item
0017: Find or move over top-level definitions (@pxref{Defuns}).
0018: @item
0019: Apply the usual indentation conventions of the language
0020: (@pxref{Program Indent}).
0021: @item
0022: Balance parentheses (@pxref{Parentheses}).
0023: @item
0024: Insert, kill or align comments (@pxref{Comments}).
0025: @item
0026: Highlight program syntax (@pxref{Font Lock}).
0027: @end itemize
0028: 
0029: @menu
0030: * Program Modes::       Major modes for editing programs.
0031: * Defuns::              Commands to operate on major top-level parts
0032:                           of a program.
0033: * Program Indent::      Adjusting indentation to show the nesting.
0034: * Parentheses::         Commands that operate on parentheses.
0035: * Comments::            Inserting, killing, and aligning comments.
0036: * Documentation::       Getting documentation of functions you plan to call.
0037: * Hideshow::            Displaying blocks selectively.
0038: * Symbol Completion::   Completion on symbol names of your program or language.
0039: * MixedCase Words::     Dealing with identifiersLikeThis.
0040: * Semantic::            Suite of editing tools based on source code parsing.
0041: * Misc for Programs::   Other Emacs features useful for editing programs.
0042: * C Modes::             Special commands of C, C++, Objective-C, Java,
0043:                           IDL, Pike and AWK modes.
0044: * Asm Mode::            Asm mode and its special features.
0045: @ifnottex
0046: * Fortran::             Fortran mode and its special features.
0047: @end ifnottex
0048: @end menu
0049: 
0050: @node Program Modes
0051: @section Major Modes for Programming Languages
0052: @cindex modes for programming languages
0053: 
0054:   Emacs has specialized major modes (@pxref{Major Modes}) for many
0055: programming languages.  A programming language mode typically
0056: specifies the syntax of expressions, the customary rules for
0057: indentation, how to do syntax highlighting for the language, and how
0058: to find the beginning or end of a function definition.  It often has
0059: features for compiling and debugging programs as well.  The major mode
0060: for each language is named after the language; for instance, the major
0061: mode for the C programming language is @code{c-mode}.
0062: 
0063: @cindex Perl mode
0064: @cindex Icon mode
0065: @cindex Makefile mode
0066: @cindex Tcl mode
0067: @cindex CPerl mode
0068: @cindex DSSSL mode
0069: @cindex Octave mode
0070: @cindex Metafont mode
0071: @cindex Modula2 mode
0072: @cindex Prolog mode
0073: @cindex Python mode
0074: @cindex Ruby mode
0075: @cindex Simula mode
0076: @cindex Verilog mode
0077: @cindex VHDL mode
0078: @cindex M4 mode
0079: @cindex Shell-script mode
0080: @cindex OPascal mode
0081: @cindex PostScript mode
0082: @cindex Conf mode
0083: @cindex DNS mode
0084: @cindex Javascript mode
0085: @cindex Awk mode
0086:   Emacs has programming language modes for Lisp, Scheme, the
0087: Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++,
0088: Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, M4, Makefiles,
0089: Metafont (@TeX{}'s companion for font creation), Modula2, Object
0090: Pascal, Objective-C, Octave, Pascal, Perl, Pike, PostScript, Prolog,
0091: Python, Ruby, Simula, SQL, Tcl, Verilog, and VHDL@.  An alternative
0092: mode for Perl is called CPerl mode.  Modes are also available for the
0093: scripting languages of the common GNU and Unix shells, and
0094: MS-DOS/MS-Windows @samp{BAT} files, and for makefiles, DNS master
0095: files, and various sorts of configuration files.
0096: 
0097:   Ideally, Emacs should have a major mode for each programming
0098: language that you might want to edit.  If it doesn't have a mode for
0099: your favorite language, the mode might be implemented in a package not
0100: distributed with Emacs (@pxref{Packages}); or you can contribute one.
0101: 
0102: @kindex DEL @r{(programming modes)}
0103: @findex backward-delete-char-untabify
0104:   In most programming languages, indentation should vary from line to
0105: line to illustrate the structure of the program.  Therefore, in most
0106: programming language modes, typing @kbd{@key{TAB}} updates the
0107: indentation of the current line (@pxref{Program Indent}).
0108: Furthermore, @kbd{@key{DEL}} is usually bound to
0109: @code{backward-delete-char-untabify}, which deletes backward treating
0110: each tab as if it were the equivalent number of spaces, so that you
0111: can delete one column of indentation without worrying whether the
0112: whitespace consists of spaces or tabs.
0113: 
0114: @cindex mode hook, and major modes
0115: @vindex c-mode-hook
0116: @vindex lisp-mode-hook
0117: @vindex emacs-lisp-mode-hook
0118: @vindex lisp-interaction-mode-hook
0119: @vindex scheme-mode-hook
0120:   Entering a programming language mode runs the custom Lisp functions
0121: specified in the hook variable @code{prog-mode-hook}, followed by
0122: those specified in the mode's own mode hook (@pxref{Major Modes}).
0123: For instance, entering C mode runs the hooks @code{prog-mode-hook} and
0124: @code{c-mode-hook}.  @xref{Hooks}, for information about hooks.
0125: 
0126: @ifnottex
0127:   Separate manuals are available for the modes for Ada (@pxref{Top,,
0128: Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba
0129: IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), Octave, VHDL,
0130: and IDLWAVE (@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}).
0131: @end ifnottex
0132: @iftex
0133:   The Emacs distribution contains Info manuals for the major modes for
0134: Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, Octave, VHDL, and
0135: IDLWAVE@.  For Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized
0136: Emacs Features}.
0137: @end iftex
0138: 
0139: @node Defuns
0140: @section Top-Level Definitions, or Defuns
0141: 
0142:   In Emacs, a major definition at the top level in the buffer, such as
0143: a function, is called a @dfn{defun}.  The name comes from Lisp, but in
0144: Emacs we use it for all languages.
0145: 
0146: @menu
0147: * Left Margin Paren::   An open-paren or similar opening delimiter
0148:                           starts a defun if it is at the left margin.
0149: * Moving by Defuns::    Commands to move over or mark a major definition.
0150: * Imenu::               Making buffer indexes as menus.
0151: * Which Function::      Which Function mode shows which function you are in.
0152: @end menu
0153: 
0154: @node Left Margin Paren
0155: @subsection Left Margin Convention
0156: 
0157: @cindex open-parenthesis in leftmost column
0158: @cindex ( in leftmost column
0159:   Many programming-language modes have traditionally assumed that any
0160: opening parenthesis or brace found at the left margin is the start of
0161: a top-level definition, or defun.  So, by default, commands which seek
0162: the beginning of a defun accept such a delimiter as signifying that
0163: position.
0164: 
0165: @vindex open-paren-in-column-0-is-defun-start
0166:   If you want to override this convention, you can do so by setting
0167: the user option @code{open-paren-in-column-0-is-defun-start} to
0168: @code{nil}.  If this option is set to @code{t} (the default), commands
0169: seeking the start of a defun will stop at opening parentheses or
0170: braces at column zero which aren't in a comment or string.  When it is
0171: @code{nil}, defuns are found by searching for parens or braces at the
0172: outermost level.  Since low-level Emacs routines no longer depend on
0173: this convention, you usually won't need to change
0174: @code{open-paren-in-column-0-is-defun-start} from its default.
0175: 
0176: @node Moving by Defuns
0177: @subsection Moving by Defuns
0178: @cindex defuns
0179: 
0180:   These commands move point or set up the region based on top-level
0181: major definitions, also called @dfn{defuns}.
0182: 
0183: @table @kbd
0184: @item C-M-a
0185: Move to beginning of current or preceding defun
0186: (@code{beginning-of-defun}).
0187: @item C-M-e
0188: Move to end of current or following defun (@code{end-of-defun}).
0189: @item C-M-h
0190: Put region around whole current or following defun (@code{mark-defun}).
0191: @end table
0192: 
0193: @cindex move to beginning or end of function
0194: @cindex function, move to beginning or end
0195: @kindex C-M-a
0196: @kindex C-M-e
0197: @kindex C-M-h
0198: @findex beginning-of-defun
0199: @findex end-of-defun
0200: @findex mark-defun
0201:   The commands to move to the beginning and end of the current defun
0202: are @kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e}
0203: (@code{end-of-defun}).  If you repeat one of these commands, or use a
0204: positive numeric argument, each repetition moves to the next defun in
0205: the direction of motion.
0206: 
0207:   @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward
0208: @var{n} times to the next beginning of a defun.  This is not exactly
0209: the same place that @kbd{C-M-e} with argument @var{n} would move to;
0210: the end of this defun is not usually exactly the same place as the
0211: beginning of the following defun.  (Whitespace, comments, and perhaps
0212: declarations can separate them.)  Likewise, @kbd{C-M-e} with a
0213: negative argument moves back to an end of a defun, which is not quite
0214: the same as @kbd{C-M-a} with a positive argument.
0215: 
0216: @kindex C-M-h @r{(C mode)}
0217: @findex c-mark-function
0218:   To operate on the current defun, use @kbd{C-M-h}
0219: (@code{mark-defun}), which sets the mark at the end of the current
0220: defun and puts point at its beginning.  @xref{Marking Objects}.  This
0221: is the easiest way to get ready to kill the defun in order to move it
0222: to a different place in the file.  If the defun is directly preceded
0223: by comments (with no intervening blank lines), they are marked, too.
0224: If you use the command while point is between defuns, it uses the
0225: following defun.  If you use the command while the mark is already
0226: active, it extends the end of the region to include one more defun.
0227: With a prefix argument, it marks that many defuns or extends the
0228: region by the appropriate number of defuns.  With negative prefix
0229: argument it marks defuns in the opposite direction and also changes
0230: the direction of selecting for subsequent uses of @code{mark-defun}.
0231: 
0232:   In C mode, @kbd{C-M-h} runs the function @code{c-mark-function},
0233: which is almost the same as @code{mark-defun}; the difference is that
0234: it backs up over the argument declarations, function name and returned
0235: data type so that the entire C function is inside the region.  This is
0236: an example of how major modes adjust the standard key bindings so that
0237: they do their standard jobs in a way better fitting a particular
0238: language.  Other major modes may replace any or all of these key
0239: bindings for that purpose.
0240: 
0241: @node Imenu
0242: @subsection Imenu
0243: @cindex index of buffer definitions
0244: @cindex buffer definitions index
0245: 
0246:   The Imenu facility offers a way to find the major definitions in
0247: a file by name.  It is also useful in text formatter major modes,
0248: where it treats each chapter, section, etc., as a definition.
0249: (@xref{Xref}, for a more powerful feature that handles multiple files
0250: together.)
0251: 
0252: @findex imenu
0253:   If you type @kbd{M-x imenu}, it reads the name of a definition using
0254: the minibuffer, then moves point to that definition.  You can use
0255: completion to specify the name; the command always displays the whole
0256: list of valid names.
0257: 
0258: @findex imenu-add-menubar-index
0259:   Alternatively, you can bind the command @code{imenu} to a mouse
0260: click.  Then it displays mouse menus for you to select a definition
0261: name.  You can also add the buffer's index to the menu bar by calling
0262: @code{imenu-add-menubar-index}.  If you want to have this menu bar
0263: item available for all buffers in a certain major mode, you can do
0264: this by adding @code{imenu-add-menubar-index} to its mode hook.  But
0265: if you have done that, you will have to wait a little while each time
0266: you visit a file in that mode, while Emacs finds all the definitions
0267: in that buffer.
0268: 
0269: @vindex imenu-auto-rescan
0270:   When you change the contents of a buffer, if you add or delete
0271: definitions, you can update the buffer's index based on the
0272: new contents by invoking the @samp{*Rescan*} item in the menu.
0273: Rescanning happens automatically if you set @code{imenu-auto-rescan} to
0274: a non-@code{nil} value.  There is no need to rescan because of small
0275: changes in the text.
0276: 
0277: @vindex imenu-auto-rescan-maxout
0278:   @code{imenu-auto-rescan} will be disabled in buffers that are larger
0279: than @code{imenu-auto-rescan-maxout} in bytes.
0280: 
0281: @vindex imenu-sort-function
0282:   You can customize the way the menus are sorted by setting the
0283: variable @code{imenu-sort-function}.  By default, names are ordered as
0284: they occur in the buffer; if you want alphabetic sorting, use the
0285: symbol @code{imenu--sort-by-name} as the value.  You can also
0286: define your own comparison function by writing Lisp code.
0287: 
0288:   Imenu provides the information to guide Which Function mode
0289: @ifnottex
0290: (@pxref{Which Function}).
0291: @end ifnottex
0292: @iftex
0293: (see below).
0294: @end iftex
0295: The Speedbar can also use it (@pxref{Speedbar}).
0296: 
0297: @node Which Function
0298: @subsection Which Function Mode
0299: @cindex current function name in mode line
0300: 
0301:   Which Function mode is a global minor mode (@pxref{Minor Modes})
0302: which displays the current function name in the mode line, updating it
0303: as you move around in a buffer.
0304: 
0305: @findex which-function-mode
0306: @vindex which-func-modes
0307:   To either enable or disable Which Function mode, use the command
0308: @kbd{M-x which-function-mode}.  Which Function mode is a global minor
0309: mode.  By default, it takes effect in all major modes that
0310: know how to support it (i.e., all the major modes that support
0311: Imenu).  You can restrict it to a specific list of major modes by
0312: changing the value of the variable @code{which-func-modes} from
0313: @code{t} (which means to support all available major modes) to a list
0314: of major mode names.
0315: 
0316: @node Program Indent
0317: @section Indentation for Programs
0318: @cindex indentation for programs
0319: 
0320:   The best way to keep a program properly indented is to use Emacs to
0321: reindent it as you change it.  Emacs has commands to indent either a
0322: single line, a specified number of lines, or all of the lines inside a
0323: single parenthetical grouping.
0324: 
0325:   @xref{Indentation}, for general information about indentation.  This
0326: section describes indentation features specific to programming
0327: language modes.
0328: 
0329: @menu
0330: * Basic Indent::        Indenting a single line.
0331: * Multi-line Indent::   Commands to reindent many lines at once.
0332: * Lisp Indent::         Specifying how each Lisp function should be indented.
0333: * C Indent::            Extra features for indenting C and related modes.
0334: * Custom C Indent::     Controlling indentation style for C and related modes.
0335: @end menu
0336: 
0337: @cindex pretty-printer
0338:   Emacs also provides a Lisp pretty-printer in the @code{pp} package,
0339: which reformats Lisp objects with nice-looking indentation.
0340: @xref{Output Functions, pp,, elisp, The Emacs Lisp Reference Manual}.
0341: 
0342: @node Basic Indent
0343: @subsection Basic Program Indentation Commands
0344: 
0345: @table @kbd
0346: @item @key{TAB}
0347: Adjust indentation of current line (@code{indent-for-tab-command}).
0348: @item @key{RET}
0349: Insert a newline, then adjust indentation of following line
0350: (@code{newline}).
0351: @end table
0352: 
0353: @kindex TAB @r{(programming modes)}
0354: @findex indent-line-function
0355:   The basic indentation command is @kbd{@key{TAB}}
0356: (@code{indent-for-tab-command}), which was documented in
0357: @ref{Indentation}.  In programming language modes, @kbd{@key{TAB}}
0358: indents the current line, based on the indentation and syntactic
0359: content of the preceding lines; if the region is active,
0360: @kbd{@key{TAB}} indents each line within the region, not just the
0361: current line.
0362: 
0363:   The command @kbd{@key{RET}} (@code{newline}), which was documented
0364: in @ref{Inserting Text}, does the same as @kbd{C-j} followed by
0365: @kbd{@key{TAB}}: it inserts a new line, then adjusts the line's
0366: indentation.
0367: 
0368:   When indenting a line that starts within a parenthetical grouping,
0369: Emacs usually places the start of the line under the preceding line
0370: within the group, or under the text after the parenthesis.  If you
0371: manually give one of these lines a nonstandard indentation (e.g., for
0372: aesthetic purposes), the lines below will follow it.
0373: 
0374:   The indentation commands for most programming language modes assume
0375: that an open-parenthesis, open-brace or other opening delimiter at the
0376: left margin is the start of a function.  If the code you are editing
0377: violates this assumption---even if the delimiters occur in strings or
0378: comments---you must set @code{open-paren-in-column-0-is-defun-start}
0379: to @code{nil} for indentation to work properly.  @xref{Left Margin
0380: Paren}.
0381: 
0382: @node Multi-line Indent
0383: @subsection Indenting Several Lines
0384: 
0385:   Sometimes, you may want to reindent several lines of code at a time.
0386: One way to do this is to use the mark; when the mark is active and the
0387: region is non-empty, @kbd{@key{TAB}} indents every line in the region.
0388: Alternatively, the command @kbd{C-M-\} (@code{indent-region}) indents
0389: every line in the region, whether or not the mark is active
0390: (@pxref{Indentation Commands}).
0391: 
0392:   In addition, Emacs provides the following commands for indenting
0393: large chunks of code:
0394: 
0395: @table @kbd
0396: @item C-M-q
0397: Reindent all the lines within one parenthetical grouping.
0398: @item C-u @key{TAB}
0399: Shift an entire parenthetical grouping rigidly sideways so that its
0400: first line is properly indented.
0401: @item M-x indent-code-rigidly
0402: Shift all the lines in the region rigidly sideways, but do not alter
0403: lines that start inside comments and strings.
0404: @end table
0405: 
0406: @kindex C-M-q
0407: @findex indent-pp-sexp
0408:   To reindent the contents of a single parenthetical grouping,
0409: position point before the beginning of the grouping and type
0410: @kbd{C-M-q}.  This changes the relative indentation within the
0411: grouping, without affecting its overall indentation (i.e., the
0412: indentation of the line where the grouping starts).  The function that
0413: @kbd{C-M-q} runs depends on the major mode; it is
0414: @code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode,
0415: etc.  To correct the overall indentation as well, type @kbd{@key{TAB}}
0416: first.
0417: 
0418: @kindex C-u TAB
0419:   If you like the relative indentation within a grouping but not the
0420: indentation of its first line, move point to that first line and type
0421: @kbd{C-u @key{TAB}}.  In Lisp, C, and some other major modes,
0422: @kbd{@key{TAB}} with a numeric argument reindents the current line as
0423: usual, then reindents by the same amount all the lines in the
0424: parenthetical grouping starting on the current line.  It is clever,
0425: though, and does not alter lines that start inside strings.  Neither
0426: does it alter C preprocessor lines when in C mode, but it does
0427: reindent any continuation lines that may be attached to them.
0428: 
0429: @findex indent-code-rigidly
0430:   The command @kbd{M-x indent-code-rigidly} rigidly shifts all the
0431: lines in the region sideways, like @code{indent-rigidly} does
0432: (@pxref{Indentation Commands}).  It doesn't alter the indentation of
0433: lines that start inside a string, unless the region also starts inside
0434: that string.  The prefix arg specifies the number of columns to
0435: indent.
0436: 
0437: @node Lisp Indent
0438: @subsection Customizing Lisp Indentation
0439: @cindex customizing Lisp indentation
0440: 
0441:   The indentation pattern for a Lisp expression can depend on the function
0442: called by the expression.  For each Lisp function, you can choose among
0443: several predefined patterns of indentation, or define an arbitrary one with
0444: a Lisp program.
0445: 
0446:   The standard pattern of indentation is as follows: the second line of the
0447: expression is indented under the first argument, if that is on the same
0448: line as the beginning of the expression; otherwise, the second line is
0449: indented underneath the function name.  Each following line is indented
0450: under the previous line whose nesting depth is the same.
0451: 
0452: @vindex lisp-indent-offset
0453:   If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides
0454: the usual indentation pattern for the second line of an expression, so that
0455: such lines are always indented @code{lisp-indent-offset} more columns than
0456: the containing list.
0457: 
0458: @vindex lisp-body-indent
0459:   Certain functions override the standard pattern.  Functions whose
0460: names start with @code{def} treat the second lines as the start of
0461: a @dfn{body}, by indenting the second line @code{lisp-body-indent}
0462: additional columns beyond the open-parenthesis that starts the
0463: expression.
0464: 
0465: @cindex @code{lisp-indent-function} property
0466:   You can override the standard pattern in various ways for individual
0467: functions, according to the @code{lisp-indent-function} property of
0468: the function name.  This is normally done for macro definitions, using
0469: the @code{declare} construct.  @xref{Defining Macros,,, elisp, The
0470: Emacs Lisp Reference Manual}.
0471: 
0472: @node C Indent
0473: @subsection Commands for C Indentation
0474: 
0475:   Here are special features for indentation in C mode and related modes:
0476: 
0477: @table @kbd
0478: @item C-c C-q
0479: @kindex C-c C-q @r{(C mode)}
0480: @findex c-indent-defun
0481: Reindent the current top-level function definition or aggregate type
0482: declaration (@code{c-indent-defun}).
0483: 
0484: @item C-M-q
0485: @kindex C-M-q @r{(C mode)}
0486: @findex c-indent-exp
0487: Reindent each line in the balanced expression that follows point
0488: (@code{c-indent-exp}).  A prefix argument inhibits warning messages
0489: about invalid syntax.
0490: 
0491: @item @key{TAB}
0492: @findex c-indent-command
0493: Reindent the current line, and/or in some cases insert a tab character
0494: (@code{c-indent-command}).
0495: 
0496: @vindex c-tab-always-indent
0497: If @code{c-tab-always-indent} is @code{t}, this command always reindents
0498: the current line and does nothing else.  This is the default.
0499: 
0500: If that variable is @code{nil}, this command reindents the current line
0501: only if point is at the left margin or in the line's indentation;
0502: otherwise, it inserts a tab (or the equivalent number of spaces,
0503: if @code{indent-tabs-mode} is @code{nil}).
0504: 
0505: Any other value (not @code{nil} or @code{t}) means always reindent the
0506: line, and also insert a tab if within a comment or a string.
0507: @end table
0508: 
0509:   To reindent the whole current buffer, type @kbd{C-x h C-M-\}.  This
0510: first selects the whole buffer as the region, then reindents that
0511: region.
0512: 
0513:   To reindent the current block, use @kbd{C-M-u C-M-q}.  This moves
0514: to the front of the block and then reindents it all.
0515: 
0516: @node Custom C Indent
0517: @subsection Customizing C Indentation
0518: @cindex style (for indentation)
0519: 
0520:   C mode and related modes use a flexible mechanism for customizing
0521: indentation.  C mode indents a source line in two steps: first it
0522: classifies the line syntactically according to its contents and
0523: context; second, it determines the indentation offset associated by
0524: your selected @dfn{style} with the syntactic construct and adds this
0525: onto the indentation of the @dfn{anchor statement}.
0526: 
0527: @table @kbd
0528: @item C-c . @var{style} @key{RET}
0529: Select a predefined style @var{style} (@code{c-set-style}).
0530: @end table
0531: 
0532:   A @dfn{style} is a named collection of customizations that can be
0533: used in C mode and the related modes.  @ref{Styles,,, ccmode, The CC
0534: Mode Manual}, for a complete description.  Emacs comes with several
0535: predefined styles, including @code{gnu}, @code{k&r}, @code{bsd},
0536: @code{stroustrup}, @code{linux}, @code{python}, @code{java},
0537: @code{whitesmith}, @code{ellemtel}, and @code{awk}.  Some of these
0538: styles are primarily intended for one language, but any of them can be
0539: used with any of the languages supported by these modes.  To find out
0540: what a style looks like, select it and reindent some code, e.g., by
0541: typing @kbd{C-M-q} at the start of a function definition.
0542: 
0543: @kindex C-c . @r{(C mode)}
0544: @findex c-set-style
0545:   To choose a style for the current buffer, use the command @w{@kbd{C-c
0546: .}}.  Specify a style name as an argument (case is not significant).
0547: This command affects the current buffer only, and it affects only
0548: future invocations of the indentation commands; it does not reindent
0549: the code already in the buffer.  To reindent the whole buffer in the
0550: new style, you can type @kbd{C-x h C-M-\}.
0551: 
0552: @vindex c-default-style
0553:   You can also set the variable @code{c-default-style} to specify the
0554: default style for various major modes.  Its value should be either the
0555: style's name (a string) or an alist, in which each element specifies
0556: one major mode and which indentation style to use for it.  For
0557: example,
0558: 
0559: @example
0560: (setq c-default-style
0561:       '((java-mode . "java")
0562:         (awk-mode . "awk")
0563:         (other . "gnu")))
0564: @end example
0565: 
0566: @noindent
0567: specifies explicit choices for Java and AWK modes, and the default
0568: @samp{gnu} style for the other C-like modes.  (These settings are
0569: actually the defaults.)  This variable takes effect when you select
0570: one of the C-like major modes; thus, if you specify a new default
0571: style for Java mode, you can make it take effect in an existing Java
0572: mode buffer by typing @kbd{M-x java-mode} there.
0573: 
0574:   The @code{gnu} style specifies the formatting recommended by the GNU
0575: Project for C; it is the default, so as to encourage use of our
0576: recommended style.
0577: 
0578:   @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and
0579: @ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more
0580: information on customizing indentation for C and related modes,
0581: including how to override parts of an existing style and how to define
0582: your own styles.
0583: 
0584: @findex c-guess
0585: @findex c-guess-install
0586:   As an alternative to specifying a style, you can tell Emacs to guess
0587: a style by typing @kbd{M-x c-guess} in a sample code buffer.  You can
0588: then apply the guessed style to other buffers with @kbd{M-x
0589: c-guess-install}.  @xref{Guessing the Style,,, ccmode, the CC Mode
0590: Manual}, for details.
0591: 
0592: @node Parentheses
0593: @section Commands for Editing with Parentheses
0594: 
0595: @findex check-parens
0596: @cindex unbalanced parentheses and quotes
0597:   This section describes the commands and features that take advantage
0598: of the parenthesis structure in a program, or help you keep it
0599: balanced.
0600: 
0601:   When talking about these facilities, the term ``parenthesis'' also
0602: includes braces, brackets, or whatever delimiters are defined to match
0603: in pairs.  The major mode controls which delimiters are significant,
0604: through the syntax table (@pxref{Syntax Tables,, Syntax Tables, elisp,
0605: The Emacs Lisp Reference Manual}).  In Lisp, only parentheses count;
0606: in C, these commands apply to braces and brackets too.
0607: 
0608:   You can use @kbd{M-x check-parens} to find any unbalanced
0609: parentheses and unbalanced string quotes in the buffer.
0610: 
0611: @menu
0612: * Expressions::         Expressions with balanced parentheses.
0613: * Moving by Parens::    Commands for moving up, down and across
0614:                           in the structure of parentheses.
0615: * Matching::            Insertion of a close-delimiter flashes matching open.
0616: @end menu
0617: 
0618: @node Expressions
0619: @subsection Expressions with Balanced Parentheses
0620: 
0621: @cindex sexp
0622: @cindex expression
0623: @cindex balanced expression
0624:   Each programming language mode has its own definition of a
0625: @dfn{balanced expression}.  Balanced expressions typically include
0626: individual symbols, numbers, and string constants, as well as pieces
0627: of code enclosed in a matching pair of delimiters.  The following
0628: commands deal with balanced expressions (in Emacs, such expressions
0629: are referred to internally as @dfn{sexps}@footnote{The word ``sexp''
0630: is used to refer to an expression in Lisp.}).
0631: 
0632: @table @kbd
0633: @item C-M-f
0634: Move forward over a balanced expression (@code{forward-sexp}).
0635: @item C-M-b
0636: Move backward over a balanced expression (@code{backward-sexp}).
0637: @item C-M-k
0638: Kill balanced expression forward (@code{kill-sexp}).
0639: @item C-M-t
0640: Transpose expressions (@code{transpose-sexps}).
0641: @item C-M-@@
0642: @itemx C-M-@key{SPC}
0643: Put mark after following expression (@code{mark-sexp}).
0644: @end table
0645: 
0646: @kindex C-M-f
0647: @kindex C-M-b
0648: @findex forward-sexp
0649: @findex backward-sexp
0650:   To move forward over a balanced expression, use @kbd{C-M-f}
0651: (@code{forward-sexp}).  If the first significant character after point
0652: is an opening delimiter (e.g., @samp{(}, @samp{[} or @samp{@{} in C),
0653: this command moves past the matching closing delimiter.  If the
0654: character begins a symbol, string, or number, the command moves over
0655: that.
0656: 
0657:   The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a
0658: balanced expression---like @kbd{C-M-f}, but in the reverse direction.
0659: If the expression is preceded by any prefix characters (single-quote,
0660: backquote and comma, in Lisp), the command moves back over them as
0661: well.
0662: 
0663:   @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation
0664: the specified number of times; with a negative argument means to move
0665: in the opposite direction.  In most modes, these two commands move
0666: across comments as if they were whitespace.  Note that their keys,
0667: @kbd{C-M-f} and @kbd{C-M-b}, are analogous to @kbd{C-f} and @kbd{C-b},
0668: which move by characters (@pxref{Moving Point}), and @kbd{M-f} and
0669: @kbd{M-b}, which move by words (@pxref{Words}).
0670: 
0671: @cindex killing expressions
0672: @kindex C-M-k
0673: @findex kill-sexp
0674:   To kill a whole balanced expression, type @kbd{C-M-k}
0675: (@code{kill-sexp}).  This kills the text that @kbd{C-M-f} would move
0676: over.
0677: 
0678: @cindex transposition of expressions
0679: @kindex C-M-t
0680: @findex transpose-sexps
0681:   @kbd{C-M-t} (@code{transpose-sexps}) switches the positions of the
0682: previous balanced expression and the next one.  It is analogous to the
0683: @kbd{C-t} command, which transposes characters (@pxref{Transpose}).
0684: An argument to @kbd{C-M-t} serves as a repeat count, moving the
0685: previous expression over that many following ones.  A negative
0686: argument moves the previous balanced expression backwards across those
0687: before it.  An argument of zero, rather than doing nothing, transposes
0688: the balanced expressions ending at or after point and the mark.
0689: 
0690: @kindex C-M-SPC
0691:   To operate on balanced expressions with a command which acts on the
0692: region, type @kbd{C-M-@key{SPC}} (@code{mark-sexp}).  This sets the
0693: mark where @kbd{C-M-f} would move to.  While the mark is active, each
0694: successive call to this command extends the region by shifting the
0695: mark by one expression.  Positive or negative numeric arguments move
0696: the mark forward or backward by the specified number of expressions.
0697: The alias @kbd{C-M-@@} is equivalent to @kbd{C-M-@key{SPC}}.
0698: @xref{Marking Objects}, for more information about this and related
0699: commands.
0700: 
0701:   In languages that use infix operators, such as C, it is not possible
0702: to recognize all balanced expressions because there can be multiple
0703: possibilities at a given position.  For example, C mode does not treat
0704: @samp{foo + bar} as a single expression, even though it @emph{is} one
0705: C expression; instead, it recognizes @samp{foo} as one expression and
0706: @samp{bar} as another, with the @samp{+} as punctuation between them.
0707: However, C mode recognizes @samp{(foo + bar)} as a single expression,
0708: because of the parentheses.
0709: 
0710: @node Moving by Parens
0711: @subsection Moving in the Parenthesis Structure
0712: 
0713: @cindex parenthetical groupings
0714: @cindex parentheses, moving across
0715: @cindex matching parenthesis and braces, moving to
0716: @cindex braces, moving across
0717: @cindex list commands
0718: 
0719:   The following commands move over groupings delimited by parentheses
0720: (or whatever else serves as delimiters in the language you are working
0721: with).  They ignore strings and comments, including any parentheses
0722: within them, and also ignore parentheses that are quoted with an
0723: escape character.  These commands are mainly intended for editing
0724: programs, but can be useful for editing any text containing
0725: parentheses.  They are referred to internally as ``list commands''
0726: because in Lisp these groupings are lists.
0727: 
0728:   These commands assume that the starting point is not inside a string
0729: or a comment.  If you invoke them from inside a string or comment, the
0730: results are unreliable.
0731: 
0732: @table @kbd
0733: @item C-M-n
0734: Move forward over a parenthetical group (@code{forward-list}).
0735: @item C-M-p
0736: Move backward over a parenthetical group (@code{backward-list}).
0737: @item C-M-u
0738: Move up in parenthesis structure (@code{backward-up-list}).
0739: @item C-M-d
0740: Move down in parenthesis structure (@code{down-list}).
0741: @end table
0742: 
0743: @kindex C-M-n
0744: @kindex C-M-p
0745: @findex forward-list
0746: @findex backward-list
0747:   The list commands @kbd{C-M-n} (@code{forward-list}) and
0748: @kbd{C-M-p} (@code{backward-list}) move forward or backward over one
0749: (or @var{n}) parenthetical groupings.
0750: 
0751: @kindex C-M-u
0752: @findex backward-up-list
0753:   @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the
0754: parenthesis structure.  To move @emph{up} one (or @var{n}) levels, use
0755: @kbd{C-M-u} (@code{backward-up-list}).  @kbd{C-M-u} moves backward up
0756: past one unmatched opening delimiter.  A positive argument serves as a
0757: repeat count; a negative argument reverses the direction of motion, so
0758: that the command moves forward and up one or more levels.
0759: 
0760: @kindex C-M-d
0761: @findex down-list
0762:   To move @emph{down} in the parenthesis structure, use @kbd{C-M-d}
0763: (@code{down-list}).  In Lisp mode, where @samp{(} is the only opening
0764: delimiter, this is nearly the same as searching for a @samp{(}.  An
0765: argument specifies the number of levels to go down.
0766: 
0767: @node Matching
0768: @subsection Matching Parentheses
0769: @cindex matching parentheses
0770: @cindex parentheses, displaying matches
0771: 
0772:   Emacs has a number of @dfn{parenthesis matching} features, which
0773: make it easy to see how and whether parentheses (or other delimiters)
0774: match up.
0775: 
0776:   Whenever you type a self-inserting character that is a closing
0777: delimiter, Emacs briefly indicates the location of the matching
0778: opening delimiter, provided that is on the screen.  If it is not on
0779: the screen, Emacs displays some of the text near it in the echo area.
0780: Either way, you can tell which grouping you are closing off.  If the
0781: opening delimiter and closing delimiter are mismatched---such as in
0782: @samp{[x)}---a warning message is displayed in the echo area.
0783: 
0784: @vindex blink-matching-paren
0785: @vindex blink-matching-paren-distance
0786: @vindex blink-matching-delay
0787:   Three variables control the display of matching parentheses:
0788: 
0789: @itemize @bullet
0790: @item
0791: @code{blink-matching-paren} turns the feature on or off: @code{nil}
0792: disables it, but the default is @code{t} to enable it.  Set it to
0793: @code{jump} to make indication work by momentarily moving the cursor
0794: to the matching opening delimiter.  Set it to @code{jump-offscreen} to
0795: make the cursor jump, even if the opening delimiter is off screen.
0796: 
0797: @item
0798: @code{blink-matching-delay} says how many seconds to keep indicating
0799: the matching opening delimiter.  This may be an integer or
0800: floating-point number; the default is 1.
0801: 
0802: @item
0803: @code{blink-matching-paren-distance} specifies how many characters
0804: back to search to find the matching opening delimiter.  If the match
0805: is not found in that distance, Emacs stops scanning and nothing is
0806: displayed.  The default is 102400.
0807: @end itemize
0808: 
0809: @cindex Show Paren mode
0810: @cindex highlighting matching parentheses
0811: @findex show-paren-mode
0812:   Show Paren mode, a global minor mode, provides a more powerful kind
0813: of automatic matching.  Whenever point is before an opening delimiter
0814: or after a closing delimiter, the delimiter, its matching delimiter,
0815: and optionally the text between them are highlighted.  To toggle Show
0816: Paren mode, type @kbd{M-x show-paren-mode}.  To customize it, type
0817: @kbd{M-x customize-group @key{RET} paren-showing}.  The customizable
0818: options which control the operation of this mode include:
0819: 
0820: @itemize @bullet
0821: @item
0822: @vindex show-paren-highlight-openparen
0823: @code{show-paren-highlight-openparen} controls whether to highlight
0824: an open paren when point stands just before it, and hence its position
0825: is marked by the cursor anyway.  The default is non-@code{nil} (yes).
0826: 
0827: @item
0828: @vindex show-paren-style
0829: @code{show-paren-style} controls whether just the two parens, or also
0830: the space between them get highlighted.  The valid options here are
0831: @code{parenthesis} (show the matching paren), @code{expression}
0832: (highlight the entire expression enclosed by the parens), and
0833: @code{mixed} (highlight the matching paren if it is visible, the
0834: expression otherwise).
0835: 
0836: @item
0837: @vindex show-paren-when-point-inside-paren
0838: @code{show-paren-when-point-inside-paren}, when non-@code{nil}, causes
0839: highlighting also when point is on the inside of a parenthesis.
0840: 
0841: @item
0842: @vindex show-paren-when-point-in-periphery
0843: @code{show-paren-when-point-in-periphery}, when non-@code{nil}, causes
0844: highlighting also when point is in whitespace at the beginning or end
0845: of a line, and there is a paren at, respectively, the first or last,
0846: or the last, non-whitespace position on the line.
0847: @end itemize
0848: 
0849: @cindex Electric Pair mode
0850: @cindex inserting matching parentheses
0851: @findex electric-pair-mode
0852:   Electric Pair mode, a global minor mode, provides a way to easily
0853: insert matching delimiters: parentheses, braces, brackets, etc.
0854: Whenever you insert an opening delimiter, the matching closing
0855: delimiter is automatically inserted as well, leaving point between the
0856: two.  Conversely, when you insert a closing delimiter over an existing
0857: one, no insertion takes places, and that position is simply skipped
0858: over.  If the region is active (@pxref{Mark}), insertion of a
0859: delimiter operates on the region: the characters in the region are
0860: enclosed in a pair of matching delimiters, leaving point after the
0861: delimiter you typed.
0862: 
0863: These variables control additional features of Electric Pair mode:
0864: 
0865: @itemize @bullet
0866: @item
0867: @vindex electric-pair-preserve-balance
0868: @code{electric-pair-preserve-balance}, when non-@code{nil}, makes the
0869: default pairing logic balance out the number of opening and closing
0870: delimiters.
0871: 
0872: @item
0873: @vindex electric-pair-delete-adjacent-pairs
0874: @code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes
0875: backspacing between two adjacent delimiters also automatically delete
0876: the closing delimiter.
0877: 
0878: @item
0879: @vindex electric-pair-open-newline-between-pairs
0880: @code{electric-pair-open-newline-between-pairs}, when non-@code{nil},
0881: makes inserting a newline between two adjacent pairs also
0882: automatically open an extra newline after point.
0883: 
0884: @item
0885: @vindex electric-pair-skip-whitespace
0886: @code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor
0887: mode to skip whitespace forward before deciding whether to skip over
0888: the closing delimiter.
0889: @end itemize
0890: 
0891: To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}.  To
0892: toggle the mode in a single buffer, use @kbd{M-x
0893: electric-pair-local-mode}.
0894: 
0895: @node Comments
0896: @section Manipulating Comments
0897: @cindex comments
0898: 
0899:   Because comments are such an important part of programming, Emacs
0900: provides special commands for editing and inserting comments.  It can
0901: also do spell checking on comments with Flyspell Prog mode
0902: (@pxref{Spelling}).
0903: 
0904:   Some major modes have special rules for indenting different kinds of
0905: comments.  For example, in Lisp code, comments starting with two
0906: semicolons are indented as if they were lines of code, while those
0907: starting with three semicolons are supposed to be aligned to the left
0908: margin and are often used for sectioning purposes.  Emacs understands
0909: these conventions; for instance, typing @kbd{@key{TAB}} on a comment
0910: line will indent the comment to the appropriate position.
0911: 
0912: @example
0913: ;; This function is just an example.
0914: ;;; Here either two or three semicolons are appropriate.
0915: (defun foo (x)
0916: ;;;  And now, the first part of the function:
0917:   ;; The following line adds one.
0918:   (1+ x))           ; This line adds one.
0919: @end example
0920: 
0921: @menu
0922: * Comment Commands::    Inserting, killing, and aligning comments.
0923: * Multi-Line Comments:: Commands for adding and editing multi-line comments.
0924: * Options for Comments::Customizing the comment features.
0925: @end menu
0926: 
0927: @node Comment Commands
0928: @subsection Comment Commands
0929: @cindex indentation for comments
0930: @cindex alignment for comments
0931: 
0932:   The following commands operate on comments:
0933: 
0934: @table @asis
0935: @item @kbd{M-;}
0936: Insert or realign comment on current line; if the region is active,
0937: comment or uncomment the region instead (@code{comment-dwim}).
0938: @item @kbd{C-x C-;}
0939: Comment or uncomment the current line (@code{comment-line}).  If the
0940: region is active, comment or uncomment the lines in the region
0941: instead.
0942: @item @kbd{C-u M-;}
0943: Kill comment on current line (@code{comment-kill}).
0944: @item @kbd{C-x ;}
0945: Set comment column (@code{comment-set-column}).
0946: @item @kbd{C-M-j}
0947: @itemx @kbd{M-j}
0948: Like @kbd{@key{RET}} followed by inserting and aligning a comment
0949: (@code{comment-indent-new-line}).  @xref{Multi-Line Comments}.
0950: @item @kbd{M-x comment-region}
0951: @itemx @kbd{C-c C-c} (in C-like modes)
0952: Add comment delimiters to all the lines in the region.
0953: @end table
0954: 
0955: @kindex M-;
0956: @findex comment-dwim
0957:   The command to create or align a comment is @kbd{M-;}
0958: (@code{comment-dwim}).  The word ``dwim'' is an acronym for ``Do What
0959: I Mean''; it indicates that this command can be used for many
0960: different jobs relating to comments, depending on the situation where
0961: you use it.
0962: 
0963:   When a region is active (@pxref{Mark}), @kbd{M-;} either adds
0964: comment delimiters to the region, or removes them.  If every line in
0965: the region is already a comment, it uncomments each of those lines
0966: by removing their comment delimiters.  Otherwise, it adds comment
0967: delimiters to enclose the text in the region.
0968: 
0969:   If you supply a prefix argument to @kbd{M-;} when a region is
0970: active, that specifies the number of comment delimiters to add or
0971: delete.  A positive argument @var{n} adds @var{n} delimiters, while a
0972: negative argument @var{-n} removes @var{n} delimiters.
0973: 
0974:   If the region is not active, and there is no existing comment on the
0975: current line, @kbd{M-;} adds a new comment to the current line.  If
0976: the line is blank (i.e., empty or containing only whitespace
0977: characters), the comment is indented to the same position where
0978: @kbd{@key{TAB}} would indent to (@pxref{Basic Indent}).  If the line
0979: is non-blank, the comment is placed after the last non-whitespace
0980: character on the line.  Emacs tries to fit the comment between the
0981: columns specified by the variables @code{comment-column} and
0982: @code{comment-fill-column} (@pxref{Options for Comments}), if
0983: possible.  Otherwise, it will choose some other suitable position,
0984: usually separated from the non-comment text by at least one space.  In
0985: each case, Emacs places point after the comment's starting delimiter,
0986: so that you can start typing the comment text right away.
0987: 
0988:   You can also use @kbd{M-;} to align an existing comment.  If a line
0989: already contains the comment-start string, @kbd{M-;} realigns it to
0990: the conventional alignment and moves point after the comment's
0991: starting delimiter.  As an exception, comments starting in column 0
0992: are not moved.  Even when an existing comment is properly aligned,
0993: @kbd{M-;} is still useful for moving directly to the start of the
0994: comment text.
0995: 
0996: @findex comment-line
0997: @kindex C-x C-;
0998:   @kbd{C-x C-;} (@code{comment-line}) comments or uncomments complete
0999: lines.  When a region is active (@pxref{Mark}), @kbd{C-x C-;} either
1000: comments or uncomments the lines in the region.  If the region is not
1001: active, this command comments or uncomments the line point is on.
1002: With a positive prefix argument @var{n}, it operates on @var{n} lines
1003: starting with the current one; with a negative @var{n}, it affects
1004: @var{n} preceding lines.  After invoking this command with a negative
1005: argument, successive invocations with a positive argument will operate
1006: on preceding lines as if the argument were negated.
1007: 
1008: @findex comment-kill
1009: @kindex C-u M-;
1010:   @kbd{C-u M-;} (@code{comment-dwim} with a prefix argument) kills any
1011: comment on the current line, along with the whitespace before it.
1012: Since the comment is saved to the kill ring, you can reinsert it on
1013: another line by moving to the end of that line, doing @kbd{C-y}, and
1014: then @kbd{M-;} to realign the comment.  You can achieve the same
1015: effect as @kbd{C-u M-;} by typing @kbd{M-x comment-kill}
1016: (@code{comment-dwim} actually calls @code{comment-kill} as a
1017: subroutine when it is given a prefix argument).
1018: 
1019: @kindex C-c C-c @r{(C mode)}
1020: @findex comment-region
1021: @findex uncomment-region
1022:   The command @kbd{M-x comment-region} is equivalent to calling
1023: @kbd{M-;} on an active region, except that it always acts on the
1024: region, even if the mark is inactive.  In C mode and related modes,
1025: this command is bound to @kbd{C-c C-c}.  The command @kbd{M-x
1026: uncomment-region} uncomments each line in the region; a numeric prefix
1027: argument specifies the number of comment delimiters to remove
1028: (negative arguments specify the number of comment delimiters to add).
1029: 
1030:   For C-like modes, you can configure the exact effect of @kbd{M-;} by
1031: setting the variables @code{c-indent-comment-alist} and
1032: @code{c-indent-comments-syntactically-p}.  For example, on a line
1033: ending in a closing brace, @kbd{M-;} puts the comment one space after
1034: the brace rather than at @code{comment-column}.  For full details see
1035: @ref{Comment Commands,,, ccmode, The CC Mode Manual}.
1036: 
1037: @node Multi-Line Comments
1038: @subsection Multiple Lines of Comments
1039: 
1040: @kindex C-M-j
1041: @kindex M-j
1042: @cindex blank lines in programs
1043: @findex comment-indent-new-line
1044: @vindex comment-multi-line
1045:   If you are typing a comment and wish to continue it to another line,
1046: type @kbd{M-j} or @kbd{C-M-j} (@code{comment-indent-new-line}).  This
1047: breaks the current line, and inserts the necessary comment delimiters
1048: and indentation to continue the comment.
1049: 
1050:   For languages with closing comment delimiters (e.g., @samp{*/} in
1051: C), the exact behavior of @kbd{M-j} depends on the value of the
1052: variable @code{comment-multi-line}.  If the value is @code{nil}, the
1053: command closes the comment on the old line and starts a new comment on
1054: the new line.  Otherwise, it opens a new line within the current
1055: comment delimiters.
1056: 
1057:   When Auto Fill mode is on, going past the fill column while typing a
1058: comment also continues the comment, in the same way as an explicit
1059: invocation of @kbd{M-j}.
1060: 
1061:   To turn existing lines into comment lines, use @kbd{M-;} with the
1062: region active, or use @kbd{M-x comment-region}
1063: @ifinfo
1064: (@pxref{Comment Commands}).
1065: @end ifinfo
1066: @ifnotinfo
1067: as described in the preceding section.
1068: @end ifnotinfo
1069: 
1070:   You can configure C Mode such that when you type a @samp{/} at the
1071: start of a line in a multi-line block comment, this closes the
1072: comment.  Enable the @code{comment-close-slash} clean-up for this.
1073: @xref{Clean-ups,,, ccmode, The CC Mode Manual}.
1074: 
1075: @node Options for Comments
1076: @subsection Options Controlling Comments
1077: 
1078: @vindex comment-column
1079: @vindex comment-fill-column
1080: @kindex C-x ;
1081: @findex comment-set-column
1082:   As mentioned in @ref{Comment Commands}, when the @kbd{M-j} command
1083: adds a comment to a line, it tries to place the comment between the
1084: columns specified by the buffer-local variables @code{comment-column}
1085: and @code{comment-fill-column} (or if that is @code{nil}, then the
1086: value of @code{fill-column}, @pxref{Fill Commands}).  You can set
1087: either the local value or the default value of these buffer-local
1088: variables in the usual way (@pxref{Locals}).  Alternatively, you can
1089: type @kbd{C-x ;} (@code{comment-set-column}) to set the value of
1090: @code{comment-column} in the current buffer to the column where point
1091: is currently located.  @kbd{C-u C-x ;} sets the comment column to
1092: match the last comment before point in the buffer, and then does a
1093: @kbd{M-;} to align the current line's comment under the previous one.
1094: 
1095: @vindex comment-start-skip
1096:   The comment commands recognize comments based on the regular
1097: expression that is the value of the variable @code{comment-start-skip}.
1098: Make sure this regexp does not match the null string.  It may match more
1099: than the comment starting delimiter in the strictest sense of the word;
1100: for example, in C mode the value of the variable is
1101: @c This stops M-q from breaking the line inside that @code.
1102: @code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and
1103: spaces after the @samp{/*} itself, and accepts C++ style comments
1104: also.  (Note that @samp{\\} is needed in Lisp syntax to include a
1105: @samp{\} in the string, which is needed to deny the first star its
1106: special meaning in regexp syntax.  @xref{Regexp Backslash}.)
1107: 
1108: @vindex comment-start
1109: @vindex comment-end
1110:   When a comment command makes a new comment, it inserts the value of
1111: @code{comment-start} as an opening comment delimiter.  It also inserts
1112: the value of @code{comment-end} after point, as a closing comment
1113: delimiter.  For example, in Lisp mode, @code{comment-start} is
1114: @samp{";"} and @code{comment-end} is @code{""} (the empty string).  In
1115: C mode, @code{comment-start} is @code{"/* "} and @code{comment-end} is
1116: @code{" */"}.
1117: 
1118: @vindex comment-padding
1119:   The variable @code{comment-padding} specifies a string that the
1120: commenting commands should insert between the comment delimiter(s) and
1121: the comment text.  The default, @samp{" "}, specifies a single space.
1122: Alternatively, the value can be a number, which specifies that number
1123: of spaces, or @code{nil}, which means no spaces at all.
1124: 
1125:   The variable @code{comment-multi-line} controls how @kbd{M-j} and
1126: Auto Fill mode continue comments over multiple lines.
1127: @xref{Multi-Line Comments}.
1128: 
1129: @vindex comment-indent-function
1130:   The variable @code{comment-indent-function} should contain a function
1131: that will be called to compute the alignment for a newly inserted
1132: comment or for aligning an existing comment.  It is set differently by
1133: various major modes.  The function is called with no arguments, but with
1134: point at the beginning of the comment, or at the end of a line if a new
1135: comment is to be inserted.  It should return the column in which the
1136: comment ought to start.  For example, the default function bases its
1137: decision on how many comment characters begin an existing comment.
1138: 
1139: Emacs also tries to align comments on adjacent lines.  To override
1140: this, the function may return a cons of two (possibly equal) integers
1141: to indicate an acceptable range of indentation.
1142: 
1143: @node Documentation
1144: @section Documentation Lookup
1145: 
1146:   Emacs provides several features you can use to look up the
1147: documentation of functions, variables and commands that you plan to
1148: use in your program.
1149: 
1150: @menu
1151: * Info Lookup::         Looking up library functions and commands in Info files.
1152: * Man Page::            Looking up man pages of library functions and commands.
1153: * Lisp Doc::            Looking up Emacs Lisp functions, etc.
1154: @end menu
1155: 
1156: @node Info Lookup
1157: @subsection Info Documentation Lookup
1158: 
1159: @findex info-lookup-file
1160:   For major modes that apply to languages which have documentation in
1161: Info, you can use @kbd{C-h S} (@code{info-lookup-symbol}) to view the
1162: Info documentation for a symbol used in the program.  You specify the
1163: symbol with the minibuffer; the default is the symbol appearing in the
1164: buffer at point.  For example, in C mode this looks for the symbol in
1165: the C Library Manual.  The command only works if the appropriate
1166: manual's Info files are installed.
1167: 
1168:   Emacs determines where to look for documentation for the
1169: symbol---which Info files to look in, and which indices to
1170: search---based on the major mode.  You can also use @kbd{M-x
1171: info-lookup-file} to look for documentation for a file name.
1172: 
1173:   If you use @kbd{C-h S} in a major mode that does not support it,
1174: it asks you to specify the symbol help mode.  You should enter
1175: a command such as @code{c-mode} that would select a major
1176: mode which @kbd{C-h S} does support.
1177: 
1178: @node Man Page
1179: @subsection Man Page Lookup
1180: 
1181: @cindex man page
1182:   On Unix, the main form of on-line documentation was the @dfn{manual
1183: page} or @dfn{man page}.  In the GNU operating system, we aim to
1184: replace man pages with better-organized manuals that you can browse
1185: with Info (@pxref{Misc Help}).  This process is not finished, so it is
1186: still useful to read manual pages.
1187: 
1188: @findex man
1189:   You can read the man page for an operating system command, library
1190: function, or system call, with the @kbd{M-x man} command.  This
1191: prompts for a topic, with completion (@pxref{Completion}), and runs
1192: the @command{man} program to format the corresponding man page.  If
1193: the system permits, it runs @command{man} asynchronously, so that you
1194: can keep on editing while the page is being formatted.  The result
1195: goes in a buffer named @file{*Man @var{topic}*}.  These buffers use a
1196: special major mode, Man mode, that facilitates scrolling and jumping
1197: to other manual pages.  For details, type @kbd{C-h m} while in a Man
1198: mode buffer.
1199: 
1200: @cindex sections of manual pages
1201:   Each man page belongs to one of ten or more @dfn{sections}, each
1202: named by a digit or by a digit and a letter.  Sometimes there are man
1203: pages with the same name in different sections.  To read a man page
1204: from a specific section, type @samp{@var{topic}(@var{section})} or
1205: @samp{@var{section} @var{topic}} when @kbd{M-x man} prompts for the
1206: topic.  For example, the man page for the C library function
1207: @code{chmod} is in section 2, but there is a shell command of the same
1208: name, whose man page is in section 1; to view the former, type
1209: @w{@kbd{M-x man @key{RET} chmod(2) @key{RET}}}.
1210: 
1211: @vindex Man-switches
1212: @kindex M-n @r{(Man mode)}
1213: @kindex M-p @r{(Man mode)}
1214:   If you do not specify a section, @kbd{M-x man} normally displays
1215: only the first man page found.  On some systems, the @code{man}
1216: program accepts a @samp{-a} command-line option, which tells it to
1217: display all the man pages for the specified topic.  To make use of
1218: this, change the value of the variable @code{Man-switches} to
1219: @samp{"-a"}.  Then, in the Man mode buffer, you can type @kbd{M-n} and
1220: @kbd{M-p} to switch between man pages in different sections.  The mode
1221: line shows how many manual pages are available.
1222: 
1223: @findex woman
1224: @cindex manual pages, on MS-DOS/MS-Windows
1225:   An alternative way of reading manual pages is the @kbd{M-x woman}
1226: command.  Unlike @kbd{M-x man}, it does not run any external programs
1227: to format and display the man pages; the formatting is done by Emacs,
1228: so it works on systems such as MS-Windows where the @command{man}
1229: program may be unavailable.  It prompts for a man page, and displays
1230: it in a buffer named @file{*WoMan @var{section} @var{topic}}.
1231: 
1232:   @kbd{M-x woman} computes the completion list for manpages the first
1233: time you invoke the command.  With a numeric argument, it recomputes
1234: this list; this is useful if you add or delete manual pages.
1235: 
1236:   If you type a name of a manual page and @kbd{M-x woman} finds that
1237: several manual pages by the same name exist in different sections, it
1238: pops up a window with possible candidates asking you to choose one of
1239: them.
1240: 
1241:   Note that @kbd{M-x woman} doesn't yet support the latest features of
1242: modern man pages, so we recommend using @kbd{M-x man} if that is
1243: available on your system.
1244: 
1245:   For more information about setting up and using @kbd{M-x woman}, see
1246: @ifinfo
1247: @ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The
1248: WoMan Manual}.
1249: @end ifinfo
1250: @ifnotinfo
1251: the WoMan Info manual, which is distributed with Emacs.
1252: @end ifnotinfo
1253: 
1254: @node Lisp Doc
1255: @subsection Emacs Lisp Documentation Lookup
1256: 
1257:   When editing Emacs Lisp code, you can use the commands @kbd{C-h f}
1258: (@code{describe-function}) and @kbd{C-h v} (@code{describe-variable})
1259: to view the built-in documentation for the Lisp functions and
1260: variables that you want to use.  @xref{Name Help}.
1261: 
1262: @cindex Eldoc mode
1263: @findex eldoc-mode
1264: @findex global-eldoc-mode
1265:   Eldoc is a buffer-local minor mode that helps with looking up Lisp
1266: documentation.  When it is enabled, the echo area displays some useful
1267: information whenever there is a Lisp function or variable at point;
1268: for a function, it shows the argument list, and for a variable it
1269: shows the first line of the variable's documentation string.  To
1270: toggle Eldoc mode, type @kbd{M-x eldoc-mode}.  There's also a Global
1271: Eldoc mode, which is turned on by default, and affects buffers, such
1272: as @samp{*scratch*}, whose major mode is Emacs Lisp or Lisp
1273: Interaction (@w{@kbd{M-x global-eldoc-mode}} to turn it off globally).
1274: 
1275: @node Hideshow
1276: @section Hideshow minor mode
1277: @cindex Hideshow mode
1278: @cindex mode, Hideshow
1279: 
1280: @findex hs-minor-mode
1281:   Hideshow mode is a buffer-local minor mode that allows you to
1282: selectively display portions of a program, which are referred to as
1283: @dfn{blocks}.  Type @kbd{M-x hs-minor-mode} to toggle this minor mode
1284: (@pxref{Minor Modes}).
1285: 
1286:   When you use Hideshow mode to hide a block, the block disappears
1287: from the screen, to be replaced by an ellipsis (three periods in a
1288: row).  Just what constitutes a block depends on the major mode.  In C
1289: mode and related modes, blocks are delimited by braces, while in Lisp
1290: mode they are delimited by parentheses.  Multi-line comments also
1291: count as blocks.
1292: 
1293:   Hideshow mode provides the following commands:
1294: 
1295: @findex hs-hide-all
1296: @findex hs-hide-block
1297: @findex hs-show-all
1298: @findex hs-show-block
1299: @findex hs-show-region
1300: @findex hs-hide-level
1301: @kindex C-c @@ C-h
1302: @kindex C-c @@ C-s
1303: @kindex C-c @@ C-M-h
1304: @kindex C-c @@ C-M-s
1305: @kindex C-c @@ C-r
1306: @kindex C-c @@ C-l
1307: @kindex S-mouse-2
1308: @table @kbd
1309: @item C-c @@ C-h
1310: @itemx C-c @@ C-d
1311: Hide the current block (@code{hs-hide-block}).
1312: @item C-c @@ C-s
1313: Show the current block (@code{hs-show-block}).
1314: @item C-c @@ C-c
1315: @itemx C-x @@ C-e
1316: Either hide or show the current block (@code{hs-toggle-hiding}).
1317: @item S-mouse-2
1318: Toggle hiding for the block you click on (@code{hs-mouse-toggle-hiding}).
1319: @item C-c @@ C-M-h
1320: @itemx C-c @@ C-t
1321: Hide all top-level blocks (@code{hs-hide-all}).
1322: @item C-c @@ C-M-s
1323: @itemx C-c @@ C-a
1324: Show all blocks in the buffer (@code{hs-show-all}).
1325: @item C-u @var{n} C-c @@ C-l
1326: Hide all blocks @var{n} levels below this block
1327: (@code{hs-hide-level}).
1328: @end table
1329: 
1330: @vindex hs-hide-comments-when-hiding-all
1331: @vindex hs-isearch-open
1332: @vindex hs-special-modes-alist
1333:   These variables can be used to customize Hideshow mode:
1334: 
1335: @table @code
1336: @item hs-hide-comments-when-hiding-all
1337: If non-@code{nil}, @kbd{C-c @@ C-M-h} (@code{hs-hide-all}) hides
1338: comments too.
1339: 
1340: @item hs-isearch-open
1341: This variable specifies the conditions under which incremental search
1342: should unhide a hidden block when matching text occurs within the
1343: block.  Its value should be either @code{code} (unhide only code
1344: blocks), @code{comment} (unhide only comments), @code{t} (unhide both
1345: code blocks and comments), or @code{nil} (unhide neither code blocks
1346: nor comments).  The default value is @code{code}.
1347: @end table
1348: 
1349: @node Symbol Completion
1350: @section Completion for Symbol Names
1351: @cindex completion (symbol names)
1352: 
1353:   Completion is normally done in the minibuffer (@pxref{Completion}),
1354: but you can also complete symbol names in ordinary Emacs buffers.
1355: 
1356: @kindex M-TAB
1357: @kindex C-M-i
1358:   In programming language modes, type @kbd{C-M-i} or @kbd{M-@key{TAB}}
1359: to complete the partial symbol before point.  On graphical displays,
1360: the @kbd{M-@key{TAB}} key is usually reserved by the window manager
1361: for switching graphical windows, so you should type @kbd{C-M-i} or
1362: @kbd{@key{ESC} @key{TAB}} instead.
1363: 
1364: @cindex tags-based completion
1365: @findex completion-at-point@r{, in programming language modes}
1366: @cindex Lisp symbol completion
1367: @cindex completion (Lisp symbols)
1368:   In most programming language modes, @kbd{C-M-i} (or
1369: @kbd{M-@key{TAB}}) invokes the command @code{completion-at-point},
1370: which generates its completion list in a flexible way.  If Semantic
1371: mode is enabled, it tries to use the Semantic parser data for
1372: completion (@pxref{Semantic}).  If Semantic mode is not enabled or
1373: fails at performing completion, it tries to complete using the
1374: selected tags table (@pxref{Tags Tables}).  If in Emacs Lisp mode, it
1375: performs completion using the function, variable, or property names
1376: defined in the current Emacs session.
1377: 
1378:   In all other respects, in-buffer symbol completion behaves like
1379: minibuffer completion.  For instance, if Emacs cannot complete to a
1380: unique symbol, it displays a list of completion alternatives in
1381: another window.  @xref{Completion}.
1382: 
1383:   In Text mode and related modes, @kbd{M-@key{TAB}} completes words
1384: based on the spell-checker's dictionary.  @xref{Spelling}.
1385: 
1386: @node MixedCase Words
1387: @section MixedCase Words
1388: @cindex camel case
1389: 
1390:   Some programming styles make use of mixed-case (or ``CamelCase'')
1391: symbols like @samp{unReadableSymbol}.  (In the GNU project, we recommend
1392: using underscores to separate words within an identifier, rather than
1393: using case distinctions.)  Emacs has various features to make it easier
1394: to deal with such symbols.
1395: 
1396: @cindex Glasses mode
1397: @cindex mode, Glasses
1398:   Glasses mode is a buffer-local minor mode that makes it easier to read
1399: such symbols, by altering how they are displayed.  By default, it
1400: displays extra underscores between each lower-case letter and the
1401: following capital letter.  This does not alter the buffer text, only how
1402: it is displayed.
1403: 
1404:   To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor
1405: Modes}).  When Glasses mode is enabled, the minor mode indicator
1406: @samp{o^o} appears in the mode line.  For more information about
1407: Glasses mode, type @kbd{C-h P glasses @key{RET}}.
1408: 
1409: @cindex Subword mode
1410: @findex subword-mode
1411:   Subword mode is another buffer-local minor mode.  In subword mode,
1412: Emacs's word commands recognize upper case letters in
1413: @samp{StudlyCapsIdentifiers} as word boundaries.  When Subword mode is
1414: enabled, the minor mode indicator @samp{,} appears in the mode line.
1415: See also the similar @code{superword-mode} (@pxref{Misc for Programs}).
1416: 
1417: @node Semantic
1418: @section Semantic
1419: @cindex Semantic package
1420: 
1421: Semantic is a package that provides language-aware editing commands
1422: based on @code{source code parsers}.  This section provides a brief
1423: description of Semantic; for full details,
1424: @ifnottex
1425: see @ref{Top, Semantic,, semantic, Semantic}.
1426: @end ifnottex
1427: @iftex
1428: see the Semantic Info manual, which is distributed with Emacs.
1429: @end iftex
1430: 
1431:   Most of the language-aware features in Emacs, such as Font Lock
1432: mode (@pxref{Font Lock}), rely on rules of thumb@footnote{Regular
1433: expressions and syntax tables.} that usually give good results but are
1434: never completely exact.  In contrast, the parsers used by Semantic
1435: have an exact understanding of programming language syntax.  This
1436: allows Semantic to provide search, navigation, and completion commands
1437: that are powerful and precise.
1438: 
1439: @cindex Semantic mode
1440: @cindex mode, Semantic
1441:   To begin using Semantic, type @kbd{M-x semantic-mode} or click on
1442: the menu item named @samp{Source Code Parsers (Semantic)} in the
1443: @samp{Tools} menu.  This enables Semantic mode, a global minor mode.
1444: 
1445:    When Semantic mode is enabled, Emacs automatically attempts to
1446: parse each file you visit.  Currently, Semantic understands C, C++,
1447: HTML, Java, Javascript, Make, Python, Scheme, SRecode, and Texinfo.
1448: Within each parsed buffer, the following commands are available:
1449: 
1450: @table @kbd
1451: @item C-c , j
1452: @kindex C-c , j
1453: Prompt for the name of a function defined in the current file, and
1454: move point there (@code{semantic-complete-jump-local}).
1455: 
1456: @item C-c , J
1457: @kindex C-c , J
1458: Prompt for the name of a function defined in any file Emacs has
1459: parsed, and move point there (@code{semantic-complete-jump}).
1460: 
1461: @item C-c , @key{SPC}
1462: @kindex C-c , SPC
1463: Display a list of possible completions for the symbol at point
1464: (@code{semantic-complete-analyze-inline}).  This also activates a set
1465: of special key bindings for choosing a completion: @kbd{@key{RET}}
1466: accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through
1467: possible completions, @kbd{@key{TAB}} completes as far as possible and
1468: then cycles, and @kbd{C-g} or any other key aborts completion.
1469: 
1470: @item C-c , l
1471: @kindex C-c , l
1472: Display a list of the possible completions of the symbol at point, in
1473: another window (@code{semantic-analyze-possible-completions}).
1474: @end table
1475: 
1476: @noindent
1477: In addition to the above commands, the Semantic package provides a
1478: variety of other ways to make use of parser information.  For
1479: instance, you can use it to display a list of completions when Emacs
1480: is idle.
1481: @ifnottex
1482: @xref{Top, Semantic,, semantic, Semantic}, for details.
1483: @end ifnottex
1484: 
1485: @node Misc for Programs
1486: @section Other Features Useful for Editing Programs
1487: 
1488:   Some Emacs commands that aren't designed specifically for editing
1489: programs are useful for that nonetheless.
1490: 
1491:   The Emacs commands that operate on words, sentences and paragraphs
1492: are useful for editing code.  Most symbol names contain words
1493: (@pxref{Words}), while sentences can be found in strings and comments
1494: (@pxref{Sentences}).  As for paragraphs, they are defined in most
1495: programming language modes to begin and end at blank lines
1496: (@pxref{Paragraphs}).  Therefore, judicious use of blank lines to make
1497: the program clearer will also provide useful chunks of text for the
1498: paragraph commands to work on.  Auto Fill mode, if enabled in a
1499: programming language major mode, indents the new lines which it
1500: creates.
1501: 
1502: @findex superword-mode
1503:  Superword mode is a buffer-local minor mode that causes editing and
1504: motion commands to treat symbols (e.g., @samp{this_is_a_symbol}) as words.
1505: When Superword mode is enabled, the minor mode indicator
1506: @iftex
1507: @samp{@math{^2}}
1508: @end iftex
1509: @ifnottex
1510: @samp{²}
1511: @end ifnottex
1512: appears in the mode line.  See also the similar @code{subword-mode}
1513: (@pxref{MixedCase Words}).
1514: 
1515: @findex electric-layout-mode
1516:   Electric Layout mode (@kbd{M-x electric-layout-mode}) is a global
1517: minor mode that automatically inserts newlines when you type certain
1518: characters; for example, @samp{@{}, @samp{@}} and @samp{;} in Javascript
1519: mode.
1520: 
1521:   Apart from Hideshow mode (@pxref{Hideshow}), another way to
1522: selectively display parts of a program is to use the selective display
1523: feature (@pxref{Selective Display}).  Programming modes often also
1524: support Outline minor mode (@pxref{Outline Mode}), which can be used
1525: with the Foldout package (@pxref{Foldout}).
1526: 
1527: @ifinfo
1528:   The automatic typing features may be useful for writing programs.
1529: @xref{Top,,Autotyping, autotype, Autotyping}.
1530: @end ifinfo
1531: 
1532: @findex prettify-symbols-mode
1533:   Prettify Symbols mode is a buffer-local minor mode that replaces
1534: certain strings with more attractive versions for display purposes.
1535: For example, in Emacs Lisp mode, it replaces the string @samp{lambda}
1536: with the Greek lambda character @samp{λ}.  In a @TeX{} buffer, it will
1537: replace @samp{\alpha} @dots{} @samp{\omega} and other math macros with
1538: their Unicode characters.  You may wish to use this in non-programming
1539: modes as well.  You can customize the mode by adding more entries to
1540: @code{prettify-symbols-alist}.  More elaborate customization is
1541: available via customizing @code{prettify-symbols-compose-predicate} if
1542: its default value @code{prettify-symbols-default-compose-p} is not
1543: appropriate.  There is also a global version,
1544: @code{global-prettify-symbols-mode}, which enables the mode in all
1545: buffers that support it.
1546: 
1547:   The symbol at point can be shown in its original form.  This is
1548: controlled by the variable @code{prettify-symbols-unprettify-at-point}:
1549: if non-@code{nil}, the original form of symbol at point will be
1550: restored for as long as point is at it.
1551: 
1552: 
1553: @node C Modes
1554: @section C and Related Modes
1555: @cindex C mode
1556: @cindex Java mode
1557: @cindex Pike mode
1558: @cindex IDL mode
1559: @cindex CORBA IDL mode
1560: @cindex Objective C mode
1561: @cindex C++ mode
1562: @cindex AWK mode
1563: @cindex mode, Java
1564: @cindex mode, C
1565: @cindex mode, C++
1566: @cindex mode, Objective C
1567: @cindex mode, CORBA IDL
1568: @cindex mode, Pike
1569: @cindex mode, AWK
1570: 
1571:   This section gives a brief description of the special features
1572: available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes.
1573: (These are called ``C mode and related modes''.)
1574: @ifinfo
1575: @xref{Top,, CC Mode, ccmode, CC Mode}, for more details.
1576: @end ifinfo
1577: @ifnotinfo
1578: For more details, see the CC mode Info manual, which is distributed
1579: with Emacs.
1580: @end ifnotinfo
1581: 
1582: @menu
1583: * Motion in C::                 Commands to move by C statements, etc.
1584: * Electric C::                  Colon and other chars can automatically reindent.
1585: * Hungry Delete::               A more powerful DEL command.
1586: * Other C Commands::            Filling comments, viewing expansion of macros,
1587:                                 and other neat features.
1588: @end menu
1589: 
1590: @node Motion in C
1591: @subsection C Mode Motion Commands
1592: 
1593:   This section describes commands for moving point, in C mode and
1594: related modes.
1595: 
1596: @table @code
1597: @item C-M-a
1598: @itemx C-M-e
1599: @findex c-beginning-of-defun
1600: @findex c-end-of-defun
1601: Move point to the beginning or end of the current function or
1602: top-level definition.  In languages with enclosing scopes (such as
1603: C++'s classes) the @dfn{current function} is the immediate one,
1604: possibly inside a scope.  Otherwise it is the one defined by the least
1605: enclosing braces.  (By contrast, @code{beginning-of-defun} and
1606: @code{end-of-defun} search for braces in column zero.)  @xref{Moving
1607: by Defuns}.
1608: 
1609: @item C-c C-u
1610: @kindex C-c C-u @r{(C mode)}
1611: @findex c-up-conditional
1612: Move point back to the containing preprocessor conditional, leaving the
1613: mark behind.  A prefix argument acts as a repeat count.  With a negative
1614: argument, move point forward to the end of the containing
1615: preprocessor conditional.
1616: 
1617: @samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so
1618: the function will stop at a @samp{#elif} when going backward, but not
1619: when going forward.
1620: 
1621: @item C-c C-p
1622: @kindex C-c C-p @r{(C mode)}
1623: @findex c-backward-conditional
1624: Move point back over a preprocessor conditional, leaving the mark
1625: behind.  A prefix argument acts as a repeat count.  With a negative
1626: argument, move forward.
1627: 
1628: @item C-c C-n
1629: @kindex C-c C-n @r{(C mode)}
1630: @findex c-forward-conditional
1631: Move point forward across a preprocessor conditional, leaving the mark
1632: behind.  A prefix argument acts as a repeat count.  With a negative
1633: argument, move backward.
1634: 
1635: @item M-a
1636: @kindex M-a @r{(C mode)}
1637: @findex c-beginning-of-statement
1638: Move point to the beginning of the innermost C statement
1639: (@code{c-beginning-of-statement}).  If point is already at the beginning
1640: of a statement, move to the beginning of the preceding statement.  With
1641: prefix argument @var{n}, move back @var{n} @minus{} 1 statements.
1642: 
1643: In comments or in strings which span more than one line, this command
1644: moves by sentences instead of statements.
1645: 
1646: @item M-e
1647: @kindex M-e @r{(C mode)}
1648: @findex c-end-of-statement
1649: Move point to the end of the innermost C statement or sentence; like
1650: @kbd{M-a} except that it moves in the other direction
1651: (@code{c-end-of-statement}).
1652: @end table
1653: 
1654: @node Electric C
1655: @subsection Electric C Characters
1656: 
1657:   In C mode and related modes, certain printing characters are
1658: @dfn{electric}---in addition to inserting themselves, they also
1659: reindent the current line, and optionally also insert newlines.  The
1660: electric characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#},
1661: @kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and
1662: @kbd{)}.
1663: 
1664:   You might find electric indentation inconvenient if you are editing
1665: chaotically indented code.  If you are new to CC Mode, you might find
1666: it disconcerting.  You can toggle electric action with the command
1667: @kbd{C-c C-l}; when it is enabled, @samp{/@var{c}l} appears in the
1668: mode line after the mode name (where @var{c}, if present, is @samp{*}
1669: or @samp{/}, depending on whether the comment style is block or line).
1670: @xref{Minor Modes,,, ccmode, The CC Mode Manual}, for more about
1671: mode-line indicators in CC Mode.
1672: 
1673: @table @kbd
1674: @item C-c C-l
1675: @kindex C-c C-l @r{(C mode)}
1676: @findex c-toggle-electric-state
1677: Toggle electric action (@code{c-toggle-electric-state}).  With a
1678: positive prefix argument, this command enables electric action, with a
1679: negative one it disables it.
1680: @end table
1681: 
1682:   Electric characters insert newlines only when, in addition to the
1683: electric state, the @dfn{auto-newline} feature is enabled (indicated
1684: by @samp{/@var{c}la} in the mode line after the mode name).  You can
1685: turn this feature on or off with the command @kbd{C-c C-a}:
1686: 
1687: @table @kbd
1688: @item C-c C-a
1689: @kindex C-c C-a @r{(C mode)}
1690: @findex c-toggle-auto-newline
1691: Toggle the auto-newline feature (@code{c-toggle-auto-newline}).  With a
1692: prefix argument, this command turns the auto-newline feature on if the
1693: argument is positive, and off if it is negative.
1694: @end table
1695: 
1696:   Usually the CC Mode style configures the exact circumstances in
1697: which Emacs inserts auto-newlines.  You can also configure this
1698: directly.  @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}.
1699: 
1700: @node Hungry Delete
1701: @subsection Hungry Delete Feature in C
1702: @cindex hungry deletion (C Mode)
1703: 
1704:   If you want to delete an entire block of whitespace at point, you
1705: can use @dfn{hungry deletion}.  This deletes all the contiguous
1706: whitespace either before point or after point in a single operation.
1707: @dfn{Whitespace} here includes tabs and newlines, but not comments or
1708: preprocessor commands.
1709: 
1710: @table @kbd
1711: @item C-c C-@key{DEL}
1712: @itemx C-c @key{DEL}
1713: @findex c-hungry-delete-backwards
1714: @kindex C-c C-DEL @r{(C Mode)}
1715: @kindex C-c DEL @r{(C Mode)}
1716: Delete the entire block of whitespace preceding point (@code{c-hungry-delete-backwards}).
1717: 
1718: @item C-c C-d
1719: @itemx C-c C-@key{Delete}
1720: @itemx C-c @key{Delete}
1721: @findex c-hungry-delete-forward
1722: @kindex C-c C-d @r{(C Mode)}
1723: @kindex C-c C-Delete @r{(C Mode)}
1724: @kindex C-c Delete @r{(C Mode)}
1725: Delete the entire block of whitespace after point (@code{c-hungry-delete-forward}).
1726: @end table
1727: 
1728:   As an alternative to the above commands, you can enable @dfn{hungry
1729: delete mode}.  When this feature is enabled (indicated by @samp{h}
1730: after a @samp{/} in the mode line after the mode name), a single
1731: @kbd{@key{DEL}} deletes all preceding whitespace, not just one space,
1732: and a single @kbd{C-d} (but @emph{not} plain @kbd{@key{Delete}})
1733: deletes all following whitespace.
1734: 
1735: @table @kbd
1736: @item M-x c-toggle-hungry-state
1737: @findex c-toggle-hungry-state
1738: Toggle the hungry-delete feature
1739: (@code{c-toggle-hungry-state}).  With a prefix argument,
1740: this command turns the hungry-delete feature on if the argument is
1741: positive, and off if it is negative.
1742: @end table
1743: 
1744: @vindex c-hungry-delete-key
1745:    The variable @code{c-hungry-delete-key} controls whether the
1746: hungry-delete feature is enabled.
1747: 
1748: @node Other C Commands
1749: @subsection Other Commands for C Mode
1750: 
1751: @table @kbd
1752: @item M-x c-context-line-break
1753: @findex c-context-line-break
1754: This command inserts a line break and indents the new line in a manner
1755: appropriate to the context.  In normal code, it does the work of
1756: @kbd{@key{RET}} (@code{newline}), in a C preprocessor line it additionally
1757: inserts a @samp{\} at the line break, and within comments it's like
1758: @kbd{M-j} (@code{c-indent-new-comment-line}).
1759: 
1760: @code{c-context-line-break} isn't bound to a key by default, but it
1761: needs a binding to be useful.  The following code will bind it to
1762: @kbd{@key{RET}}.  We use @code{c-initialization-hook} here to make
1763: sure the keymap is loaded before we try to change it.
1764: 
1765: @example
1766: (defun my-bind-clb ()
1767:   (define-key c-mode-base-map "\C-m"
1768:               'c-context-line-break))
1769: (add-hook 'c-initialization-hook 'my-bind-clb)
1770: @end example
1771: 
1772: @item C-M-h
1773: Put mark at the end of a function definition, and put point at the
1774: beginning (@code{c-mark-function}).
1775: 
1776: @item M-q
1777: @kindex M-q @r{(C mode)}
1778: @findex c-fill-paragraph
1779: Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}).
1780: If any part of the current line is a comment or within a comment, this
1781: command fills the comment or the paragraph of it that point is in,
1782: preserving the comment indentation and comment delimiters.
1783: 
1784: @item C-c C-e
1785: @cindex macro expansion in C
1786: @cindex expansion of C macros
1787: @findex c-macro-expand
1788: @kindex C-c C-e @r{(C mode)}
1789: Run the C preprocessor on the text in the region, and show the result,
1790: which includes the expansion of all the macro calls
1791: (@code{c-macro-expand}).  The buffer text before the region is also
1792: included in preprocessing, for the sake of macros defined there, but the
1793: output from this part isn't shown.
1794: 
1795: When you are debugging C code that uses macros, sometimes it is hard to
1796: figure out precisely how the macros expand.  With this command, you
1797: don't have to figure it out; you can see the expansions.
1798: 
1799: @item C-c C-\
1800: @findex c-backslash-region
1801: @kindex C-c C-\ @r{(C mode)}
1802: Insert or align @samp{\} characters at the ends of the lines of the
1803: region (@code{c-backslash-region}).  This is useful after writing or
1804: editing a C macro definition.
1805: 
1806: If a line already ends in @samp{\}, this command adjusts the amount of
1807: whitespace before it.  Otherwise, it inserts a new @samp{\}.  However,
1808: the last line in the region is treated specially; no @samp{\} is
1809: inserted on that line, and any @samp{\} there is deleted.
1810: 
1811: @item M-x cpp-highlight-buffer
1812: @cindex preprocessor highlighting
1813: @findex cpp-highlight-buffer
1814: Highlight parts of the text according to its preprocessor conditionals.
1815: This command displays another buffer named @file{*CPP Edit*}, which
1816: serves as a graphic menu for selecting how to display particular kinds
1817: of conditionals and their contents.  After changing various settings,
1818: click on @samp{[A]pply these settings} (or go to that buffer and type
1819: @kbd{a}) to rehighlight the C mode buffer accordingly.
1820: 
1821: @item C-c C-s
1822: @findex c-show-syntactic-information
1823: @kindex C-c C-s @r{(C mode)}
1824: Display the syntactic information about the current source line
1825: (@code{c-show-syntactic-information}).  This information directs how
1826: the line is indented.
1827: 
1828: @item M-x cwarn-mode
1829: @itemx M-x global-cwarn-mode
1830: @findex cwarn-mode
1831: @findex global-cwarn-mode
1832: @vindex global-cwarn-mode
1833: @cindex CWarn mode
1834: @cindex suspicious constructions in C, C++
1835: CWarn minor mode highlights certain suspicious C and C++ constructions:
1836: 
1837: @itemize @bullet{}
1838: @item
1839: Assignments inside expressions.
1840: @item
1841: Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while}
1842: (except after a @samp{do @dots{} while} statement);
1843: @item
1844: C++ functions with reference parameters.
1845: @end itemize
1846: 
1847: @noindent
1848: You can enable the mode for one buffer with the command @kbd{M-x
1849: cwarn-mode}, or for all suitable buffers with the command @kbd{M-x
1850: global-cwarn-mode} or by customizing the variable
1851: @code{global-cwarn-mode}.  You must also enable Font Lock mode to make
1852: it work.
1853: 
1854: @item M-x hide-ifdef-mode
1855: @findex hide-ifdef-mode
1856: @cindex Hide-ifdef mode
1857: @vindex hide-ifdef-shadow
1858: Hide-ifdef minor mode hides selected code within @samp{#if} and
1859: @samp{#ifdef} preprocessor blocks.  If you change the variable
1860: @code{hide-ifdef-shadow} to @code{t}, Hide-ifdef minor mode
1861: shadows preprocessor blocks by displaying them with a less
1862: prominent face, instead of hiding them entirely.  See the
1863: documentation string of @code{hide-ifdef-mode} for more information.
1864: 
1865: @item M-x ff-find-related-file
1866: @cindex related files
1867: @findex ff-find-related-file
1868: @vindex ff-related-file-alist
1869: Find a file related in a special way to the file visited by the
1870: current buffer.  Typically this will be the header file corresponding
1871: to a C/C++ source file, or vice versa.  The variable
1872: @code{ff-related-file-alist} specifies how to compute related file
1873: names.
1874: @end table
1875: 
1876: @node Asm Mode
1877: @section Asm Mode
1878: 
1879: @cindex Asm mode
1880: @cindex assembler mode
1881: Asm mode is a major mode for editing files of assembler code.  It
1882: defines these commands:
1883: 
1884: @table @kbd
1885: @item @key{TAB}
1886: @code{tab-to-tab-stop}.
1887: @c FIXME: Maybe this should be consistent with other programming modes.
1888: 
1889: @item C-j
1890: Insert a newline and then indent using @code{tab-to-tab-stop}.
1891: 
1892: @item :
1893: Insert a colon and then remove the indentation from before the label
1894: preceding colon.  Then do @code{tab-to-tab-stop}.
1895: 
1896: @item ;
1897: Insert or align a comment.
1898: @end table
1899: 
1900:   The variable @code{asm-comment-char} specifies which character
1901: starts comments in assembler syntax.
1902: 
1903: @ifnottex
1904: @include fortran-xtra.texi
1905: @end ifnottex
1906: