+@c -*- coding: utf-8 -*-
@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2014 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Programs, Building, Text, Top
+@node Programs
@chapter Editing Programs
@cindex Lisp editing
@cindex C editing
@cindex program editing
This chapter describes Emacs features for facilitating editing
-programs. Some of these features can:
+programs. Some of the things these features can do are:
@itemize @bullet
@item
* 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.
+* MixedCase Words:: Dealing with identifiersLikeThis.
* Semantic:: Suite of editing tools based on source code parsing.
* Misc for Programs:: Other Emacs features useful for editing programs.
* C Modes:: Special commands of C, C++, Objective-C, Java,
@cindex VHDL mode
@cindex M4 mode
@cindex Shell-script mode
-@cindex Delphi mode
+@cindex OPascal mode
@cindex PostScript mode
@cindex Conf mode
@cindex DNS mode
@cindex Javascript mode
Emacs has programming language modes for Lisp, Scheme, the
-Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++, Delphi,
+Scheme-based DSSSL expression language, Ada, ASM, AWK, C, C++,
Fortran, Icon, IDL (CORBA), IDLWAVE, Java, Javascript, Metafont
-(@TeX{}'s companion for font creation), Modula2, Objective-C, Octave,
-Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl, and
-VHDL. An alternative mode for Perl is called CPerl mode. Modes are
+(@TeX{}'s companion for font creation), Modula2, Object Pascal, Objective-C,
+Octave, Pascal, Perl, Pike, PostScript, Prolog, Python, Ruby, Simula, Tcl,
+and VHDL@. An alternative mode for Perl is called CPerl mode. Modes are
also available for the scripting languages of the common GNU and Unix
shells, VMS DCL, and MS-DOS/MS-Windows @samp{BAT} files, and for
makefiles, DNS master files, and various sorts of configuration files.
For instance, entering C mode runs the hooks @code{prog-mode-hook} and
@code{c-mode-hook}. @xref{Hooks}, for information about hooks.
-@ifinfo
+@ifnottex
Separate manuals are available for the modes for Ada (@pxref{Top,,
Ada Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba
IDL/Pike/AWK (@pxref{Top, , CC Mode, ccmode, CC Mode}), and IDLWAVE
(@pxref{Top,, IDLWAVE, idlwave, IDLWAVE User Manual}).
-@end ifinfo
-@ifnotinfo
+@end ifnottex
+@iftex
The Emacs distribution contains Info manuals for the major modes for
-Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE. For
-Fortran mode, see the ``Fortran'' section in the Info version of the
-Emacs manual, which is not included in this printed version.
-@end ifnotinfo
+Ada, C/C++/Objective C/Java/Corba IDL/Pike/AWK, and IDLWAVE@. For
+Fortran mode, @pxref{Fortran,,, emacs-xtra, Specialized Emacs Features}.
+@end iftex
@node Defuns
@section Top-Level Definitions, or Defuns
highlights confusing opening delimiters (those that ought to be
quoted) in bold red.
+@vindex open-paren-in-column-0-is-defun-start
If you need to override this convention, you can do so by setting
-this user option:
-
-@defvar open-paren-in-column-0-is-defun-start
+the variable @code{open-paren-in-column-0-is-defun-start}.
If this user option is set to @code{t} (the default), opening
-parentheses or braces at column zero always start defuns. When it's
+parentheses or braces at column zero always start defuns. When it is
@code{nil}, defuns are found by searching for parens or braces at the
outermost level.
-@end defvar
Usually, you should leave this option at its default value of
@code{t}. If your buffer contains parentheses or braces in column
@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}. Although Which Function mode is a
-global minor mode, it takes effect only in certain major modes: those
-listed in the variable @code{which-func-modes}. If the value of
-@code{which-func-modes} is @code{t} rather than a list of modes, 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.
+@kbd{M-x which-function-mode}. Which Function mode is a global minor
+mode. By default, it takes effect in all major modes major modes that
+know how to support it (i.e., all the major modes that support
+Imenu). You can restrict it to a specific list of major modes by
+changing the value of the variable @code{which-func-modes} from
+@code{t} (which means to support all available major modes) to a list
+of major mode names.
@node Program Indent
@section Indentation for Programs
@table @kbd
@item @key{TAB}
Adjust indentation of current line (@code{indent-for-tab-command}).
-@item C-j
+@item @key{RET}
Insert a newline, then adjust indentation of following line
-(@code{newline-and-indent}).
+(@code{newline}).
@end table
@kindex TAB @r{(programming modes)}
the preceding lines; if the region is active, @key{TAB} indents each
line within the region, not just the current line.
-@kindex C-j @r{(indenting source code)}
-@findex newline-and-indent
- The command @kbd{C-j} (@code{newline-and-indent}), which was
-documented in @ref{Indentation Commands}, does the same as @key{RET}
-followed by @key{TAB}: it inserts a new line, then adjusts the line's
-indentation.
+ The command @key{RET} (@code{newline}), which was documented in
+@ref{Inserting Text}, does the same as @key{C-j} followed by
+@key{TAB}: it inserts a new line, then adjusts the line's indentation.
When indenting a line that starts within a parenthetical grouping,
Emacs usually places the start of the line under the preceding line
within the group, or under the text after the parenthesis. If you
-manually give one of these lines a nonstandard indentation (e.g.@: for
+manually give one of these lines a nonstandard indentation (e.g., for
aesthetic purposes), the lines below will follow it.
The indentation commands for most programming language modes assume
To reindent the contents of a single parenthetical grouping,
position point before the beginning of the grouping and type
@kbd{C-M-q}. This changes the relative indentation within the
-grouping, without affecting its overall indentation (i.e.@: the
+grouping, without affecting its overall indentation (i.e., the
indentation of the line where the grouping starts). The function that
@kbd{C-M-q} runs depends on the major mode; it is
@code{indent-pp-sexp} in Lisp mode, @code{c-indent-exp} in C mode,
@findex backward-sexp
To move forward over a balanced expression, use @kbd{C-M-f}
(@code{forward-sexp}). If the first significant character after point
-is an opening delimiter (e.g.@: @samp{(}, @samp{[} or @samp{@{} in C),
+is an opening delimiter (e.g., @samp{(}, @samp{[} or @samp{@{} in C),
this command moves past the matching closing delimiter. If the
character begins a symbol, string, or number, the command moves over
that.
match up.
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.
+delimiter, Emacs briefly indicates the location of the matching
+opening delimiter, provided that is on the screen. If it is not on
+the screen, Emacs displays some of the text near it in the echo area.
+Either way, you can tell which grouping you are closing off. If the
+opening delimiter and closing delimiter are mismatched---such as in
+@samp{[x)}---a warning message is displayed in the echo area.
@vindex blink-matching-paren
@vindex blink-matching-paren-distance
@itemize @bullet
@item
@code{blink-matching-paren} turns the feature on or off: @code{nil}
-disables it, but the default is @code{t} to enable it.
+disables it, but the default is @code{t} to enable it. Set it to
+@code{jump} to make indication work by momentarily moving the cursor
+to the matching opening delimiter.
@item
-@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. This may be an integer or floating-point number;
-the default is 1.
+@code{blink-matching-delay} says how many seconds to keep indicating
+the matching opening delimiter. This may be an integer or
+floating-point number; the default is 1.
@item
@code{blink-matching-paren-distance} specifies how many characters
Electric Pair mode, a global minor mode, provides a way to easily
insert matching delimiters. Whenever you insert an opening delimiter,
the matching closing delimiter is automatically inserted as well,
-leaving point between the two. To toggle Electric Pair mode, type
-@kbd{M-x electric-pair-mode}.
+leaving point between the two. Conversely, when you insert a closing
+delimiter over an existing one, no inserting takes places and that
+position is simply skipped over. These variables control additional
+features of Electric Pair mode:
+
+@itemize @bullet
+@item
+@code{electric-pair-preserve-balance}, when non-@code{nil}, makes the
+default pairing logic balance out the number of opening and closing
+delimiters.
+
+@item
+@code{electric-pair-delete-adjacent-pairs}, when non-@code{nil}, makes
+backspacing between two adjacent delimiters also automatically delete
+the closing delimiter.
+
+@item
+@code{electric-pair-open-newline-between-pairs}, when non-@code{nil},
+makes inserting inserting a newline between two adjacent pairs also
+automatically open and extra newline after point.
+
+@item
+@code{electric-pair-skip-whitespace}, when non-@code{nil}, causes the minor
+mode to skip whitespace forward before deciding whether to skip over
+the closing delimiter.
+@end itemize
+
+To toggle Electric Pair mode, type @kbd{M-x electric-pair-mode}.
@node Comments
@section Manipulating Comments
If the region is not active, and there is no existing comment on the
current line, @kbd{M-;} adds a new comment to the current line. If
-the line is blank (i.e.@: empty or containing only whitespace
+the line is blank (i.e., empty or containing only whitespace
characters), the comment is indented to the same position where
@key{TAB} would indent to (@pxref{Basic Indent}). If the line is
non-blank, the comment is placed after the last non-whitespace
breaks the current line, and inserts the necessary comment delimiters
and indentation to continue the comment.
- For languages with closing comment delimiters (e.g.@: @samp{*/} in
+ For languages with closing comment delimiters (e.g., @samp{*/} in
C), the exact behavior of @kbd{M-j} depends on the value of the
variable @code{comment-multi-line}. If the value is @code{nil}, the
command closes the comment on the old line and starts a new comment on
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
+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.
the @command{man} program to format the corresponding man page. If
the system permits, it runs @command{man} asynchronously, so that you
can keep on editing while the page is being formatted. The result
-goes in a buffer named @samp{*Man @var{topic}*}. These buffers use a
+goes in a buffer named @file{*Man @var{topic}*}. These buffers use a
special major mode, Man mode, that facilitates scrolling and jumping
to other manual pages. For details, type @kbd{C-h m} while in a Man
mode buffer.
to format and display the man pages; the formatting is done by Emacs,
so it works on systems such as MS-Windows where the @command{man}
program may be unavailable. It prompts for a man page, and displays
-it in a buffer named @samp{*WoMan @var{section} @var{topic}}.
+it in a buffer named @file{*WoMan @var{section} @var{topic}}.
@kbd{M-x woman} computes the completion list for manpages the first
time you invoke the command. With a numeric argument, it recomputes
@cindex Eldoc mode
@findex eldoc-mode
Eldoc is a buffer-local minor mode that helps with looking up Lisp
-documention. When it is enabled, the echo area displays some useful
+documentation. When it is enabled, the echo area displays some useful
information whenever there is a Lisp function or variable at point;
for a function, it shows the argument list, and for a variable it
shows the first line of the variable's documentation string. To
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
+@node MixedCase Words
+@section MixedCase Words
@cindex camel case
-@findex mode, Glasses
- Glasses mode is a buffer-local minor mode that makes it easier to
-read mixed-case (or ``CamelCase'') symbols like
-@samp{unReadableSymbol}, by altering how they are displayed. By
-default, it displays extra underscores between each lower-case letter
-and the following capital letter. This does not alter the buffer
-text, only how it is displayed.
+ Some programming styles make use of mixed-case (or ``CamelCase'')
+symbols like @samp{unReadableSymbol}. (In the GNU project, we recommend
+using underscores to separate words within an identifier, rather than
+using case distinctions.) Emacs has various features to make it easier
+to deal with such symbols.
+
+@cindex Glasses mode
+@findex mode, Glasses
+ Glasses mode is a buffer-local minor mode that makes it easier to read
+such symbols, by altering how they are displayed. By default, it
+displays extra underscores between each lower-case letter and the
+following capital letter. This does not alter the buffer text, only how
+it is displayed.
To toggle Glasses mode, type @kbd{M-x glasses-mode} (@pxref{Minor
Modes}). When Glasses mode is enabled, the minor mode indicator
@samp{o^o} appears in the mode line. For more information about
Glasses mode, type @kbd{C-h P glasses @key{RET}}.
+@cindex Subword mode
+@findex subword-mode
+ Subword mode is another buffer-local minor mode. In subword mode,
+Emacs's word commands recognize upper case letters in
+@samp{StudlyCapsIdentifiers} as word boundaries. When Subword mode is
+enabled, the minor mode indicator @samp{,} appears in the mode line.
+See also the similar @code{superword-mode} (@pxref{Misc for Programs}).
+
@node Semantic
@section Semantic
@cindex Semantic package
@samp{Tools} menu. This enables Semantic mode, a global minor mode.
When Semantic mode is enabled, Emacs automatically attempts to
-parses each file you visit. Currently, Semantic understands C, C++,
+parse each file you visit. Currently, Semantic understands C, C++,
Scheme, Javascript, Java, HTML, and Make. Within each parsed buffer,
the following commands are available:
programming language major mode, indents the new lines which it
creates.
+@findex superword-mode
+ Superword mode is a buffer-local minor mode that causes editing and
+motion commands to treat symbols (e.g., @samp{this_is_a_symbol}) as words.
+When Subword mode is enabled, the minor mode indicator
+@iftex
+@samp{@math{^2}}
+@end iftex
+@ifnottex
+@samp{²}
+@end ifnottex
+appears in the mode line. See also the similar @code{subword-mode}
+(@pxref{MixedCase Words}).
+
@findex electric-layout-mode
Electric Layout mode (@kbd{M-x electric-layout-mode}) is a global
minor mode that automatically inserts newlines when you type certain
@xref{Top,,Autotyping, autotype, Autotyping}.
@end ifinfo
+@findex prettify-symbols-mode
+ Prettify Symbols mode is a buffer-local minor mode that replaces
+certain strings with more ``attractive'' versions for display
+purposes. For example, in Emacs Lisp mode, it replaces the string
+``lambda'' with the Greek lambda character. You may wish to use this
+in non-programming modes as well. You can customize the mode by
+adding more entries to @code{prettify-symbols-alist}. There is also a
+global version, @code{global-prettify-symbols-mode}, which enables the
+mode in all buffers that support it.
+
+
@node C Modes
@section C and Related Modes
@cindex C mode
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.'')
+(These are called ``C mode and related modes''.)
@ifinfo
@xref{Top,, CC Mode, ccmode, CC Mode}, for more details.
@end ifinfo
@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.
+positive prefix argument, this command enables electric action, with a
+negative one it disables it.
@end table
Electric characters insert newlines only when, in addition to the
@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.
+Delete the entire block of whitespace preceding point (@code{c-hungry-delete-backwards}).
@item C-c C-d
-@itemx C-c C-@key{DELETE}
-@itemx C-c @key{DELETE}
+@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.
+@kindex C-c C-@key{Delete} (C Mode)
+@kindex C-c @key{Delete} (C Mode)
+Delete the entire block of whitespace after point (@code{c-hungry-delete-forward}).
@end table
As an alternative to the above commands, you can enable @dfn{hungry
delete mode}. When this feature is enabled (indicated by @samp{/h} 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.
+(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,
+(@code{c-toggle-hungry-state}). With a prefix argument,
this command turns the hungry-delete feature on if the argument is
positive, and off if it is negative.
@end table
@subsection Other Commands for C Mode
@table @kbd
-@item C-c C-w
-@itemx M-x subword-mode
-@findex 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 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}).
+@key{RET} (@code{newline}), in a C preprocessor line it additionally
+inserts a @samp{\} at the line break, and within comments it's like
+@kbd{M-j} (@code{c-indent-new-comment-line}).
@code{c-context-line-break} isn't bound to a key by default, but it
needs a binding to be useful. The following code will bind it to
-@kbd{C-j}. We use @code{c-initialization-hook} here to make sure
+@key{RET}. We use @code{c-initialization-hook} here to make sure
the keymap is loaded before we try to change it.
-@smallexample
+@example
(defun my-bind-clb ()
- (define-key c-mode-base-map "\C-j" 'c-context-line-break))
+ (define-key c-mode-base-map "\C-m"
+ 'c-context-line-break))
(add-hook 'c-initialization-hook 'my-bind-clb)
-@end smallexample
+@end example
@item C-M-h
Put mark at the end of a function definition, and put point at the
@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
+This command displays another buffer named @file{*CPP Edit*}, which
serves as a graphic menu for selecting how to display particular kinds
of conditionals and their contents. After changing various settings,
click on @samp{[A]pply these settings} (or go to that buffer and type
@table @kbd
@item @key{TAB}
@code{tab-to-tab-stop}.
+@c FIXME: Maybe this should be consistent with other programming modes.
@item C-j
Insert a newline and then indent using @code{tab-to-tab-stop}.
@item :
HCoop / bpt / emacs.git / blobdiff