Mercurial > emacs
changeset 84188:f18225c263a7
Move to ../doc/emacs/, misc/
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:39:33 +0000 |
| parents | d9a59393078c |
| children | 3adfc25d5a81 |
| files | man/programs.texi |
| diffstat | 1 files changed, 0 insertions(+), 1773 deletions(-) [+] |
line wrap: on
line diff
--- a/man/programs.texi Thu Sep 06 04:39:28 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1773 +0,0 @@ -@c This is part of the Emacs manual. -@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, -@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. -@c See file emacs.texi for copying conditions. -@node Programs, Building, Text, Top -@chapter Editing Programs -@cindex Lisp editing -@cindex C editing -@cindex program editing - - Emacs provides many features to facilitate editing programs. Some -of these features can - -@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 - - This chapter describes these features and many more. - -@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. -* Glasses:: Making identifiersLikeThis more readable. -* Misc for Programs:: Other Emacs features useful for editing programs. -* C Modes:: Special commands of C, C++, Objective-C, - Java, and Pike 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 for various programming languages. -@xref{Major Modes}. A programming language major 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 of a function definition. It often customizes -or provides facilities for compiling and debugging programs as well. - - Ideally, Emacs should provide a major mode for each programming -language that you might want to edit; if it doesn't have a mode for -your favorite language, you can contribute one. But often the mode -for one language can serve for other syntactically similar languages. -The major mode for language @var{l} is called @code{@var{l}-mode}, -and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}. -@xref{Choosing Modes}. - -@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 Simula mode -@cindex VHDL mode -@cindex M4 mode -@cindex Shell-script mode -@cindex Delphi mode -@cindex PostScript mode -@cindex Conf mode -@cindex DNS mode - The existing programming language major modes include Lisp, Scheme (a -variant of Lisp) and the Scheme-based DSSSL expression language, Ada, -ASM, AWK, C, C++, Delphi (Object Pascal), Fortran (free format and fixed -format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s -companion for font creation), Modula2, Objective-C, Octave, Pascal, -Perl, Pike, PostScript, Prolog, Python, Simula, Tcl, and VHDL. An -alternative mode for Perl is called CPerl mode. Modes are available for -the scripting languages of the common GNU and Unix shells, VMS DCL, and -MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for -editing makefiles, DNS master files, and various sorts of configuration -files. - -@kindex DEL @r{(programming modes)} -@findex c-electric-backspace - In most programming languages, indentation should vary from line to -line to illustrate the structure of the program. So the major modes -for programming languages arrange for @key{TAB} to update the -indentation of the current line. They also rebind @key{DEL} to treat -a tab as if it were the equivalent number of spaces; this lets you -delete one column of indentation without worrying whether the -whitespace consists of spaces or tabs. Use @kbd{C-b C-d} to delete a -tab character before point, in these modes. - - 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}) and the IDLWAVE modes -(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). For Fortran -mode, see -@iftex -@ref{Fortran,,, emacs-xtra, Specialized Emacs Features}. -@end iftex -@ifnottex -@ref{Fortran}. -@end ifnottex - - -@cindex mode hook -@vindex c-mode-hook -@vindex lisp-mode-hook -@vindex emacs-lisp-mode-hook -@vindex lisp-interaction-mode-hook -@vindex scheme-mode-hook - Turning on a major mode runs a normal hook called the @dfn{mode -hook}, which is the value of a Lisp variable. Each major mode has a -mode hook, and the hook's name is always made from the mode command's -name by adding @samp{-hook}. For example, turning on C mode runs the -hook @code{c-mode-hook}, while turning on Lisp mode runs the hook -@code{lisp-mode-hook}. The purpose of the mode hook is to give you a -place to set up customizations for that major mode. @xref{Hooks}. - -@node Defuns -@section Top-Level Definitions, or Defuns - - In Emacs, a major definition at the top level in the buffer, -something like a function, is called a @dfn{defun}. The name comes -from Lisp, but in Emacs we use it for all languages. - -@menu -* Left Margin Paren:: An open-paren or similar opening delimiter - starts a defun if it is at the left margin. -* Moving by Defuns:: Commands to move over or mark a major definition. -* Imenu:: Making buffer indexes as menus. -* Which Function:: Which Function mode shows which function you are in. -@end menu - -@node Left Margin Paren -@subsection Left Margin Convention - -@cindex open-parenthesis in leftmost column -@cindex ( in leftmost column - Emacs assumes by default that any opening delimiter found at the -left margin is the start of a top-level definition, or defun. -Therefore, @strong{don't put an opening delimiter at the left margin -unless it should have that significance}. For instance, never put an -open-parenthesis at the left margin in a Lisp file unless it is the -start of a top-level list. - - If you don't follow this convention, not only will you have trouble -when you explicitly use the commands for motion by defuns; other -features that use them will also give you trouble. This includes -the indentation commands (@pxref{Program Indent}) and Font Lock -mode (@pxref{Font Lock}). - - The most likely problem case is when you want an opening delimiter -at the start of a line inside a string. To avoid trouble, put an -escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some -other Lisp dialects) before the opening delimiter. This will not -affect the contents of the string, but will prevent that opening -delimiter from starting a defun. Here's an example: - -@example - (insert "Foo: -\(bar) -") -@end example - - To help you catch violations of this convention, Font Lock mode -highlights confusing opening delimiters (those that ought to be -quoted) in bold red. - -If you need to override this convention, you can so by setting this -user option: - -@defvar open-paren-in-column-0-is-defun-start -If this user option is set to @code{t} (the default), opening -parentheses or braces at column zero always start defuns. When it's -@code{nil}, defuns are found by searching for parens or braces at the -outermost level. -@end defvar - - Usually, you shouldn't need to set -@code{open-paren-in-column-0-is-defun-start} to @code{nil}. However, -if your buffer contains parentheses or braces in column zero which -don't start defuns and this confuses Emacs, it sometimes helps to set -the option to @code{nil}. Be aware, though, that this will make -scrolling and display in large buffers quite sluggish, and that -parentheses and braces must be correctly matched throughout the buffer -for it to work properly. - - In the earliest days, the original Emacs found defuns by moving -upward a level of parentheses or braces until there were no more -levels to go up. This always required scanning all the way back to -the beginning of the buffer, even for a small function. To speed up -the operation, we changed Emacs to assume that any opening delimiter -at the left margin is the start of a defun. This heuristic is nearly -always right, and avoids the need to scan back to the beginning of the -buffer. However, now that modern computers are so powerful, this -scanning is rarely slow enough to annoy, so we've provided a way to -disable the heuristic. - -@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 puts point at the beginning and mark at the end of the current -defun. 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 you use the -command while point is between defuns, it uses the following defun. -Successive uses of @kbd{C-M-h}, or using it in Transient Mark mode -when the mark is active, extends the end of the region to include one -more defun each time. - - In C mode, @kbd{C-M-h} runs the function @code{c-mark-function}, -which is almost the same as @code{mark-defun}; the difference is that -it backs up over the argument declarations, function name and returned -data type so that the entire C function is inside the region. This is -an example of how major modes adjust the standard key bindings so that -they do their standard jobs in a way better fitting a particular -language. Other major modes may replace any or all of these key -bindings for that purpose. - -@node Imenu -@subsection Imenu -@cindex index of buffer definitions -@cindex buffer definitions index -@cindex tags - - The Imenu facility offers a way to find the major definitions in -a file by name. It is also useful in text formatter major modes, -where it treats each chapter, section, etc., as a definition. -(@xref{Tags}, for a more powerful feature that handles multiple files -together.) - -@findex imenu - If you type @kbd{M-x imenu}, it reads the name of a definition using -the minibuffer, then moves point to that definition. You can use -completion to specify the name; the command always displays the whole -list of valid names. - -@findex imenu-add-menubar-index - Alternatively, you can bind the command @code{imenu} to a mouse -click. Then it displays mouse menus for you to select a definition -name. You can also add the buffer's index to the menu bar by calling -@code{imenu-add-menubar-index}. If you want to have this menu bar -item available for all buffers in a certain major mode, you can do -this by adding @code{imenu-add-menubar-index} to its mode hook. But -if you have done that, you will have to wait a little while each time -you visit a file in that mode, while Emacs finds all the definitions -in that buffer. - -@vindex imenu-auto-rescan - When you change the contents of a buffer, if you add or delete -definitions, you can update the buffer's index based on the -new contents by invoking the @samp{*Rescan*} item in the menu. -Rescanning happens automatically if you set @code{imenu-auto-rescan} to -a non-@code{nil} value. There is no need to rescan because of small -changes in the text. - -@vindex imenu-sort-function - You can customize the way the menus are sorted by setting the -variable @code{imenu-sort-function}. By default, names are ordered as -they occur in the buffer; if you want alphabetic sorting, use the -symbol @code{imenu--sort-by-name} as the value. You can also -define your own comparison function by writing Lisp code. - - Imenu provides the information to guide Which Function mode -@ifnottex -(@pxref{Which Function}). -@end ifnottex -@iftex -(see below). -@end iftex -The Speedbar can also use it (@pxref{Speedbar}). - -@node Which Function -@subsection Which Function Mode -@cindex current function name in mode line - - Which Function mode is a minor mode that displays the current -function name in the mode line, updating it as you move around in a -buffer. - -@findex which-function-mode -@vindex which-func-modes - To either enable or disable Which Function mode, use the command -@kbd{M-x which-function-mode}. This command is global; it applies to -all buffers, both existing ones and those yet to be created. However, -it takes effect only in certain major modes, those listed in the value -of @code{which-func-modes}. If the value is @code{t}, then Which -Function mode applies to all major modes that know how to support -it---in other words, all the major modes that support Imenu. - -@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 properly -either a single line, a specified number of lines, or all of the lines -inside a single parenthetical grouping. - -@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 library @code{pp}. -This program reformats a Lisp object with indentation chosen to look nice. - -@node Basic Indent -@subsection Basic Program Indentation Commands - - The basic indentation commands indent a single line according to the -usual conventions of the language you are editing. - -@need 1000 -@table @kbd -@item @key{TAB} -Adjust indentation of current line. -@item C-j -Insert a newline, then adjust indentation of following line -(@code{newline-and-indent}). -@end table - -@kindex TAB @r{(programming modes)} -@findex c-indent-command -@findex indent-line-function -@findex indent-for-tab-command - The basic indentation command is @key{TAB}, which gives the current line -the correct indentation as determined from the previous lines. The -function that @key{TAB} runs depends on the major mode; it is -@code{lisp-indent-line} -in Lisp mode, @code{c-indent-command} in C mode, etc. These functions -understand the syntax and conventions of different languages, but they all do -conceptually the same job: @key{TAB} in any programming-language major mode -inserts or deletes whitespace at the beginning of the current line, -independent of where point is in the line. If point was inside the -whitespace at the beginning of the line, @key{TAB} puts it at the end of -that whitespace; otherwise, @key{TAB} keeps point fixed with respect to -the characters around it. - - Use @kbd{C-q @key{TAB}} to insert a tab character at point. - -@kindex C-j -@findex newline-and-indent - When entering lines of new code, use @kbd{C-j} -(@code{newline-and-indent}), which inserts a newline and then adjusts -indentation after it. (It also deletes any trailing whitespace which -remains before the new newline.) Thus, @kbd{C-j} at the end of a line -creates a blank line with appropriate indentation. In programming -language modes, it is equivalent to @key{RET} @key{TAB}. - - @key{TAB} indents a line that starts within a parenthetical grouping -under the preceding line within the grouping, or the text after the -parenthesis. Therefore, if you manually give one of these lines a -nonstandard indentation, the lines below will tend to follow it. This -behavior is convenient in cases where you have overridden the standard -result of @key{TAB} because you find it unaesthetic for a particular -line. - - In some modes, an open-parenthesis, open-brace or other opening -delimiter at the left margin is assumed by Emacs (including the -indentation routines) to be the start of a function. This speeds up -indentation commands. If you will be editing text which contains -opening delimiters in column zero that aren't the beginning of a -functions, even inside strings or comments, you must set -@code{open-paren-in-column-0-is-defun-start}. @xref{Left Margin -Paren}, for more information on this. - - Normally, lines are indented with tabs and spaces. If you want Emacs -to use spaces only, set @code{indent-tabs-mode} (@pxref{Just Spaces}). - -@node Multi-line Indent -@subsection Indenting Several Lines - - When you wish to reindent several lines of code which have been -altered or moved to a different level in the parenthesis structure, -you have several commands available. - -@table @kbd -@item C-M-q -Reindent all the lines within one parenthetical grouping (@code{indent-pp-sexp}). -@item C-M-\ -Reindent all lines in the region (@code{indent-region}). -@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 - You can reindent the contents of a single parenthetical grouping by -positioning point before the beginning of it and typing @kbd{C-M-q} -(@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode; also -bound to other suitable commands in other modes). The indentation of -the line where the grouping starts is not changed; therefore this -changes only the relative indentation within the grouping, not its -overall indentation. To correct that as well, type @key{TAB} first. - - Another way to specify the range to be reindented is with the -region. The command @kbd{C-M-\} (@code{indent-region}) applies -@key{TAB} to every line whose first character is between point and -mark. - -@kindex C-u TAB - If you like the relative indentation within a grouping, but not the -indentation of its first line, you can type @kbd{C-u @key{TAB}} to -reindent the whole grouping as a rigid unit. (This works in Lisp -modes and C and related modes.) @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 - You can also perform this operation on the region, using the command -@kbd{M-x indent-code-rigidly}. It 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. Normally you would use this for macro definitions -and specify it using the @code{declare} construct (@pxref{Defining -Macros,,, elisp, the Emacs Lisp Reference Manual}). - -@node C Indent -@subsection Commands for C Indentation - - Here are special features for indentation in C mode and related modes: - -@table @code -@item C-c C-q -@kindex C-c C-q @r{(C mode)} -@findex c-indent-defun -Reindent the current top-level function definition or aggregate type -declaration (@code{c-indent-defun}). - -@item C-M-q -@kindex C-M-q @r{(C mode)} -@findex c-indent-exp -Reindent each line in the balanced expression that follows point -(@code{c-indent-exp}). A prefix argument inhibits warning messages -about invalid syntax. - -@item @key{TAB} -@findex c-indent-command -Reindent the current line, and/or in some cases insert a tab character -(@code{c-indent-command}). - -@vindex c-tab-always-indent -If @code{c-tab-always-indent} is @code{t}, this command always reindents -the current line and does nothing else. This is the default. - -If that variable is @code{nil}, this command reindents the current line -only if point is at the left margin or in the line's indentation; -otherwise, it inserts a tab (or the equivalent number of spaces, -if @code{indent-tabs-mode} is @code{nil}). - -Any other value (not @code{nil} or @code{t}) means always reindent the -line, and also insert a tab if within a comment or a string. -@end table - - To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This -first selects the whole buffer as the region, then reindents that -region. - - To reindent the current block, use @kbd{C-M-u C-M-q}. This moves -to the front of the block and then reindents it all. - -@node Custom C Indent -@subsection Customizing C Indentation -@cindex style (for indentation) - - C mode and related modes use a flexible mechanism for customizing -indentation. C mode indents a source line in two steps: first it -classifies the line syntactically according to its contents and -context; second, it determines the indentation offset associated by -your selected @dfn{style} with the syntactic construct and adds this -onto the indentation of the @dfn{anchor statement}. - -@table @kbd -@item C-c . @key{RET} @var{style} @key{RET} -Select a predefined style @var{style} (@code{c-set-style}). -@end table - - A @dfn{style} is a named collection of customizations that can be -used in C mode and the related modes. @ref{Styles,,, ccmode, The CC -Mode Manual}, for a complete description. Emacs comes with several -predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, -@code{stroustrup}, @code{linux}, @code{python}, @code{java}, -@code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these -styles are primarily intended for one language, but any of them can be -used with any of the languages supported by these modes. To find out -what a style looks like, select it and reindent some code, e.g., by -typing @key{C-M-q} at the start of a function definition. - -@kindex C-c . @r{(C mode)} -@findex c-set-style - To choose a style for the current buffer, use the command @w{@kbd{C-c -.}}. Specify a style name as an argument (case is not significant). -This command affects the current buffer only, and it affects only -future invocations of the indentation commands; it does not reindent -the code already in the buffer. To reindent the whole buffer in the -new style, you can type @kbd{C-x h C-M-\}. - -@vindex c-default-style - You can also set the variable @code{c-default-style} to specify the -default style for various major modes. Its value should be either the -style's name (a string) or an alist, in which each element specifies -one major mode and which indentation style to use for it. For -example, - -@example -(setq c-default-style - '((java-mode . "java") (awk-mode . "awk") (other . "gnu"))) -@end example - -@noindent -specifies explicit choices for Java and AWK modes, and the default -@samp{gnu} style for the other C-like modes. (These settings are -actually the defaults.) This variable takes effect when you select -one of the C-like major modes; thus, if you specify a new default -style for Java mode, you can make it take effect in an existing Java -mode buffer by typing @kbd{M-x java-mode} there. - - The @code{gnu} style specifies the formatting recommended by the GNU -Project for C; it is the default, so as to encourage use of our -recommended style. - - @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and -@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more -information on customizing indentation for C and related modes, -including how to override parts of an existing style and how to define -your own styles. - -@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}). 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 - These commands deal with balanced expressions, also called -@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 - - Each programming language major mode customizes the definition of -balanced expressions to suit that language. Balanced expressions -typically include symbols, numbers, and string constants, as well as -any pair of matching delimiters and their contents. Some languages -have obscure forms of expression syntax that nobody has bothered to -implement in Emacs. - -@cindex Control-Meta - By convention, the keys for these commands are all Control-Meta -characters. They usually act on expressions just as the corresponding -Meta characters act on words. For instance, the command @kbd{C-M-b} -moves backward over a balanced expression, just as @kbd{M-b} moves -back over a word. - -@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 (@samp{(} in Lisp; @samp{(}, @samp{[} or -@samp{@{} in C), @kbd{C-M-f} moves past the matching closing -delimiter. If the character begins a symbol, string, or number, -@kbd{C-M-f} moves over that. - - The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a -balanced expression. The detailed rules are like those above for -@kbd{C-M-f}, but with directions reversed. If there are prefix -characters (single-quote, backquote and comma, in Lisp) preceding the -expression, @kbd{C-M-b} moves back over them as well. The balanced -expression commands move across comments as if they were whitespace, -in most modes. - - @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the -specified number of times; with a negative argument, it moves in the -opposite direction. - -@cindex killing expressions -@kindex C-M-k -@findex kill-sexp - Killing a whole balanced expression can be done with @kbd{C-M-k} -(@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f} -would move over. - -@cindex transposition of expressions -@kindex C-M-t -@findex transpose-sexps - A somewhat random-sounding command which is nevertheless handy is -@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous -balanced expression across the next one. An argument serves as a -repeat count, moving the previous expression over that many following -ones. A negative argument drags the previous balanced expression -backwards across those before it (thus canceling out the effect of -@kbd{C-M-t} with a positive argument). An argument of zero, rather -than doing nothing, transposes the balanced expressions ending at or -after point and the mark. - -@kindex C-M-@@ -@kindex C-M-@key{SPC} -@findex mark-sexp - To set the region around the next balanced expression in the buffer, -use @kbd{C-M-@@} (@code{mark-sexp}), which sets mark at the same place -that @kbd{C-M-f} would move to. @kbd{C-M-@@} takes arguments like -@kbd{C-M-f}. In particular, a negative argument is useful for putting -the mark at the beginning of the previous balanced expression. The -alias @kbd{C-M-@key{SPC}} is equivalent to @kbd{C-M-@@}. When you -repeat this command, or use it in Transient Mark mode when the mark is -active, it extends the end of the region by one sexp each time. - - In languages that use infix operators, such as C, it is not possible -to recognize all balanced expressions as such 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. Both @samp{foo + bar} and @samp{foo} are legitimate -choices for ``the expression following point'' when point is at the -@samp{f}, so the expression commands must perforce choose one or the -other to operate on. Note that @samp{(foo + bar)} is recognized as a -single expression in C mode, 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 Emacs commands for handling parenthetical groupings see nothing -except parentheses (or whatever characters must balance in the -language you are working with), and the escape characters that might -be used to quote those. They are mainly intended for editing -programs, but can be useful for editing any text that has parentheses. -They are sometimes called ``list'' commands because in Lisp these -groupings are lists. - -@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 over one (or @var{n}) -parenthetical groupings, skipping blithely over any amount of text -that doesn't include meaningful parentheses (symbols, strings, etc.). - -@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 Automatic Display Of Matching Parentheses -@cindex matching parentheses -@cindex parentheses, displaying matches - - The Emacs parenthesis-matching feature is designed to show -automatically how parentheses (and other matching delimiters) match in -the text. Whenever you type a self-inserting character that is a -closing delimiter, the cursor moves momentarily to 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 parenthesis match display: - - @code{blink-matching-paren} turns the feature on or off: @code{nil} -disables it, but the default is @code{t} to enable match display. - - @code{blink-matching-delay} says how many seconds to leave the -cursor on the matching opening delimiter, before bringing it back to -the real location of point; the default is 1, but on some systems it -is useful to specify a fraction of a second. - - @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, scanning stops, and nothing is displayed. -This is to prevent the scan for the matching delimiter from wasting -lots of time when there is no match. The default is 25600. - -@cindex Show Paren mode -@cindex highlighting matching parentheses -@findex show-paren-mode - Show Paren mode provides a more powerful kind of automatic matching. -Whenever point is after a closing delimiter, that delimiter and its -matching opening delimiter are both highlighted; otherwise, if point -is before an opening delimiter, the matching closing delimiter is -highlighted. (There is no need to highlight the opening delimiter in -that case, because the cursor appears on top of that character.) Use -the command @kbd{M-x show-paren-mode} to enable or disable this mode. - - Show Paren mode uses the faces @code{show-paren-match} and -@code{show-paren-mismatch} to highlight parentheses; you can customize -them to control how highlighting looks. @xref{Face Customization}. - -@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}). - -@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 comment commands in this table insert, kill and align comments. -They are described in this section and following sections. - -@table @asis -@item @kbd{M-;} -Insert or realign comment on current line; alternatively, comment or -uncomment the region (@code{comment-dwim}). -@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 @key{RET} followed by inserting and aligning a comment -(@code{comment-indent-new-line}). @xref{Multi-Line Comments}. -@item @kbd{M-x comment-region} -@itemx @kbd{C-c C-c} (in C-like modes) -Add or remove comment delimiters on 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. - - If there is no comment already on the line, @kbd{M-;} inserts a new -comment, aligned at a specific column called the @dfn{comment column}. -The new comment begins with the string Emacs thinks comments should -start with (the value of @code{comment-start}; see below). Point is -after that string, so you can insert the text of the comment right -away. If the major mode has specified a string to terminate comments, -@kbd{M-;} inserts that after point, to keep the syntax valid. - - If the text of the line extends past the comment column, this -command aligns the comment start string to a suitable boundary -(usually, at least one space is inserted). - - 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 it. (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 text inside the comment. - -@findex comment-kill -@kindex C-u M-; - @kbd{C-u M-;} kills any comment on the current line, along with the -whitespace before it. To reinsert the comment on another line, move -to the end of that line, do @kbd{C-y}, and then do @kbd{M-;} to -realign it. - - Note that @kbd{C-u M-;} is not a distinct key; it is @kbd{M-;} -(@code{comment-dwim}) with a prefix argument. That command is -programmed so that when it receives a prefix argument it calls -@code{comment-kill}. However, @code{comment-kill} is a valid command -in its own right, and you can bind it directly to a key if you wish. - - @kbd{M-;} does two other jobs when used with an active region in -Transient Mark mode (@pxref{Transient Mark}). Then it either adds or -removes comment delimiters on each line of the region. (If every line -is a comment, it removes comment delimiters from each; otherwise, it -adds comment delimiters to each.) If you are not using Transient Mark -mode, then you should use the commands @code{comment-region} and -@code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}), -or else enable Transient Mark mode momentarily (@pxref{Momentary Mark}). -A prefix argument used in these circumstances specifies how many -comment delimiters to add or how many to delete. - - Some major modes have special rules for aligning certain kinds of -comments in certain contexts. For example, in Lisp code, comments which -start with two semicolons are indented as if they were lines of code, -instead of at the comment column. Comments which start with three -semicolons are supposed to start at the left margin and are often used -for sectioning purposes. Emacs understands -these conventions by indenting a double-semicolon comment using @key{TAB}, -and by not changing the indentation of a triple-semicolon comment at all. - -@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 - - For C-like modes, you can configure the exact effect of @kbd{M-;} -more flexibly than for most buffers 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 comment-indent-new-line - - If you are typing a comment and wish to continue it on another line, -you can use the command @kbd{C-M-j} or @kbd{M-j} -(@code{comment-indent-new-line}). If @code{comment-multi-line} -(@pxref{Options for Comments}) is non-@code{nil}, it moves to a new -line within the comment. Otherwise it closes the comment and starts a -new comment on a new line. When Auto Fill mode is on, going past the -fill column while typing a comment causes the comment to be continued -in just this fashion. - -@kindex C-c C-c (C mode) -@findex comment-region - To turn existing lines into comment lines, use the @kbd{M-x -comment-region} command (or type @kbd{C-c C-c} in C-like modes). It -adds comment delimiters to the lines that start in the region, thus -commenting them out. With a negative argument, it does the -opposite---it deletes comment delimiters from the lines in the region. - - With a positive argument, @code{comment-region} duplicates the last -character of the comment start sequence it adds; the argument -specifies how many copies of the character to insert. Thus, in Lisp -mode, @kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. -Duplicating the comment delimiter is a way of calling attention to the -comment. It can also affect how the comment is aligned or indented. -In Lisp, for proper indentation, you should use an argument of two or -three, if between defuns; if within a defun, it must be three. - - 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 -@kindex C-x ; -@findex comment-set-column - The @dfn{comment column}, the column at which Emacs tries to place -comments, is stored in the variable @code{comment-column}. You can -set it to a number explicitly. Alternatively, the command @kbd{C-x ;} -(@code{comment-set-column}) sets the comment column to the column -point is at. @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. - - The variable @code{comment-column} is per-buffer: setting the variable -in the normal fashion affects only the current buffer, but there is a -default value which you can change with @code{setq-default}. -@xref{Locals}. Many major modes initialize this variable for the -current buffer. - -@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 is -@c This stops M-q from breaking the line inside that @code. -@code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces -after the @samp{/*} itself, and accepts C++ style 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} to begin it. The value of @code{comment-end} is -inserted after point, so that it will follow the text that you will -insert into the comment. When @code{comment-end} is non-empty, it -should start with a space. For example, in C mode, -@code{comment-start} has the value @w{@code{"/* "}} and -@code{comment-end} has the value @w{@code{" */"}}. - -@vindex comment-padding - The variable @code{comment-padding} specifies how many spaces -@code{comment-region} should insert on each line between the comment -delimiter and the line's original text. The default is 1, to insert -one space. @code{nil} means 0. Alternatively, @code{comment-padding} -can hold the actual string to insert. - -@vindex comment-multi-line - The variable @code{comment-multi-line} controls how @kbd{C-M-j} -(@code{indent-new-comment-line}) behaves when used inside a comment. -Specifically, when @code{comment-multi-line} is @code{nil}, the -command inserts a comment terminator, begins a new line, and finally -inserts a comment starter. Otherwise it does not insert the -terminator and starter, so it effectively continues the current -comment across multiple lines. In languages that allow multi-line -comments, the choice of value for this variable is a matter of taste. -The default for this variable depends on the major mode. - -@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, in Lisp mode, the indent hook -function bases its decision on how many semicolons begin an existing -comment, and on the code in the preceding lines. - -@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. -* Lisp Doc:: Looking up Emacs Lisp functions, etc. -@end menu - -@node Info Lookup -@subsection Info Documentation Lookup - -@findex info-lookup-symbol -@findex info-lookup-file -@kindex C-h S - For many major modes, that apply to languages that 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. - - The major mode determines where to look for documentation for the -symbol---which Info files to look in, and which indices to search. -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 manual 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 manual-entry - You can read the man page for an operating system command, library -function, or system call, with the @kbd{M-x man} command. It -runs the @code{man} program to format the man page; if the system -permits, it runs @code{man} asynchronously, so that you can keep on -editing while the page is being formatted. (On MS-DOS and MS-Windows -3, you cannot edit while Emacs waits for @code{man} to finish.) The -result goes in a buffer named @samp{*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 page 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 -multiple 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 manual-entry} prompts for the topic. For example, to -read the man page for the C library function @code{chmod} (as opposed -to a command of the same name), type @kbd{M-x manual-entry @key{RET} -chmod(2) @key{RET}}. (@code{chmod} is a system call, so it is in -section @samp{2}.) - -@vindex Man-switches - If you do not specify a section, the results depend on how the -@code{man} program works on your system. Some of them display only -the first man page they find. Others display all man pages that have -the specified name, so you can move between them with the @kbd{M-n} -and @kbd{M-p} keys@footnote{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. If you want this behavior, you -can add this option to the value of the variable @code{Man-switches}.}. -The mode line shows how many manual pages are present in the Man buffer. - -@vindex Man-fontify-manpage-flag - By default, Emacs highlights the text in man pages. For a long man -page, highlighting can take substantial time. You can turn off -highlighting of man pages by setting the variable -@code{Man-fontify-manpage-flag} to @code{nil}. - -@findex Man-fontify-manpage - If you insert the text of a man page into an Emacs buffer in some -other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to -perform the same conversions that @kbd{M-x manual-entry} does. - -@findex woman -@cindex manual pages, on MS-DOS/MS-Windows - An alternative way of reading manual pages is the @kbd{M-x woman} -command@footnote{The name of the command, @code{woman}, is an acronym -for ``w/o (without) man,'' since it doesn't use the @code{man} -program.}. Unlike @kbd{M-x man}, it does not run any external -programs to format and display the man pages; instead it does the job -in Emacs Lisp, so it works on systems such as MS-Windows, where the -@code{man} program (and other programs it uses) are not generally -available. - - @kbd{M-x woman} prompts for a name of a manual page, and provides -completion based on the list of manual pages that are installed on -your machine; the list of available manual pages is computed -automatically the first time you invoke @code{woman}. The word at -point in the current buffer is used to suggest the default for the -name the manual page. - - With a numeric argument, @kbd{M-x woman} recomputes the list of the -manual pages used for completion. 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. - - For more information about setting up and using @kbd{M-x woman}, see -@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan -Manual}. - -@node Lisp Doc -@subsection Emacs Lisp Documentation Lookup - - As you edit Lisp code to be run in Emacs, you can use the commands -@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v} -(@code{describe-variable}) to view documentation of functions and -variables that you want to use. These commands use the minibuffer to -read the name of a function or variable to document, and display the -documentation in a window. Their default arguments are based on the -code in the neighborhood of point. For @kbd{C-h f}, the default is -the function called in the innermost list containing point. @kbd{C-h -v} uses the symbol name around or adjacent to point as its default. - -@cindex Eldoc mode -@findex eldoc-mode - A more automatic but less powerful method is Eldoc mode. This minor -mode constantly displays in the echo area the argument list for the -function being called at point. (In other words, it finds the -function call that point is contained in, and displays the argument -list of that function.) If point is over a documented variable, it -shows the first line of the variable's docstring. Eldoc mode applies -in Emacs Lisp and Lisp Interaction modes, and perhaps a few others -that provide special support for looking up doc strings. Use the -command @kbd{M-x eldoc-mode} to enable or disable this feature. - -@node Hideshow -@section Hideshow minor mode - -@findex hs-minor-mode - Hideshow minor mode provides selective display of portions of a -program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode} -to enable or disable this mode, or add @code{hs-minor-mode} to the -mode hook for certain major modes in order to enable it automatically -for those modes. - - Just what constitutes a block depends on the major mode. In C mode -or C++ mode, they are delimited by braces, while in Lisp mode and -similar modes they are delimited by parentheses. Multi-line comments -also count as blocks. - -@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-minor-mode -@kindex C-c @@ C-h -@kindex C-c @@ C-s -@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 -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 -Either hide or show the current block (@code{hs-toggle-hiding}). -@item S-Mouse-2 -Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}). -@item C-c @@ C-M-h -Hide all top-level blocks (@code{hs-hide-all}). -@item C-c @@ C-M-s -Show everything in the buffer (@code{hs-show-all}). -@item 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 exist for customizing Hideshow mode. - -@table @code -@item hs-hide-comments-when-hiding-all -Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. - -@item hs-isearch-open -Specifies what kind of hidden blocks incremental search should make -visible. The value should be one of these four symbols: - -@table @code -@item code -Open only code blocks. -@item comment -Open only comments. -@item t -Open both code blocks and comments. -@item nil -Open neither code blocks nor comments. -@end table - -@item hs-special-modes-alist -A list of elements, each specifying how to initialize Hideshow -variables for one major mode. See the variable's documentation string -for more information. -@end table - -@node Symbol Completion -@section Completion for Symbol Names -@cindex completion (symbol names) - - In Emacs, completion is something you normally do in the minibuffer. -But one kind of completion is available in all buffers: completion for -symbol names. - -@kindex M-TAB - The character @kbd{M-@key{TAB}} runs a command to complete the -partial symbol before point against the set of meaningful symbol -names. This command inserts at point any additional characters that -it can determine from the partial name. - - If your window manager defines @kbd{M-@key{TAB}} to switch windows, -you can type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i} instead. -However, most window managers let you customize these shortcuts, and -we recommend that you change any that get in the way of use of Emacs. - - If the partial name in the buffer has multiple possible completions -that differ in the very next character, so that it is impossible to -complete even one more character, @kbd{M-@key{TAB}} displays a list of -all possible completions in another window. - -@cindex tags-based completion -@cindex Info index completion -@findex complete-symbol - In most programming language major modes, @kbd{M-@key{TAB}} runs the -command @code{complete-symbol}, which provides two kinds of completion. -Normally it does completion based on a tags table (@pxref{Tags}); with a -numeric argument (regardless of the value), it does completion based on -the names listed in the Info file indexes for your language. Thus, to -complete the name of a symbol defined in your own program, use -@kbd{M-@key{TAB}} with no argument; to complete the name of a standard -library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based -completion works only if there is an Info file for the standard library -functions of your language, and only if it is installed at your site. - -@cindex Lisp symbol completion -@cindex completion (Lisp symbols) -@findex lisp-complete-symbol - In Emacs-Lisp mode, the name space for completion normally consists of -nontrivial symbols present in Emacs---those that have function -definitions, values or properties. However, if there is an -open-parenthesis immediately before the beginning of the partial symbol, -only symbols with function definitions are considered as completions. -The command which implements this is @code{lisp-complete-symbol}. - - In Text mode and related modes, @kbd{M-@key{TAB}} completes words -based on the spell-checker's dictionary. @xref{Spelling}. - -@node Glasses -@section Glasses minor mode -@cindex Glasses mode -@cindex identifiers, making long ones readable -@cindex StudlyCaps, making them readable -@findex glasses-mode - - Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} -readable by altering the way they display. It knows two different -ways to do this: by displaying underscores between a lower-case letter -and the following capital letter, and by emboldening the capital -letters. It does not alter the buffer text, only the way they -display, so you can use it even on read-only buffers. You can use the -command @kbd{M-x glasses-mode} to enable or disable the mode in the -current buffer; you can also add @code{glasses-mode} to the mode hook -of the programming language major modes in which you normally want -to use Glasses mode. - -@node Misc for Programs -@section Other Features Useful for Editing Programs - - A number of 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 symbols names contain words -(@pxref{Words}); sentences can be found in strings and comments -(@pxref{Sentences}). Paragraphs in the strict sense can be found in -program code (in long comments), but the paragraph commands are useful -in other places too, because programming language major modes define -paragraphs to begin and end at blank lines (@pxref{Paragraphs}). -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. - - The selective display feature is useful for looking at the overall -structure of a function (@pxref{Selective Display}). This feature -hides the lines that are indented more than a specified amount. -Programming modes often support Outline minor mode (@pxref{Outline -Mode}). The Foldout package provides folding-editor features -(@pxref{Foldout}). - - The ``automatic typing'' features may be useful for writing programs. -@xref{Top,,Autotyping, autotype, Autotyping}. - -@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.'') @xref{Top, , CC Mode, -ccmode, CC Mode}, for a more extensive description of these modes -and their special features. - -@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 M-x c-beginning-of-defun -@itemx M-x c-end-of-defun -@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. These are found by searching for the least -enclosing braces. (By contrast, @code{beginning-of-defun} and -@code{end-of-defun} search for braces in column zero.) If you are -editing code where the opening brace of a function isn't placed in -column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to -these commands. @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 (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 (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{/l} appears in the mode line -after the mode name: - -@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 -prefix argument, this command enables electric action if the argument -is positive, disables it if it is negative. -@end table - - Electric characters insert newlines only when, in addition to the -electric state, the @dfn{auto-newline} feature is enabled (indicated -by @samp{/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-@key{DEL} (C Mode) -@kindex C-c @key{DEL} (C Mode) -@code{c-hungry-delete-backwards}---Delete the entire block of whitespace -preceding point. - -@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 (C Mode) -@kindex C-c C-@key{DELETE} (C Mode) -@kindex C-c @key{DELETE} (C Mode) -@code{c-hungry-delete-forward}---Delete the entire block of whitespace -following point. -@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} in -the mode line after the mode name), a single @key{DEL} deletes all -preceding whitespace, not just one space, and a single @kbd{C-c C-d} -(but @emph{not} plain @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})@footnote{This command had the binding -@kbd{C-c C-d} in earlier versions of Emacs. @kbd{C-c C-d} is now -bound to @code{c-hungry-delete-forward}.}. 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 C-c C-w -@itemx M-x c-subword-mode -@findex c-subword-mode -Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word -commands recognize upper case letters in -@samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by -the flag @samp{/w} on the mode line after the mode name -(e.g. @samp{C/law}). You can even use @kbd{M-x c-subword-mode} in -non-CC Mode buffers. - -In the GNU project, we recommend using underscores to separate words -within an identifier in C or C++, rather than using case distinctions. - -@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{C-j} (@code{newline-and-indent}), 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{C-j}. We use @code{c-initialization-hook} here to make sure -the keymap is loaded before we try to change it. - -@smallexample -(defun my-bind-clb () - (define-key c-mode-base-map "\C-j" 'c-context-line-break)) -(add-hook 'c-initialization-hook 'my-bind-clb) -@end smallexample - -@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 @samp{*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 -Hide-ifdef minor mode hides selected code within @samp{#if} and -@samp{#ifdef} preprocessor blocks. 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}. -@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 - -@ignore - arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0 -@end ignore