Mercurial > emacs
changeset 6558:fa8ff07eaafc
Initial revision
| author | Richard M. Stallman <rms@gnu.org> |
|---|---|
| date | Mon, 28 Mar 1994 20:21:44 +0000 |
| parents | 74758cf67338 |
| children | 3d314bef071a |
| files | lispref/Makefile.in lispref/debugging.texi lispref/edebug.texi lispref/eval.texi lispref/keymaps.texi lispref/lists.texi lispref/macros.texi lispref/os.texi lispref/processes.texi lispref/text.texi |
| diffstat | 10 files changed, 11959 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/Makefile.in Mon Mar 28 20:21:44 1994 +0000 @@ -0,0 +1,120 @@ +# Makefile for the GNU Emacs Lisp Reference Manual. +# +# 11 August 1990 + +# Redefine `TEX' if `tex' does not invoke plain TeX. For example: +# TEX=platex + +TEX=tex + +# Where the TeX macros are kept: +texmacrodir = /usr/local/lib/tex/macros + +# Where the Emacs hierarchy lives ($EMACS in the INSTALL document for Emacs.) +# For example: +# emacslibdir = /usr/local/gnu/lib/emacs + +# Directory where Emacs is installed, by default: +emacslibdir = /usr/local/emacs + +# Unless you have a nonstandard Emacs installation, these shouldn't have to +# be changed. +prefix = /usr/local +infodir = ${prefix}/info + +# The name of the manual: + +VERSION=2.02.2 +manual = elisp-manual-19-$(VERSION) + +# Uncomment this line for permuted index. +# permuted_index = 1 + +# List of all the texinfo files in the manual: + +srcs = elisp.texi back.texi \ + abbrevs.texi anti.texi backups.texi locals.texi buffers.texi \ + calendar.texi commands.texi compile.texi control.texi debugging.texi \ + display.texi edebug.texi errors.texi eval.texi files.texi \ + frames.texi functions.texi help.texi hooks.texi \ + internals.texi intro.texi keymaps.texi lists.texi \ + loading.texi macros.texi maps.texi markers.texi \ + minibuf.texi modes.texi numbers.texi objects.texi \ + os.texi positions.texi processes.texi searching.texi \ + sequences.texi streams.texi strings.texi symbols.texi \ + syntax.texi text.texi tips.texi variables.texi \ + windows.texi \ + index.unperm index.perm + +.PHONY: elisp.dvi clean + +elisp.dvi: $(srcs) index.texi texindex + # Avoid losing old contents of aux file entirely. + -mv elisp.aux elisp.oaux + # First shot to define xrefs: + $(TEX) elisp.texi + if [ a${permuted_index} != a ]; \ + then \ + ./permute-index; \ + mv permuted.fns elisp.fns; \ + else \ + ./texindex elisp.??; \ + fi + $(TEX) elisp.texi + +index.texi: + if [ a${permuted_index} != a ]; \ + then \ + ln -s index.perm index.texi; \ + else \ + ln -s index.unperm index.texi; \ + fi + +# The info file is named `elisp'. + +elisp: $(srcs) index.texi makeinfo + ./makeinfo elisp.texi + +install: elisp elisp.dvi + mv elisp elisp-* $(infodir) + @echo also add the line for elisp to $(infodir)/dir. + +installall: install + install -c texinfo.tex $(texmacrodir) + +clean: + rm -f *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \ + *.vr *.vrs *.pg *.pgs *.ky *.kys + rm -f make.out core + rm -f makeinfo.o makeinfo getopt.o getopt1.o + rm -f texindex.o texindex index.texi + +dist: + -mkdir temp + -mkdir temp/$(manual) + -ln README Makefile permute-index $(srcs) \ + texinfo.tex getopt.c getopt1.c getopt.h \ + elisp.dvi elisp.aux elisp.??s elisp elisp-[0-9] elisp-[0-9][0-9] temp/$(manual) + -rm -f temp/$(manual)/texindex.c temp/$(manual)/makeinfo.c + cp texindex.c makeinfo.c temp/$(manual) + (cd temp/$(manual); rm -f *~) + (cd temp; tar chf - $(manual)) | gzip > $(manual).tar.gz + -rm -rf temp + +# Make two programs used in generating output from texinfo. + +CFLAGS = -g + +texindex: texindex.o + $(CC) -o $@ $(LDFLAGS) $(CFLAGS) $? +texindex.o: texindex.c + +MAKEINFO_MAJOR = 1 +MAKEINFO_MINOR = 0 +MAKEINFO_FLAGS = -DMAKEINFO_MAJOR=$(MAKEINFO_MAJOR) -DMAKEINFO_MINOR=$(MAKEINFO_MINOR) + +makeinfo: makeinfo.o getopt.o getopt1.o + $(CC) $(LDFLAGS) -o makeinfo makeinfo.o getopt.o getopt1.o + +makeinfo.o: makeinfo.c + $(CC) -c $(CFLAGS) $(MAKEINFO_FLAGS) makeinfo.c
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/debugging.texi Mon Mar 28 20:21:44 1994 +0000 @@ -0,0 +1,701 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/debugging +@node Debugging, Streams, Byte Compilation, Top +@chapter Debugging Lisp Programs + + There are three ways to investigate a problem in an Emacs Lisp program, +depending on what you are doing with the program when the problem appears. + +@itemize @bullet +@item +If the problem occurs when you run the program, you can use a Lisp +debugger (either the default debugger or Edebug) to investigate what is +happening during execution. + +@item +If the problem is syntactic, so that Lisp cannot even read the program, +you can use the Emacs facilities for editing Lisp to localize it. + +@item +If the problem occurs when trying to compile the program with the byte +compiler, you need to know how to examine the compiler's input buffer. +@end itemize + +@menu +* Debugger:: How the Emacs Lisp debugger is implemented. +* Syntax Errors:: How to find syntax errors. +* Compilation Errors:: How to find errors that show up in byte compilation. +* Edebug:: A source-level Emacs Lisp debugger. +@end menu + + Another useful debugging tool is the dribble file. When a dribble +file is open, Emacs copies all keyboard input characters to that file. +Afterward, you can examine the file to find out what input was used. +@xref{Terminal Input}. + + For debugging problems in terminal descriptions, the +@code{open-termscript} function can be useful. @xref{Terminal Output}. + +@node Debugger +@section The Lisp Debugger +@cindex debugger +@cindex Lisp debugger +@cindex break + + The @dfn{Lisp debugger} provides the ability to suspend evaluation of +a form. While evaluation is suspended (a state that is commonly known +as a @dfn{break}), you may examine the run time stack, examine the +values of local or global variables, or change those values. Since a +break is a recursive edit, all the usual editing facilities of Emacs are +available; you can even run programs that will enter the debugger +recursively. @xref{Recursive Editing}. + +@menu +* Error Debugging:: Entering the debugger when an error happens. +* Infinite Loops:: Stopping and debugging a program that doesn't exit. +* Function Debugging:: Entering it when a certain function is called. +* Explicit Debug:: Entering it at a certain point in the program. +* Using Debugger:: What the debugger does; what you see while in it. +* Debugger Commands:: Commands used while in the debugger. +* Invoking the Debugger:: How to call the function @code{debug}. +* Internals of Debugger:: Subroutines of the debugger, and global variables. +@end menu + +@node Error Debugging +@subsection Entering the Debugger on an Error +@cindex error debugging +@cindex debugging errors + + The most important time to enter the debugger is when a Lisp error +happens. This allows you to investigate the immediate causes of the +error. + + However, entry to the debugger is not a normal consequence of an +error. Many commands frequently get Lisp errors when invoked in +inappropriate contexts (such as @kbd{C-f} at the end of the buffer) and +during ordinary editing it would be very unpleasant to enter the +debugger each time this happens. If you want errors to enter the +debugger, set the variable @code{debug-on-error} to non-@code{nil}. + +@defopt debug-on-error +This variable determines whether the debugger is called when a error is +signaled and not handled. If @code{debug-on-error} is @code{t}, all +errors call the debugger. If it is @code{nil}, none call the debugger. + +The value can also be a list of error conditions that should call the +debugger. For example, if you set it to the list +@code{(void-variable)}, then only errors about a variable that has no +value invoke the debugger. +@end defopt + + To debug an error that happens during loading of the @file{.emacs} +file, use the option @samp{-debug-init}, which binds +@code{debug-on-error} to @code{t} while @file{.emacs} is loaded. + + If your @file{.emacs} file sets @code{debug-on-error}, the effect +lasts only until the end of loading @file{.emacs}. (This is an +undesirable by-product of the @samp{-debug-init} feature.) If you want +@file{.emacs} to set @code{debug-on-error} permanently, use +@code{after-init-hook}, like this: + +@example +(add-hook 'after-init-hook + '(lambda () (setq debug-on-error t))) +@end example + +@node Infinite Loops +@subsection Debugging Infinite Loops +@cindex infinite loops +@cindex loops, infinite +@cindex quitting from infinite loop +@cindex stopping an infinite loop + + When a program loops infinitely and fails to return, your first +problem is to stop the loop. On most operating systems, you can do this +with @kbd{C-g}, which causes quit. + + Ordinary quitting gives no information about why the program was +looping. To get more information, you can set the variable +@code{debug-on-quit} to non-@code{nil}. Quitting with @kbd{C-g} is not +considered an error, and @code{debug-on-error} has no effect on the +handling of @kbd{C-g}. Contrariwise, @code{debug-on-quit} has no effect +on errors.@refill + + Once you have the debugger running in the middle of the infinite loop, +you can proceed from the debugger using the stepping commands. If you +step through the entire loop, you will probably get enough information +to solve the problem. + +@defopt debug-on-quit +This variable determines whether the debugger is called when @code{quit} +is signaled and not handled. If @code{debug-on-quit} is non-@code{nil}, +then the debugger is called whenever you quit (that is, type @kbd{C-g}). +If @code{debug-on-quit} is @code{nil}, then the debugger is not called +when you quit. @xref{Quitting}. +@end defopt + +@node Function Debugging +@subsection Entering the Debugger on a Function Call +@cindex function call debugging +@cindex debugging specific functions + + To investigate a problem that happens in the middle of a program, one +useful technique is to enter the debugger whenever a certain function is +called. You can do this to the function in which the problem occurs, +and then step through the function, or you can do this to a function +called shortly before the problem, step quickly over the call to that +function, and then step through its caller. + +@deffn Command debug-on-entry function-name + This function requests @var{function-name} to invoke the debugger each time +it is called. It works by inserting the form @code{(debug 'debug)} into +the function definition as the first form. + + Any function defined as Lisp code may be set to break on entry, +regardless of whether it is interpreted code or compiled code. If the +function is a command, it will enter the debugger when called from Lisp +and when called interactively (after the reading of the arguments). You +can't debug primitive functions (i.e., those written in C) this way. + + When @code{debug-on-entry} is called interactively, it prompts +for @var{function-name} in the minibuffer. + + If the function is already set up to invoke the debugger on entry, +@code{debug-on-entry} does nothing. + + Caveat: if you redefine a function after using @code{debug-on-entry} +on it, the code to enter the debugger is lost. + + @code{debug-on-entry} returns @var{function-name}. + +@example +@group +(defun fact (n) + (if (zerop n) 1 + (* n (fact (1- n))))) + @result{} fact +@end group +@group +(debug-on-entry 'fact) + @result{} fact +@end group +@group +(fact 3) + @result{} 6 +@end group + +@group +------ Buffer: *Backtrace* ------ +Entering: +* fact(3) + eval-region(4870 4878 t) + byte-code("...") + eval-last-sexp(nil) + (let ...) + eval-insert-last-sexp(nil) +* call-interactively(eval-insert-last-sexp) +------ Buffer: *Backtrace* ------ +@end group + +@group +(symbol-function 'fact) + @result{} (lambda (n) + (debug (quote debug)) + (if (zerop n) 1 (* n (fact (1- n))))) +@end group +@end example +@end deffn + +@deffn Command cancel-debug-on-entry function-name +This function undoes the effect of @code{debug-on-entry} on +@var{function-name}. When called interactively, it prompts for +@var{function-name} in the minibuffer. + +If @code{cancel-debug-on-entry} is called more than once on the same +function, the second call does nothing. @code{cancel-debug-on-entry} +returns @var{function-name}. +@end deffn + +@node Explicit Debug +@subsection Explicit Entry to the Debugger + + You can cause the debugger to be called at a certain point in your +program by writing the expression @code{(debug)} at that point. To do +this, visit the source file, insert the text @samp{(debug)} at the +proper place, and type @kbd{C-M-x}. Be sure to undo this insertion +before you save the file! + + The place where you insert @samp{(debug)} must be a place where an +additional form can be evaluated and its value ignored. (If the value +isn't ignored, it will alter the execution of the program!) The most +common suitable places are inside a @code{progn} or an implicit +@code{progn} (@pxref{Sequencing}). + +@node Using Debugger +@subsection Using the Debugger + + When the debugger is entered, it displays the previously selected +buffer in one window and a buffer named @samp{*Backtrace*} in another +window. The backtrace buffer contains one line for each level of Lisp +function execution currently going on. At the beginning of this buffer +is a message describing the reason that the debugger was invoked (such +as the error message and associated data, if it was invoked due to an +error). + + The backtrace buffer is read-only and uses a special major mode, +Debugger mode, in which letters are defined as debugger commands. The +usual Emacs editing commands are available; thus, you can switch windows +to examine the buffer that was being edited at the time of the error, +switch buffers, visit files, or do any other sort of editing. However, +the debugger is a recursive editing level (@pxref{Recursive Editing}) +and it is wise to go back to the backtrace buffer and exit the debugger +(with the @kbd{q} command) when you are finished with it. Exiting +the debugger gets out of the recursive edit and kills the backtrace +buffer. + +@cindex current stack frame + The contents of the backtrace buffer show you the functions that are +executing and their argument values. It also allows you to specify a +stack frame by moving point to the line describing that frame. (A stack +frame is the place where the Lisp interpreter records information about +a particular invocation of a function.) The frame whose line point is +on is considered the @dfn{current frame}. Some of the debugger commands +operate on the current frame. + + The debugger itself must be run byte-compiled, since it makes +assumptions about how many stack frames are used for the debugger +itself. These assumptions are false if the debugger is running +interpreted. + +@need 3000 + +@node Debugger Commands +@subsection Debugger Commands +@cindex debugger command list + + Inside the debugger (in Debugger mode), these special commands are +available in addition to the usual cursor motion commands. (Keep in +mind that all the usual facilities of Emacs, such as switching windows +or buffers, are still available.) + + The most important use of debugger commands is for stepping through +code, so that you can see how control flows. The debugger can step +through the control structures of an interpreted function, but cannot do +so in a byte-compiled function. If you would like to step through a +byte-compiled function, replace it with an interpreted definition of the +same function. (To do this, visit the source file for the function and +type @kbd{C-M-x} on its definition.) + + Here is a list of Debugger mode commands: + +@table @kbd +@item c +Exit the debugger and continue execution. When continuing is possible, +it resumes execution of the program as if the debugger had never been +entered (aside from the effect of any variables or data structures you +may have changed while inside the debugger). + +Continuing is possible after entry to the debugger due to function entry +or exit, explicit invocation, or quitting. You cannot continue if the +debugger was entered because of an error. + +@item d +Continue execution, but enter the debugger the next time any Lisp +function is called. This allows you to step through the +subexpressions of an expression, seeing what values the subexpressions +compute, and what else they do. + +The stack frame made for the function call which enters the debugger in +this way will be flagged automatically so that the debugger will be +called again when the frame is exited. You can use the @kbd{u} command +to cancel this flag. + +@item b +Flag the current frame so that the debugger will be entered when the +frame is exited. Frames flagged in this way are marked with stars +in the backtrace buffer. + +@item u +Don't enter the debugger when the current frame is exited. This +cancels a @kbd{b} command on that frame. + +@item e +Read a Lisp expression in the minibuffer, evaluate it, and print the +value in the echo area. The debugger alters certain important variables +as part of its operation; @kbd{e} temporarily restores their +outside-the-debugger values so you can examine them. This makes the +debugger more transparent. By contrast, @kbd{M-@key{ESC}} does nothing +special in the debugger; it shows you the variable values within the +debugger. + +@item q +Terminate the program being debugged; return to top-level Emacs +command execution. + +If the debugger was entered due to a @kbd{C-g} but you really want +to quit, and not debug, use the @kbd{q} command. + +@item r +Return a value from the debugger. The value is computed by reading an +expression with the minibuffer and evaluating it. + +The @kbd{r} command makes a difference when the debugger was invoked due +to exit from a Lisp call frame (as requested with @kbd{b}); then the +value specified in the @kbd{r} command is used as the value of that +frame. + +You can't use @kbd{r} when the debugger was entered due to an error. +@end table + +@node Invoking the Debugger +@subsection Invoking the Debugger + + Here we describe fully the function used to invoke the debugger. + +@defun debug &rest debugger-args +This function enters the debugger. It switches buffers to a buffer +named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second +recursive entry to the debugger, etc.), and fills it with information +about the stack of Lisp function calls. It then enters a recursive +edit, showing the backtrace buffer in Debugger mode. + +The Debugger mode @kbd{c} and @kbd{r} commands exit the recursive edit; +then @code{debug} switches back to the previous buffer and returns to +whatever called @code{debug}. This is the only way the function +@code{debug} can return to its caller. + +If the first of the @var{debugger-args} passed to @code{debug} is +@code{nil} (or if it is not one of the special values in the table +below), then @code{debeg} displays the rest of its arguments at the the +top of the @samp{*Backtrace*} buffer. This mechanism is used to display +a message to the user. + +However, if the first argument passed to @code{debug} is one of the +following special values, then it has special significance. Normally, +these values are passed to @code{debug} only by the internals of Emacs +and the debugger, and not by programmers calling @code{debug}. + +The special values are: + +@table @code +@item lambda +@cindex @code{lambda} in debug +A first argument of @code{lambda} means @code{debug} was called because +of entry to a function when @code{debug-on-next-call} was +non-@code{nil}. The debugger displays @samp{Entering:} as a line of +text at the top of the buffer. + +@item debug +@code{debug} as first argument indicates a call to @code{debug} because +of entry to a function that was set to debug on entry. The debugger +displays @samp{Entering:}, just as in the @code{lambda} case. It also +marks the stack frame for that function so that it will invoke the +debugger when exited. + +@item t +When the first argument is @code{t}, this indicates a call to +@code{debug} due to evaluation of a list form when +@code{debug-on-next-call} is non-@code{nil}. The debugger displays the +following as the top line in the buffer: + +@smallexample +Beginning evaluation of function call form: +@end smallexample + +@item exit +When the first argument is @code{exit}, it indicates the exit of a +stack frame previously marked to invoke the debugger on exit. The +second argument given to @code{debug} in this case is the value being +returned from the frame. The debugger displays @samp{Return value:} on +the top line of the buffer, followed by the value being returned. + +@item error +@cindex @code{error} in debug +When the first argument is @code{error}, the debugger indicates that +it is being entered because an error or @code{quit} was signaled and not +handled, by displaying @samp{Signaling:} followed by the error signaled +and any arguments to @code{signal}. For example, + +@example +@group +(let ((debug-on-error t)) + (/ 1 0)) +@end group + +@group +------ Buffer: *Backtrace* ------ +Signaling: (arith-error) + /(1 0) +... +------ Buffer: *Backtrace* ------ +@end group +@end example + +If an error was signaled, presumably the variable +@code{debug-on-error} is non-@code{nil}. If @code{quit} was signaled, +then presumably the variable @code{debug-on-quit} is non-@code{nil}. + +@item nil +Use @code{nil} as the first of the @var{debugger-args} when you want +to enter the debugger explicitly. The rest of the @var{debugger-args} +are printed on the top line of the buffer. You can use this feature to +display messages---for example, to remind yourself of the conditions +under which @code{debug} is called. +@end table +@end defun + +@need 5000 + +@node Internals of Debugger +@subsection Internals of the Debugger + + This section describes functions and variables used internally by the +debugger. + +@defvar debugger +The value of this variable is the function to call to invoke the +debugger. Its value must be a function of any number of arguments (or, +more typically, the name of a function). Presumably this function will +enter some kind of debugger. The default value of the variable is +@code{debug}. + +The first argument that Lisp hands to the function indicates why it +was called. The convention for arguments is detailed in the description +of @code{debug}. +@end defvar + +@deffn Command backtrace +@cindex run time stack +@cindex call stack +This function prints a trace of Lisp function calls currently active. +This is the function used by @code{debug} to fill up the +@samp{*Backtrace*} buffer. It is written in C, since it must have access +to the stack to determine which function calls are active. The return +value is always @code{nil}. + +In the following example, a Lisp expression calls @code{backtrace} +explicitly. This prints the backtrace to the stream +@code{standard-output}: in this case, to the buffer +@samp{backtrace-output}. Each line of the backtrace represents one +function call. The line shows the values of the function's arguments if +they are all known. If they are still being computed, the line says so. +The arguments of special forms are elided. + +@smallexample +@group +(with-output-to-temp-buffer "backtrace-output" + (let ((var 1)) + (save-excursion + (setq var (eval '(progn + (1+ var) + (list 'testing (backtrace)))))))) + + @result{} nil +@end group + +@group +----------- Buffer: backtrace-output ------------ + backtrace() + (list ...computing arguments...) + (progn ...) + eval((progn (1+ var) (list (quote testing) (backtrace)))) + (setq ...) + (save-excursion ...) + (let ...) + (with-output-to-temp-buffer ...) + eval-region(1973 2142 #<buffer *scratch*>) + byte-code("... for eval-print-last-sexp ...") + eval-print-last-sexp(nil) +* call-interactively(eval-print-last-sexp) +----------- Buffer: backtrace-output ------------ +@end group +@end smallexample + +The character @samp{*} indicates a frame whose debug-on-exit flag is +set. +@end deffn + +@ignore @c Not worth mentioning +@defopt stack-trace-on-error +@cindex stack trace +This variable controls whether Lisp automatically displays a +backtrace buffer after every error that is not handled. A quit signal +counts as an error for this variable. If it is non-@code{nil} then a +backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every +error. If it is @code{nil}, then a backtrace is not shown. + +When a backtrace is shown, that buffer is not selected. If either +@code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then +a backtrace is shown in one buffer, and the debugger is popped up in +another buffer with its own backtrace. + +We consider this feature to be obsolete and superseded by the debugger +itself. +@end defopt +@end ignore + +@defvar debug-on-next-call +@cindex @code{eval}, and debugging +@cindex @code{apply}, and debugging +@cindex @code{funcall}, and debugging +If this variable is non-@code{nil}, it says to call the debugger before +the next @code{eval}, @code{apply} or @code{funcall}. Entering the +debugger sets @code{debug-on-next-call} to @code{nil}. + +The @kbd{d} command in the debugger works by setting this variable. +@end defvar + +@defun backtrace-debug level flag +This function sets the debug-on-exit flag of the stack frame @var{level} +levels, giving it the value @var{flag}. If @var{flag} is +non-@code{nil}, this will cause the debugger to be entered when that +frame later exits. Even a nonlocal exit through that frame will enter +the debugger. + +Normally, this function is only called by the debugger. +@end defun + +@defvar command-debug-status +This variable records the debugging status of current interactive +command. Each time a command is called interactively, this variable is +bound to @code{nil}. The debugger can set this variable to leave +information for future debugger invocations during the same command. + +The advantage of using this variable rather that defining another global +variable is that the data will never carry over to a subsequent command +invocation. +@end defvar + +@defun backtrace-frame frame-number +The function @code{backtrace-frame} is intended for use in Lisp +debuggers. It returns information about what computation is happening +in the stack frame @var{frame-number} levels down. + +If that frame has not evaluated the arguments yet (or is a special +form), the value is @code{(nil @var{function} @var{arg-forms}@dots{})}. + +If that frame has evaluated its arguments and called its function +already, the value is @code{(t @var{function} +@var{arg-values}@dots{})}. + +In the return value, @var{function} is whatever was supplied as @sc{car} +of evaluated list, or a @code{lambda} expression in the case of a macro +call. If the function has a @code{&rest} argument, that is represented +as the tail of the list @var{arg-values}. + +If the argument is out of range, @code{backtrace-frame} returns +@code{nil}. +@end defun + +@node Syntax Errors +@section Debugging Invalid Lisp Syntax + + The Lisp reader reports invalid syntax, but cannot say where the real +problem is. For example, the error ``End of file during parsing'' in +evaluating an expression indicates an excess of open parentheses (or +square brackets). The reader detects this imbalance at the end of the +file, but it cannot figure out where the close parenthesis should have +been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close +parenthesis or missing open parenthesis, but does not say where the +missing parenthesis belongs. How, then, to find what to change? + + If the problem is not simply an imbalance of parentheses, a useful +technique is to try @kbd{C-M-e} at the beginning of each defun, and see +if it goes to the place where that defun appears to end. If it does +not, there is a problem in that defun. + + However, unmatched parentheses are the most common syntax errors in +Lisp, and we can give further advice for those cases. + +@menu +* Excess Open:: How to find a spurious open paren or missing close. +* Excess Close:: How to find a spurious close paren or missing open. +@end menu + +@node Excess Open +@subsection Excess Open Parentheses + + The first step is to find the defun that is unbalanced. If there is +an excess open parenthesis, the way to do this is to insert a +close parenthesis at the end of the file and type @kbd{C-M-b} +(@code{backward-sexp}). This will move you to the beginning of the +defun that is unbalanced. (Then type @kbd{C-@key{SPC} C-_ C-u +C-@key{SPC}} to set the mark there, undo the insertion of the +close parenthesis, and finally return to the mark.) + + The next step is to determine precisely what is wrong. There is no +way to be sure of this except to study the program, but often the +existing indentation is a clue to where the parentheses should have +been. The easiest way to use this clue is to reindent with @kbd{C-M-q} +and see what moves. + + Before you do this, make sure the defun has enough close parentheses. +Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest +of the file until the end. So move to the end of the defun and insert a +close parenthesis there. Don't use @kbd{C-M-e} to move there, since +that too will fail to work until the defun is balanced. + + Now you can go to the beginning of the defun and type @kbd{C-M-q}. +Usually all the lines from a certain point to the end of the function +will shift to the right. There is probably a missing close parenthesis, +or a superfluous open parenthesis, near that point. (However, don't +assume this is true; study the code to make sure.) Once you have found +the discrepancy, undo the @kbd{C-M-q}, since the old indentation is +probably appropriate to the intended parentheses. + + After you think you have fixed the problem, use @kbd{C-M-q} again. If +the old indentation actually fit the intended nesting of parentheses, +and you have put back those parentheses, @kbd{C-M-q} should not change +anything. + +@node Excess Close +@subsection Excess Close Parentheses + + To deal with an excess close parenthesis, first insert an +open parenthesis at the beginning of the file and type @kbd{C-M-f} to +find the end of the unbalanced defun. (Then type @kbd{C-@key{SPC} C-_ +C-u C-@key{SPC}} to set the mark there, undo the insertion of the +open parenthesis, and finally return to the mark.) + + Then find the actual matching close parenthesis by typing @kbd{C-M-f} +at the beginning of the defun. This will leave you somewhere short of +the place where the defun ought to end. It is possible that you will +find a spurious close parenthesis in that vicinity. + + If you don't see a problem at that point, the next thing to do is to +type @kbd{C-M-q} at the beginning of the defun. A range of lines will +probably shift left; if so, the missing open parenthesis or spurious +close parenthesis is probably near the first of those lines. (However, +don't assume this is true; study the code to make sure.) Once you have +found the discrepancy, undo the @kbd{C-M-q}, since the old indentation +is probably appropriate to the intended parentheses. + +@node Compilation Errors +@section Debugging Problems in Compilation + + When an error happens during byte compilation, it is normally due to +invalid syntax in the program you are compiling. The compiler prints a +suitable error message in the @samp{*Compile-Log*} buffer, and then +stops. The message may state a function name in which the error was +found, or it may not. Either way, here is how to find out where in the +file the error occurred. + + What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}. +(Note that the buffer name starts with a space, so it does not show +up in @kbd{M-x list-buffers}.) This buffer contains the program being +compiled, and point shows how far the byte compiler was able to read. + + If the error was due to invalid Lisp syntax, point shows exactly where +the invalid syntax was @emph{detected}. The cause of the error is not +necessarily near by! Use the techniques in the previous section to find +the error. + + If the error was detected while compiling a form that had been read +successfully, then point is located at the end of the form. In this +case, it can't localize the error precisely, but can still show you +which function to check. + +@include edebug.texi
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/edebug.texi Mon Mar 28 20:21:44 1994 +0000 @@ -0,0 +1,1676 @@ +@comment -*-texinfo-*- + +@c This file is intended to be used as a section within the Emacs Lisp +@c Reference Manual. It may also be used by an independent Edebug User +@c Manual, edebug.tex, in which case the Edebug node below should be used +@c with the following links to the Bugs section and to the top level: + +@c , Bugs and Todo List, Top, Top + +@node Edebug, Bugs and Todo List, Top, Top +@section Edebug +@cindex Edebug mode + +@cindex Edebug + Edebug is a source-level debugger for Emacs Lisp programs with which +you can: + +@itemize @bullet +@item +Step through evaluation, stopping before and after each expression. + +@item +Set conditional or unconditional breakpoints. + +@item +Stop when a specified condition is true (the global break event). + +@item +Trace slow or fast, stopping briefly at each stop point, or +at each breakpoint. + +@item +Display expression results and evaluate expressions as if outside of +Edebug. + +@item +Automatically reevaluate a list of expressions and +display their results each time Edebug updates the display. + +@item +Output trace info on function enter and exit. + +@item +Stop when an error occurs. + +@item +Display a backtrace, omitting Edebug's own frames. + +@item +Specify argument evaluation for macros and defining forms. + +@item +Obtain rudimentary coverage testing and frequency counts. +@end itemize + +The first three sections below should tell you enough about Edebug to +enable you to use it. + +@menu +* Using Edebug:: Introduction to use of Edebug. +* Instrumenting:: You must instrument your code + in order to debug it with Edebug. +* Modes: Edebug Execution Modes. Execution modes, stopping more or less often. +* Jumping:: Commands to jump to a specified place. +* Misc: Edebug Misc. Miscellaneous commands. +* Breakpoints:: Setting breakpoints to make the program stop. +* Trapping Errors:: trapping errors with Edebug. +* Views: Edebug Views. Views inside and outside of Edebug. +* Eval: Edebug Eval. Evaluating expressions within Edebug. +* Eval List:: Expressions whose values are displayed + each time you enter Edebug. +* Printing in Edebug:: Customization of printing. +* Trace Buffer:: How to produce trace output in a buffer. +* Coverage Testing:: How to test evaluation coverage. +* The Outside Context:: Data that Edebug saves and restores. +* Instrumenting Macro Calls:: Specifying how to handle macro calls. +* Options: Edebug Options. Option variables for customizing Edebug. +@end menu + +@node Using Edebug +@subsection Using Edebug + + To debug a Lisp program with Edebug, you must first @dfn{instrument} +the Lisp code that you want to debug. A simple way to do this is to +first move point into the definition of a function or macro and then do +@kbd{C-u C-M-x} (@code{eval-defun} with a prefix argument). See +@ref{Instrumenting}, for alternative ways to instrument code. + + Once a function is instrumented, any call to the function activates +Edebug. Activating Edebug may stop execution and let you step through +the function, or it may update the display and continue execution while +checking for debugging commands, depending on which Edebug execution +mode you have selected. The default execution mode is step, which does +stop execution. @xref{Edebug Execution Modes}. + + Within Edebug, you normally view an Emacs buffer showing the source of +the Lisp code you are debugging. This is referred to as the @dfn{source +code buffer}. This buffer is temporarily read-only. + + An arrow at the left margin indicates the line where the function is +executing. Point initially shows where within the line the function is +executing, but this ceases to be true if you move point yourself. + + If you instrument the definition of @code{fac} (shown below) and then +execute @code{(fac 3)}, here is what you normally see. Point is at the +open-parenthesis before @code{if}. + +@example +(defun fac (n) +=>@point{}(if (< 0 n) + (* n (fac (1- n))) + 1)) +@end example + +@cindex stop points +The places within a function where Edebug can stop execution are called +@dfn{stop points}. These occur both before and after each subexpression +that is a list, and also after each variable reference. +Here we show with periods the stop points found in the function +@code{fac}: + +@example +(defun fac (n) + .(if .(< 0 n.). + .(* n. .(fac (1- n.).).). + 1).) +@end example + +The special commands of Edebug are available in the source code buffer +in addition to the commands of Emacs Lisp mode. For example, you can +type the Edebug command @key{SPC} to execute until the next stop point. +If you type @key{SPC} once after entry to @code{fac}, here is the +display you will see: + +@example +(defun fac (n) +=>(if @point{}(< 0 n) + (* n (fac (1- n))) + 1)) +@end example + +When Edebug stops execution after an expression, it displays the +expression's value in the echo area. + +Other frequently used commands are @kbd{b} to set a breakpoint at a stop +point, @kbd{g} to execute until a breakpoint is reached, and @kbd{q} to +exit Edebug and return to the top-level command loop. Type @kbd{?} to +display a list of all Edebug commands. + +@node Instrumenting +@subsection Instrumenting for Edebug + + In order to use Edebug to debug Lisp code, you must first +@dfn{instrument} the code. Instrumenting code inserts additional code +into it, code which invokes Edebug at the proper places. + + Once a function is instrumented, any call to the function activates +Edebug. This may or may not stop execution, depending on the Edebug +execution mode in use. Some Edebug modes only update the display to +indicate the progress of the evaluation without stopping execution. + +@kindex C-M-x +@findex eval-defun (Edebug) + Once you have loaded Edebug, the command @kbd{C-M-x} +(@code{eval-defun}) is redefined so that when invoked with a prefix +argument on a definition, it instruments the definition before +evaluating it. (The source code itself is not modified.) If the +variable @code{edebug-all-defs} is non-@code{nil}, that inverts the +meaning of the prefix argument: then @kbd{C-M-x} instruments the +definition @emph{unless} it has a prefix argument. The default value of +@code{edebug-all-defs} is @code{nil}. The command @kbd{M-x +edebug-all-defs} toggles the value of the variable +@code{edebug-all-defs}. + +@findex edebug-all-forms +@findex eval-region (Edebug) +@findex eval-current-buffer (Edebug) + If @code{edebug-all-defs} is non-@code{nil}, then the commands +@code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer} +also instrument any definitions they evaluate. Similarly, +@code{edebug-all-forms} controls whether @code{eval-region} should +instrument @emph{any} form, even non-defining forms. This doesn't apply +to loading or evaluations in the minibuffer. The command @kbd{M-x +edebug-all-forms} toggles this option. + +@findex edebug-eval-top-level-form +Another command, @kbd{M-x edebug-eval-top-level-form}, is available to +instrument any top-level form regardless of the value of +@code{edebug-all-defs} or @code{edebug-all-forms}. + +When Edebug is about to instrument code for the first time in a session, +it runs the hook @code{edebug-setup-hook}, then sets it to @code{nil}. +You can use this to load up Edebug specifications associated with a +package you are using, but only when you also use Edebug. + +While Edebug is active, the command @kbd{I} +(@code{edebug-instrument-callee}) instruments the definition of the +function or macro called by the list form after point, if is not already +instrumented. This is possible only if Edebug knows where to find the +source for that function; after loading Edebug, @code{eval-region} +records the position of every definition it evaluates, even if not +instrumenting it. See also the @kbd{i} command (@pxref{Jumping}), which +steps into the call after instrumenting the function. + +@cindex special forms (Edebug) +@cindex interactive commands (Edebug) +@cindex anonymous lambda expressions (Edebug) +@cindex Common Lisp (Edebug) +@pindex cl.el (Edebug) +@pindex cl-specs.el + Edebug knows how to instrument all the standard special forms, an +interactive form with an expression argument, anonymous lambda +expressions, and other defining forms. Edebug cannot know what a +user-defined macro will do with the arguments of a macro call, so you +must tell it; @xref{Instrumenting Macro Calls}, for details. + +@findex eval-expression (Edebug) + To remove instrumentation from a definition, simply reevaluate its +definition in a way that does not instrument. There are two ways of +evaluating forms without instrumenting them: from a file with +@code{load}, and from the minibuffer with @code{eval-expression} +(@kbd{M-ESC}). + + If Edebug detects a syntax error while instrumenting, it leaves point +at the erroneous code and signals an @code{invalid-read-syntax} error. + + @xref{Edebug Eval}, for other evaluation functions available +inside of Edebug. + +@node Edebug Execution Modes +@subsection Edebug Execution Modes + +@cindex Edebug execution modes +Edebug supports several execution modes for running the program you are +debugging. We call these alternatives @dfn{Edebug execution modes}; do +not confuse them with major or minor modes. The current Edebug mode +determines how far Edebug continues execution before stopping---whether +it stops at each stop point, or continues to the next breakpoint, for +example---and how much Edebug displays the progress of the evaluation +before it stops. + +Normally, you specify the Edebug execution mode by typing a command to +continue the program in a certain mode. Here is a table of these +commands. All except for @kbd{S} resume execution of the program, at +least for a certain distance. + +@table @kbd +@item S +Stop: don't execute any more of the program for now, just wait for more +Edebug commands (@code{edebug-stop}). + +@item @key{SPC} +Step: stop at the next stop point encountered (@code{edebug-step-mode}). + +@item n +Next: stop at the next stop point encountered after an expression +(@code{edebug-next-mode}). Also see @code{edebug-forward-sexp} in +@ref{Edebug Misc}. + +@item t +Trace: pause one second at each Edebug stop point (@code{edebug-trace-mode}). + +@item T +Rapid trace: update the display at each stop point, but don't actually +pause (@code{edebug-Trace-fast-mode}). + +@item g +Go: run until the next breakpoint (@code{edebug-go-mode}). @xref{Breakpoints}. + +@item c +Continue: pause one second at each breakpoint, and then continue +(@code{edebug-continue-mode}). + +@item C +Rapid continue: move point to each breakpoint, but don't pause +(@code{edebug-Continue-fast-mode}). + +@item G +Go non-stop: ignore breakpoints (@code{edebug-Go-nonstop-mode}). You +can still stop the program by typing @kbd{S}, or any editing command. +@end table + +In general, the execution modes earlier in the above list run the +program more slowly or stop sooner. + +While executing or tracing, you can interrupt the execution by typing +any Edebug command. Edebug stops the program at the next stop point and +then executes the command that you typed. For example, typing @kbd{t} +during execution switches to trace mode at the next stop point. You can +use @kbd{S} to stop execution without doing anything else. + +If your function happens to read input, a character you type intending +to interrupt execution may be read by the function instead. You can +avoid such unintended results by paying attention to when your program +wants input. + +@cindex keyboard macros (Edebug) +Keyboard macros containing the commands in this section do not +completely work: exiting from Edebug, to resume the program, loses track +of the keyboard macro. This is not easy to fix. Also, defining or +executing a keyboard macro outside of Edebug does not affect commands +inside Edebug. This is usually an advantage. But see the +@code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}). + +When you enter a new Edebug level, the initial execution mode comes from +the value of the variable @code{edebug-initial-mode}. By default, this +specifies step mode. Note that you may reenter the same Edebug level +several times if, for example, an instrumented function is called +several times from one command. + + +@node Jumping +@subsection Jumping + + The commands described in this section execute until they reach a +specified location. All except @kbd{i} make a temporary breakpoint to +establish the place to stop, then switch to go mode. Any other +breakpoint reached before the intended stop point will also stop +execution. @xref{Breakpoints}, for the details on breakpoints. + + These commands may fail to work as expected in case of nonlocal exit, +because a nonlocal exit can bypass the temporary breakpoint where you +expected the program to stop. + +@table @kbd +@item h +Proceed to the stop point near where point is (@code{edebug-goto-here}). + +@item f +Run the program forward over one expression +(@code{edebug-forward-sexp}). + +@item o +Run the program until the end of the containing sexp. + +@item i +Step into the function or macro called by the form after point. +@end table + +The @kbd{h} command proceeds to the stop point near the current location +if point, using a temporary breakpoint. See @ref{Breakpoints}, for more +about breakpoints. + +The @kbd{f} command runs the program forward over one expression. More +precisely, it sets a temporary breakpoint at the position that +@kbd{C-M-f} would reach, then executes in go mode so that the program +will stop at breakpoints. + +With a prefix argument @var{n}, the temporary breakpoint is placed +@var{n} sexps beyond point. If the containing list ends before @var{n} +more elements, then the place to stop is after the containing +expression. + +Be careful that the position @kbd{C-M-f} finds is a place that the +program will really get to; this may not be true in a +@code{cond}, for example. + +The @kbd{f} command does @code{forward-sexp} starting at point, rather +than at the stop point, for flexibility. If you want to execute one +expression @emph{from the current stop point}, type @kbd{w} first, to +move point there, and then type @kbd{f}. + +The @kbd{o} command continues ``out of'' an expression. It places a +temporary breakpoint at the end of the sexp containing point. If the +containing sexp is a function definition itself, it continues until just +before the last sexp in the definition. If that is where you are now, +it returns from the function and then stops. In other words, this +command does not exit the currently executing function unless you are +positioned after the last sexp. + +The @kbd{i} command steps into the function or macro called by the list +form after point. Note that the form need not be the one about to be +evaluated. But if the form is a function call about to be evaluated, +remember to use this command before any of the arguments are evaluated, +since otherwise it will be too late. + +The @kbd{i} command instruments the function or macro it's supposed to +step into, if it isn't instrumented already. This is convenient, but keep +in mind that the function or macro remains instrumented unless you explicitly +arrange to deinstrument it. + +@node Edebug Misc +@subsection Miscellaneous Edebug Commands + + Some miscellaneous Edebug commands are described here. + +@table @kbd +@item ? +Display the help message for Edebug (@code{edebug-help}). + +@item C-] +Abort one level back to the previous command level +(@code{abort-recursive-edit}). + +@item q +Return to the top level editor command loop (@code{top-level}). This +exits all recursive editing levels, including all levels of Edebug +activity. However, instrumented code protected with +@code{unwind-protect} or @code{condition-case} forms may resume +debugging. + +@item Q +Like @kbd{q} but don't stop even for protected code +(@code{top-level-nonstop}). + +@item r +Redisplay the most recently known expression result in the echo area +(@code{edebug-previous-result}). + +@item d +Display a backtrace, excluding Edebug's own functions for clarity +(@code{edebug-backtrace}). + +You cannot use debugger commands in the backtrace buffer in Edebug as +you would in the standard debugger. + +The backtrace buffer is killed automatically when you continue +execution. +@end table + +>From the Edebug recursive edit, you may invoke commands that activate +Edebug again recursively. Any time Edebug is active, you can quit to +the top level with @kbd{q} or abort one recursive edit level with +@kbd{C-]}. You can display a backtrace of all the +pending evaluations with @kbd{d}. + +@node Breakpoints +@subsection Breakpoints + +@cindex breakpoints +Edebug's step mode stops execution at the next stop point reached. +There are three other ways to stop Edebug execution once it has started: +breakpoints, the global break condition, and source breakpoints. + +While using Edebug, you can specify @dfn{breakpoints} in the program you +are testing: points where execution should stop. You can set a +breakpoint at any stop point, as defined in @ref{Using Edebug}. For +setting and unsetting breakpoints, the stop point that is affected is +the first one at or after point in the source code buffer. Here are the +Edebug commands for breakpoints: + +@table @kbd +@item b +Set a breakpoint at the stop point at or after point +(@code{edebug-set-breakpoint}). If you use a prefix argument, the +breakpoint is temporary (it turns off the first time it stops the +program). + +@item u +Unset the breakpoint (if any) at the stop point at or after +point (@code{edebug-unset-breakpoint}). + +@item x @var{condition} @key{RET} +Set a conditional breakpoint which stops the program only if +@var{condition} evaluates to a non-@code{nil} value +(@code{edebug-set-conditional-breakpoint}). With a prefix argument, the +breakpoint is temporary. + +@item B +Move point to the next breakpoint in the definition +(@code{edebug-next-breakpoint}). +@end table + +While in Edebug, you can set a breakpoint with @kbd{b} and unset one +with @kbd{u}. First move point to the Edebug stop point of your choice, +then type @kbd{b} or @kbd{u} to set or unset a breakpoint there. +Unsetting a breakpoint where none has been set has no effect. + +Reevaluating or reinstrumenting a definition forgets all its breakpoints. + +A @dfn{conditional breakpoint} tests a condition each time the program +gets there. Any errors that occur as a result of evaluating the +condition are ignored, as if the result were @code{nil}. To set a +conditional breakpoint, use @kbd{x}, and specify the condition +expression in the minibuffer. Setting a conditional breakpoint at a +stop point that has a previously established conditional breakpoint puts +the previous condition expression in the minibuffer so you can edit it. + +You can make a conditional or unconditional breakpoint +@dfn{temporary} by using a prefix arg with the command to set the +breakpoint. When a temporary breakpoint stops the program, it is +automatically unset. + +Edebug always stops or pauses at a breakpoint except when the Edebug +mode is Go-nonstop. In that mode, it ignores breakpoints entirely. + +To find out where your breakpoints are, use the @kbd{B} command, which +moves point to the next breakpoint in the definition following point, or +to the first breakpoint if there are no following breakpoints. This +command does not continue execution---it just moves point in the buffer. + +@menu +* Global Break Condition:: Breaking on an event. +* Source Breakpoints:: Embedding breakpoints in source code. +@end menu + + +@node Global Break Condition +@subsubsection Global Break Condition + +@cindex stopping on events +@cindex global break condition + A @dfn{global break condition} stops execution when a specified +condition is satisfied, no matter where that may occur. Edebug +evaluates the global break condition at every stop point. If it +evaluates to a non-@code{nil} value, then execution stops or pauses +depending on the execution mode, as if a breakpoint had been hit. If +evaluating the condition gets an error, execution does not stop. + +@findex edebug-set-global-break-condition +@vindex edebug-global-break-condition + You can set or edit the condition expression, stored in +@code{edebug-global-break-condition}, using the @kbd{X} command +(@code{edebug-set-global-break-condition}). + + The global break condition is the simplest way to find where in your +code some event occurs, but it makes code run much more slowly. So you +should reset the condition to @code{nil} when not using it. + +@node Source Breakpoints +@subsubsection Source Breakpoints + +@findex edebug +@cindex source breakpoints + All breakpoints in a definition are forgotten each time you +reinstrument it. To make a breakpoint that won't be forgotten, you can +write a @dfn{source breakpoint}, which is simply a call to the function +@code{edebug} in your source code. You can, of course, make such a call +conditional. For example, in the @code{fac} function, insert the first +line as shown below to stop when the argument reaches zero: + +@example +(defun fac (n) + (if (= n 0) (edebug)) + (if (< 0 n) + (* n (fac (1- n))) + 1)) +@end example + +When the @code{fac} definition is instrumented and the function is +called, the call to @code{edebug} acts as a breakpoint. Depending on +the execution mode, Edebug stops or pauses there. + +If no instrumented code is being executed when @code{edebug} is called, +that function calls @code{debug}. +@c This may not be a good idea anymore. + +@node Trapping Errors +@subsection Trapping Errors + +Emacs normally displays an error message when an error is signaled and +not handled with @code{condition-case}. While Edebug is active, it +normally responds to all unhandled errors. You can customize this with +the options @code{edebug-on-error} and @code{edebug-on-quit}; see +@ref{Edebug Options}. + +When Edebug responds to an error, it shows the last stop point +encountered before the error. This may be the location of a call to a +function which was not instrumented, within which the error actually +occurred. For an unbound variable error, the last known stop point +might be quite distant from the offending variable reference. In that +case you might want to display a full backtrace (@pxref{Edebug Misc}). + +If you change @code{debug-on-error} or @code{debug-on-quit} while +Edebug is active, these changes will be forgotten when Edebug becomes +inactive. Furthermore, during Edebug's recursive edit, these variables +are bound to the values they had outside of Edebug. + +@ignore @c I don't want to document something that works only partly -- rms. +Edebug can also trap signals even if they are handled. If +@code{debug-on-error} is a list of signal names, Edebug will stop when +any of these errors are signaled. Edebug shows you the last known stop +point just as for unhandled errors. After you continue execution, the +error is signaled again (but without being caught by Edebug). Edebug +can only trap errors that are handled if they are signaled in Lisp code +(not subroutines) since it does so by temporarily replacing the +@code{signal} function. +@end ignore + +@node Edebug Views +@subsection Edebug Views + +These Edebug commands let you view aspects of the buffer and window +status that obtained before entry to Edebug. + +@table @kbd +@item v +View the outside window configuration (@code{edebug-view-outside}). + +@item p +Temporarily display the outside current buffer with point at its outside +position (@code{edebug-bounce-point}). With a prefix argument @var{n}, +pause for @var{n} seconds instead. + +@item w +Move point back to the current stop point (@code{edebug-where}) in the +source code buffer. Also, if you use this command in a different window +displaying the same buffer, that window will be used instead to display +the current definition in the future. + +@item W +Forget the saved outside window configuration---so that the current +window configuration will remain unchanged when you next exit Edebug (by +continuing the program). Also toggle the @code{edebug-save-windows} +variable. +@ignore @c This text is implementation-oriented and doesn't emphasize + what users really want to know. +Toggle the @code{edebug-save-windows} variable which indicates whether +the outside window configuration is saved and restored +(@code{edebug-toggle-save-windows}). Also, each time it is toggled on, +make the outside window configuration the same as the current window +configuration. +@end ignore +@end table + +You can view the outside window configuration with @kbd{v} or just +bounce to the point in the current buffer with @kbd{p}, even if +it is not normally displayed. After moving point, you may wish to jump +back to the stop point with @kbd{w} from a source code buffer. + +@ignore I don't understand this -- rms +If you type @kbd{W} twice, Edebug continues saving and restoring an +outside window configuration, but updates it to match the current +configuration. You can use this to add another buffer to be displayed +whenever Edebug is active. However, the automatic redisplay of +@samp{*edebug*} and @samp{*edebug-trace*} may conflict with the buffers +you wish to see unless you have enough windows open. + +With a prefix argument, @code{W} only toggles saving and restoring of +the selected window. To specify a window that is not displaying the +source code buffer, you must use @kbd{C-x X W} from the global keymap. +@end ignore + +@node Edebug Eval +@subsection Evaluation + +While within Edebug, you can evaluate expressions ``as if'' Edebug were +not running. Edebug tries to be invisible to the expression's +evaluation and printing. Evaluation of expressions that cause side +effects will work as expected except for things that Edebug explicitly +saves and restores. @xref{The Outside Context}, for details on this +process. + +@table @kbd +@item e @var{exp} @key{RET} +Evaluate expression @var{exp} in the context outside of Edebug +(@code{edebug-eval-expression}). That is, Edebug tries to minimize its +interference with the evaluation. + +@item M-@key{ESC} @var{exp} @key{RET} +Evaluate expression @var{exp} in the context of Edebug itself. + +@item C-x C-e +Evaluate the expression before point, in the context outside of Edebug +(@code{edebug-eval-last-sexp}). +@end table + +@cindex lexical binding (Edebug) +Edebug supports evaluation of expressions containing references to +lexically bound symbols created by the following constructs in +@file{cl.el} (version 2.03 or later): @code{lexical-let}, +@code{macrolet}, and @code{symbol-macrolet}. + + +@node Eval List +@subsection Evaluation List Buffer + +You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to +evaluate expressions interactively. You can also set up the +@dfn{evaluation list} of expressions to be evaluated automatically each +time Edebug updates the display. + +@table @kbd +@item E +Switch to the evaluation list buffer @samp{*edebug*} +(@code{edebug-visit-eval-list}). +@end table + +In the @samp{*edebug*} buffer you can use the commands of Lisp +Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs +Manual}) as well as these special commands: + +@table @kbd +@item LFD +Evaluate the expression before point, in the outside context, and insert +the value in the buffer (@code{edebug-eval-print-last-sexp}). + +@item C-x C-e +Evaluate the expression before point, in the context outside of Edebug +(@code{edebug-eval-last-sexp}). + +@item C-c C-u +Build a new evaluation list from contents of the buffer +(@code{edebug-update-eval-list}). + +@item C-c C-d +Delete the evaluation list group that point is in +(@code{edebug-delete-eval-item}). + +@item C-c C-w +Switch back to the source code buffer at the current stop point +(@code{edebug-where}). +@end table + +You can evaluate expressions in the evaluation list window with +@kbd{LFD} or @kbd{C-x C-e}, just as you would in @samp{*scratch*}; +but they are evaluated in the context outside of Edebug. + +The expressions you enter interactively (and their results) are lost +when you continue execution; but you can set up an @dfn{evaluation list} +consisting of expressions to be evaluated each time execution stops. + +@cindex evaluation list group +To do this, write one or more @dfn{evaluation list groups} in the +evaluation list buffer. An evaluation list group consists of one or +more Lisp expressions. Groups are separated by comment lines. + +The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the +evaluation list, scanning the buffer and using the first expression of +each group. + +Be careful not to add expressions that execute instrumented code since +that would cause an infinite loop. +@c There ought to be a way to fix this. + +Redisplaying the evaluation list works by inserting each expression in +the buffer, followed by its current value. It also inserts comment +lines so that each expression becomes its own group. Thus, if you type +@kbd{C-c C-u} again without changing the buffer text, the evaluation +list is effectively unchanged. + +If an error occurs during an evaluation from the evaluation list, the +error message is displayed in a string as if it were the result. +Therefore, expressions that use variables not currently valid do not +interrupt your debugging. + +Here is an example of what the evaluation list window looks like after +several expressions have been added to it: + +@smallexample +(current-buffer) +#<buffer *scratch*> +;--------------------------------------------------------------- +(selected-window) +#<window 16 on *scratch*> +;--------------------------------------------------------------- +(point) +196 +;--------------------------------------------------------------- +bad-var +"Symbol's value as variable is void: bad-var" +;--------------------------------------------------------------- +(recursion-depth) +0 +;--------------------------------------------------------------- +this-command +eval-last-sexp +;--------------------------------------------------------------- +@end smallexample + +To delete a group, move point into it and type @kbd{C-c C-d}, or simply +delete the text for the group and update the evaluation list with +@kbd{C-c C-u}. To add a new expression to the evaluation list, insert +the expression at a suitable place, and insert a new comment line. (You +need not insert dashes in the comment line---its contents don't matter.) +Then type @kbd{C-c C-u}. + +After selecting @samp{*edebug*}, you can return to the source code +buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when +you continue execution, and recreated next time it is needed. + + +@node Printing in Edebug +@subsection Printing in Edebug + +@cindex printing (Edebug) +@cindex printing circular structures +@pindex cust-print + If an expression in your program produces a value containing circular +list structure, you may get an error when Edebug attempts to print it. + +@vindex edebug-print-length +@vindex edebug-print-level + One way to cope with circular structure is to set @code{print-length} +or @code{print-level} to truncate the printing. Edebug does this for +you; it binds @code{print-length} and @code{print-level} to 50 if they +were @code{nil}. (Actually, the variables @code{edebug-print-length} +and @code{edebug-print-level} specify the values to use within Edebug.) +@xref{Output Variables}. + + You can also print circular structures and structures that share +elements more informatively by using the @file{cust-print} package. + + To load @file{cust-print} and activate custom printing only for +Edebug, simply use the command @kbd{M-x edebug-install-custom-print}. +To restore the standard print functions, use @kbd{M-x +edebug-uninstall-custom-print}. + + Here is an example of code that creates a circular structure: + +@example +(setq a '(x y)) +(setcar a a)) +@end example + +@noindent +Custom printing prints this as @samp{Result: #1=(#1# y)}. The +@samp{#1=} notation labels the structure that follows it with the label +@samp{1}, and the @samp{#1#} notation references the previously labelled +structure. This notation is used for any shared elements of lists or +vectors. + + Other programs can also use custom printing; see @file{cust-print.el} +for details. + +@node Trace Buffer +@subsection Trace Buffer +@cindex trace buffer + + Edebug can record an execution trace in a buffer named +@samp{*edebug-trace*}. This is a log of function calls and returns, +showing the function names and their arguments and values. To enable +trace recording, set @code{edebug-trace} to a non-@code{nil} value. + + Making a trace buffer is not the same thing as using trace execution +mode (@pxref{Edebug Execution Modes}). + + When trace recording is enabled, each function entry and exit adds +lines to the trace buffer. A function entry record looks like +@samp{::::@{} followed by the function name and argument values. A +function exit record looks like @samp{::::@}} followed by the function +name and result of the function. + + The number of @samp{:}s in an entry shows its recursion depth. You +can use the braces in the trace buffer to find the matching beginning or +end of function calls. + +@findex edebug-print-trace-before +@findex edebug-print-trace-after + You can customize trace recording for function entry and exit by +redefining the functions @code{edebug-print-trace-before} and +@code{edebug-print-trace-after}. + +@defmac edebug-tracing string body@dots{} +This macro requests additional trace information around the execution +of the @var{body} forms. The argument @var{string} specifies text +to put in the trace buffer. All the arguments are evaluated. +@code{edebug-tracing} returns the value of the last form in @var{body}. +@end defmac + +@defun edebug-trace format-string &rest format-args +This function inserts text in the trace buffer. It computes the text +with @code{(apply 'format @var{format-string} @var{format-args})}. +It also inserts a newline to separate entries. +@end defun + + @code{edebug-tracing} and @code{edebug-trace} insert lines in the trace +buffer even if Edebug is not active. + + Adding text to the trace buffer also scrolls its window to show the +last lines inserted. + +@ignore @c too vague +There may be some display problems if you use +tracing along with the evaluation list. +@end ignore + +@node Coverage Testing +@subsection Coverage Testing + +@cindex coverage testing +@cindex frequency counts +@cindex performance analysis +Edebug provides rudimentary coverage testing and display of execution +frequency. All execution of an instrumented function accumulates +frequency counts, both before and after evaluation of each instrumented +expression, even if the execution mode is Go-nonstop. Coverage testing +is more expensive, so it is only done if @code{edebug-test-coverage} is +non-@code{nil}. The command @kbd{M-x edebug-display-freq-count} +displays both the frequency data and the coverage data (if recorded). + +@deffn Command edebug-display-freq-count +This command displays the frequency count data for each line of the +current definition. + +The frequency counts appear comment lines after each line of code, and +you can undo all insertions with one @code{undo} command. The counts +are appear under the @kbd{(} before an expression or the @kbd{)} after +an expression, or on the last character of a symbol. Values do not appear if +they are equal to the previous count on the same line. + +The character @samp{=} following the count for an expression says that +the expression has returned the same value each time it was evaluated +This is the only coverage information that Edebug records. + +To clear the frequency count and coverage data for a definition, +reinstrument it. +@end deffn + +For example, after evaluating @code{(fac 5)} with a source +breakpoint, and setting @code{edebug-test-coverage} to @code{t}, when +the breakpoint is reached, the frequency data looks like this: + +@example +(defun fac (n) + (if (= n 0) (edebug)) +;#6 1 0 =5 + (if (< 0 n) +;#5 = + (* n (fac (1- n))) +;# 5 0 + 1)) +;# 0 +@end example + +The comment lines show that @code{fac} has been called 6 times. The +first @code{if} statement has returned 5 times with the same result each +time; the same is true of the condition on the second @code{if}. +The recursive call of @code{fac} has not returned at all. + + +@node The Outside Context +@subsection The Outside Context + +Edebug tries to be transparent to the program you are debugging, but it +does not succeed completely. Edebug also tries to be transparent when +you evaluate expressions with @kbd{e} or with the evaluation list +buffer, by temporarily restoring the outside context. This section +explains precisely what context Edebug restores, and how Edebug fails to +be completely transparent. + +@c This can be fixed and should be +The same mechanism that avoids masking certain variable's outside values +also currently makes it impossible to set these variables within Edebug. + +@menu +* Checking Whether to Stop:: When Edebug decides what to do. +* Edebug Display Update:: When Edebug updates the display. +* Edebug Recursive Edit:: When Edebug stops execution. +@end menu + +@node Checking Whether to Stop +@subsubsection Checking Whether to Stop + +Whenever Edebug is entered just to think about whether to take some +action, it needs to save and restore certain data. + +@itemize @bullet +@item +@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both +incremented one time to reduce Edebug's impact on the stack. +You could, however, still run out of stack space when using Edebug. + +@item +The state of keyboard macro execution is saved and restored. While +Edebug is active, @code{executing-macro} is bound to +@code{edebug-continue-kbd-macro}. + +@end itemize + + +@node Edebug Display Update +@subsubsection Edebug Display Update + +When Edebug needs to display something (e.g., in trace mode), it saves +the current window configuration from ``outside'' Edebug (@pxref{Window +Configurations,,, elisp, GNU Emacs Lisp Reference Manual}). When +you exit Edebug (by continuing the program), it restores the previous +window configuration. + +Emacs redisplays only when it pauses. Usually, when you continue +execution, the program comes back into Edebug at a breakpoint or after +stepping without pausing or reading input in between. In such cases, +Emacs never gets a chance to redisplay the ``outside'' configuration. +What you see is the same window configuration as the last time Edebug +was active, with no interruption. + +Entry to Edebug for displaying something also saves and restores the +following data, but some of these are deliberately not restored if an +error or quit signal occurs. + +@itemize @bullet +@item +@cindex current buffer point and mark (Edebug) +Which buffer is current, and the positions of point and the mark in the +current buffer, are saved and restored. + +@item +@cindex window configuration (Edebug) +The outside window configuration is saved and restored if +@code{edebug-save-windows} is non-@code{nil} (@pxref{Edebug Display Update}). + +The window configuration is not restored on error or quit, but the +outside selected window @emph{is} reselected even on error or quit in +case a @code{save-excursion} is active. If the value of +@code{edebug-save-windows} is a list, only the listed windows are saved +and restored. + +The window start and horizontal scrolling of the source code buffer are +not restored, however, so that the display remains coherent within Edebug. + +@item +@vindex edebug-save-displayed-buffer-points +The value of point in each displayed buffer is saved and restored if +@code{edebug-save-displayed-buffer-points} is non-@code{nil}. + +@item +The variables @code{overlay-arrow-position} and +@code{overlay-arrow-string} are saved and restored. So you can safely +invoke Edebug from the recursive edit elsewhere in the same buffer. + +@item +@code{cursor-in-echo-area} is locally bound to @code{nil} so that +the cursor shows up in the window. +@end itemize + +@node Edebug Recursive Edit +@subsubsection Edebug Recursive Edit + +When Edebug is entered and actually reads commands from the user, it +saves (and later restores) these additional data: + +@itemize @bullet +@item +The current match data. @xref{Match Data}. + +@item +@code{last-command}, @code{this-command}, @code{last-command-char}, +@code{last-input-char}, @code{last-input-event}, +@code{last-command-event}, @code{last-event-frame}, +@code{last-nonmenu-event}, and @code{track-mouse}. Commands used within +Edebug do not affect these variables outside of Edebug. + +The key sequence returned by @code{this-command-keys} is changed by +executing commands within Edebug and there is no way to reset +the key sequence from Lisp. + +@item +Complex commands executed while in Edebug are added to the variable +@code{command-history}. In rare cases this can alter execution. + +@item +Within Edebug, the recursion depth appears one deeper than the recursion +depth outside Edebug. This is not true of the automatically updated +evaluation list window. + +@item +@code{standard-output} and @code{standard-input} are bound to @code{nil} +by the @code{recursive-edit}, but Edebug temporarily restores them during +evaluations. + +@item +The state of keyboard macro definition is saved and restored. While +Edebug is active, @code{defining-kbd-macro} is bound to +@code{edebug-continue-kbd-macro}. +@end itemize + +@node Instrumenting Macro Calls +@subsection Instrumenting Macro Calls + +When Edebug instruments an expression that calls a Lisp macro, it needs +additional advice to do the job properly. This is because there is no +way to tell which subexpressions of the macro call are forms to be +evaluated. (Evaluation may occur explicitly in the macro body, or when +the resulting expansion is evaluated, or any time later.) You must +explain the format of calls to each macro to enable Edebug to handle it. +To do this, use @code{def-edebug-form-spec} to define the format of +calls to a given macro. + +@deffn Macro def-edebug-spec macro specification +Specify which expressions of a call to macro @var{macro} are forms to be +evaluated. For simple macros, the @var{specification} often looks very +similar to the formal argument list of the macro definition, but +specifications are much more general than macro arguments. + +The @var{macro} argument may actually be any symbol, not just a macro +name. +@end deffn + +Here is a simple example that defines the specification for the +@code{for} macro described in the Emacs Lisp Reference Manual, followed +by an alternative, equivalent specification. + +@example +(def-edebug-spec for + (symbolp "from" form "to" form "do" &rest form)) + +(def-edebug-spec for + (symbolp ['from form] ['to form] ['do body])) +@end example + +Here is a table of the possibilities for @var{specification} and how each +directs processing of arguments. + +@table @bullet + +@item @code{t} +All arguments are instrumented for evaluation. + +@item @code{0} +None of the arguments is instrumented. + +@item a symbol +The symbol must have an Edebug specification which is used instead. +This indirection is repeated until another kind of specification is +found. This allows you to inherit the specification for another macro. + +@item a list +The elements of the list describe the types of the arguments of a +calling form. The possible elements of a specification list are +described in the following sections. +@end table + +@menu +* Specification List:: How to specify complex patterns of evaluation. +* Backtracking:: What Edebug does when matching fails. +@c * Debugging Backquote:: Debugging Backquote +* Specification Examples:: To help understand specifications. +@end menu + + +@node Specification List +@subsubsection Specification List + +@cindex Edebug specification list +A @dfn{specification list} is required for an Edebug specification if +some arguments of a macro call are evaluated while others are not. Some +elements in a specification list match one or more arguments, but others +modify the processing of all following elements. The latter, called +@dfn{specification keywords}, are symbols beginning with @samp{&} (such +as @code{&optional}). + +A specification list may contain sublists which match arguments that are +themselves lists, or it may contain vectors used for grouping. Sublists +and groups thus subdivide the specification list into a hierarchy of +levels. Specification keywords only apply to the remainder of the +sublist or group they are contained in. + +When a specification list involves alternatives or repetition, matching +it against an actual macro call may require backtracking. +@xref{Backtracking}, for more details. + +Edebug specifications provide the power of regular expression matching, +plus some context-free grammar constructs: the matching of sublists with +balanced parentheses, recursive processing of forms, and recursion via +indirect specifications. + +Here's a table of the possible elements of a specification list, with +their meanings: + +@table @code +@item sexp +A single unevaluated Lisp object object. + +@item form +A single evaluated expression, which is instrumented. + +@item place +@findex edebug-unwrap +A place to store a value, as in the Common Lisp @code{setf} construct. + +@item body +Short for @code{&rest form}. See @code{&rest} below. + +@item function-form +A function form: either a quoted function symbol, a quoted lambda +expression, or a form (that should evaluate to a function symbol or +lambda expression). This is useful when an argument that's a lambda +expression might be quoted with @code{quote} rather than +@code{function}, since it instruments the body of the lambda expression +either way. + +@item lambda-expr +A lambda expression with no quoting. + +@item &optional +@kindex &optional @r{(Edebug)} +All following elements in the specification list are optional; as soon +as one does not match, Edebug stops matching at this level. + +To make just a few elements optional followed by non-optional elements, +use @code{[&optional @var{specs}@dots{}]}. To specify that several +elements must all match or none, use @code{&optional +[@var{specs}@dots{}]}. See the @code{defun} example below. + +@item &rest +@kindex &rest @r{(Edebug)} +All following elements in the specification list are repeated zero or +more times. All the elements need not match in the last repetition, +however. + +To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}. +To specify several elements that must all match on every repetition, use +@code{&rest [@var{specs}@dots{}]}. + +@item &or +@kindex &or @r{(Edebug)} +Each of the following elements in the specification list is an +alternative. One of the alternatives must match, or the @code{&or} +specification fails. + +Each list element following @code{&or} is a single alternative. To +group two or more list elements as a single alternative, enclose them in +@code{[@dots{}]}. + +@item ¬ +@kindex ¬ @r{(Edebug)} +Each of the following elements is matched as alternatives as if by using +@code{&or}, but if any of them match, the specification fails. If none +of them match, nothing is matched, but the @code{¬} specification +succeeds. + +@item &define +@kindex &define @r{(Edebug)} +Indicates that the specification is for a defining form. The defining +form itself is not instrumented (i.e. Edebug does not stop before and +after the defining form), but forms inside it typically will be +instrumented. The @code{&define} keyword should be the first element in +a list specification. + +@item nil +This is successful when there are no more arguments to match at the +current argument list level; otherwise it fails. See sublist +specifications and the backquote example below. + +@item gate +@cindex preventing backtracking +No argument is matched but backtracking through the gate is disabled +while matching the remainder of the specifications at this level. This +is primarily used to generate more specific syntax error messages. See +@ref{Backtracking}, for more details. Also see the @code{let} example +below. + +@item @var{other-symbol} +@cindex indirect specifications +Any other symbol in a specification list may be a predicate or an +indirect specification. + +If the symbol has an Edebug specification, this @dfn{indirect +specification} should be either a list specification that is used in +place of the symbol, or a function that is called to process the +arguments. The specification may be defined with @code{def-edebug-spec} +just as for macros. See the @code{defun} example below. + +Otherwise, the symbol should be a predicate. The predicate is called +with the argument and the specification fails if the predicate returns +@code{nil}. In either case, that argument is not instrumented. + +@findex keywordp +@findex lambda-list-keywordp +Some suitable predicates include @code{symbolp}, @code{integerp}, +@code{stringp}, @code{vectorp}, and @code{atom}. +@ignore +, @code{keywordp}, and +@code{lambda-list-keywordp}. The last two, defined in @file{edebug.el}, +test whether the argument is a symbol starting with @samp{@code{:}} and +@samp{@code{&}} respectively. +@end ignore + +@item [@var{elements}@dots{}] +@cindex [@dots{}] (Edebug) +A vector of elements groups the elements into a single @dfn{group +specification}. Its meaning has nothing to do with vectors. + +@item "@var{string}" +The argument should be a symbol named @var{string}. This specification +is equivalent to the quoted symbol, @code{'@var{symbol}}, where the name +of @var{symbol} is the @var{string}, but the string form is preferred. + +@ignore +@item '@var{symbol} @r{or} (quote @var{symbol}) +The argument should be the symbol @var{symbol}. But use a string +specification instead. +@end ignore + +@item (vector @var{elements}@dots{}) +The argument should be a vector whose elements must match the +@var{elements} in the specification. See the backquote example below. + +@item (@var{elements}@dots{}) +Any other list is a @dfn{sublist specification} and the argument must be +a list whose elements match the specification @var{elements}. + +@cindex dotted lists (Edebug) +A sublist specification may be a dotted list and the corresponding list +argument may then be a dotted list. Alternatively, the last @sc{cdr} of a +dotted list specification may be another sublist specification (via a +grouping or an indirect specification, e.g. @code{(spec . [(more +specs@dots{})])}) whose elements match the non-dotted list arguments. +This is useful in recursive specifications such as in the backquote +example below. Also see the description of a @code{nil} specification +above for terminating such recursion. + +Note that a sublist specification of the form @code{(specs . nil)} +means the same as @code{(specs)}, and @code{(specs . +(sublist-elements@dots{}))} means the same as @code{(specs +sublist-elements@dots{})}. +@end table + +@c Need to document extensions with &symbol and :symbol + +Here is a list of additional specifications that may only appear after +@code{&define}. See the @code{defun} example below. + +@table @code +@item name +The argument, a symbol, is the name of the defining form. + +A defining form is not required to have a name field; and it may have +multiple name fields. + +@item :name +This construct does not actually match an argument. The element +following @code{:name} should be a symbol; it is used as an additional +name component for the definition. You can use this to add a unique, +static component to the name of the definition. It may be used more +than once. + +@item arg +The argument, a symbol, is the name of an argument of the defining form. +However, lambda list keywords (symbols starting with @samp{@code{&}}) +are not allowed. See @code{lambda-list} and the example below. + +@item lambda-list +@cindex lambda-list (Edebug) +This matches a lambda list---the argument list of a lambda expression. +The argument should be a list of symbols. + +@item def-body +The argument is the body of code in a definition. This is like +@code{body}, described above, but a definition body must be instrumented +with a different Edebug call that looks up information associated with +the definition. Use @code{def-body} for the highest level list of forms +within the definition. + +@item def-form +The argument is a single, highest-level form in a definition. This is +like @code{def-body}, except use this to match a single form rather than +a list of forms. As a special case, @code{def-form} also means that +tracing information is not output when the form is executed. See the +@code{interactive} example below. +@end table + +@node Backtracking +@subsubsection Backtracking + +@cindex backtracking +@cindex syntax error (Edebug) +If a specification fails to match at some point, this does not +necessarily mean a syntax error will be signaled; instead, +@dfn{backtracking} will take place until all alternatives have been +exhausted. Eventually every element of the argument list must be +matched by some element in the specification, and every required element +in the specification must match some argument. + +Backtracking is disabled for the remainder of a sublist or group when +certain conditions occur, described below. Backtracking is reenabled +when a new alternative is established by @code{&optional}, @code{&rest}, +or @code{&or}. It is also reenabled initially when processing a +sublist or group specification or an indirect specification. + +You might want to disable backtracking to commit to some alternative so +that Edebug can provide a more specific syntax error message. Normally, +if no alternative matches, Edebug reports that none matched, but if one +alternative is committed to, Edebug can report how it failed to match. + +First, backtracking is disabled while matching any of the form +specifications (i.e. @code{form}, @code{body}, @code{def-form}, and +@code{def-body}). These specifications will match any form so any error +must be in the form itself rather than at a higher level. + +Second, backtracking is disabled after successfully matching a quoted +symbol or string specification, since this usually indicates a +recognized construct. If you have a set of alternative constructs that +all begin with the same symbol, you can usually work around this +constraint by factoring the symbol out of the alternatives, e.g., +@code{["foo" &or [first case] [second case] ...]}. + +Third, backtracking may be explicitly disabled by using the +@code{gate} specification. This is useful when you know that +no higher alternatives may apply. + +@ignore +@node Debugging Backquote +@subsubsection Debugging Backquote + +@findex ` (Edebug) +@cindex backquote (Edebug) +Backquote (@kbd{`}) is a macro that results in an expression that may or +may not be evaluated. It is often used to simplify the definition of a +macro to return an expression to be evaluated, but Edebug cannot know +whether the resyult of backquote will be used in any other way. + +The forms inside unquotes (@code{,} and @code{,@@}) are evaluated, and +Edebug instruments them. + +Edebug supports nested backquotes, but there is a limit on the support +of quotes inside of backquotes. Forms quoted with @code{'} are not +normally evaluated, but if the quoted form appears immediately within +@code{,} and @code{,@@} forms, Edebug treats this as a backquoted form +at the next higher level (even if there is not a next higher level; this +is difficult to fix). + +@findex edebug-` +If the backquoted forms are code to be evaluated, you can have Edebug +instrument them by using @code{edebug-`} instead of the regular +@code{`}. Unquoting forms can be used inside @code{edebug-`} anywhere a +form is normally allowed. But @code{(, @var{form})} may be used in two +other places specially recognized by Edebug: wherever a predicate +specification would match, and at the head of a list form where the +function name normally appears. The @var{form} inside a spliced +unquote, @code{(,@@ @var{form})}, will be instrumented, but the unquote +form itself will not be instrumented since this would interfere with the +splicing. + +There is one other complication with using @code{edebug-`}. If the +@code{edebug-`} call is in a macro and the macro may be called from code +that is also instrumented, and if unquoted forms contain any macro +arguments bound to instrumented forms, then you should modify the +specification for the macro as follows: the specifications for those +arguments must use @code{def-form} instead of @code{form}. (This is to +reestablish the Edebugging context for those external forms.) + +For example, the @code{for} macro (@pxref{Problems with Macros,,, elisp, +Emacs Lisp Reference Manual}) is shown here but with @code{edebug-`} +substituted for regular @code{`}. + +@example +(defmacro inc (var) + (list 'setq var (list '1+ var))) + +(defmacro for (var from init to final do &rest body) + (let ((tempvar (make-symbol "max"))) + (edebug-` (let (((, var) (, init)) + ((, tempvar) (, final))) + (while (<= (, var) (, tempvar)) + (,@ body) + (inc (, var))))))) +@end example + +Here is the corresponding modified Edebug specification and a +call of the macro: + +@example +(def-edebug-spec for + (symbolp "from" def-form "to" def-form "do" &rest def-form)) + +(let ((n 5)) + (for i from n to (* n (+ n 1)) do + (message "%s" i))) +@end example + +After instrumenting the @code{for} macro and the macro call, Edebug +first steps to the beginning of the macro call, then into the macro +body, then through each of the unquoted expressions in the backquote +showing the expressions that will be embedded. Then when the macro +expansion is evaluated, Edebug will step through the @code{let} form and +each time it gets to an unquoted form, it will jump back to an argument +of the macro call to step through that expression. Finally stepping +will continue after the macro call. Even more convoluted execution +paths may result when using anonymous functions. + +@vindex edebug-unwrap-results +When the result of an expression is an instrumented expression, it is +difficult to see the expression inside the instrumentation. So +you may want to set the option @code{edebug-unwrap-results} to a +non-@code{nil} value while debugging such expressions, but it would slow +Edebug down to always do this. + +@end ignore +@node Specification Examples +@subsubsection Specification Examples + +It may be easier to understand Edebug specifications by studying +the examples provided here. + +A @code{let} special form has a sequence of bindings and a body. Each +of the bindings is either a symbol or a sublist with a symbol and +optional value. In the specification below, notice the @code{gate} +inside of the sublist to prevent backtracking once a sublist is found. + +@example +(def-edebug-spec let + ((&rest + &or symbolp (gate symbolp &optional form)) + body)) +@end example + +Edebug uses the following specifications for @code{defun} and +@code{defmacro} and the associated argument list and @code{interactive} +specifications. It is necessary to handle interactive forms specially +since an expression argument it is actually evaluated outside of the +function body. + +@example +(def-edebug-spec defmacro defun) ; @r{Indirect ref to @code{defun} spec} +(def-edebug-spec defun + (&define name lambda-list + [&optional stringp] ; @r{Match the doc string, if present.} + [&optional ("interactive" interactive)] + def-body)) + +(def-edebug-spec lambda-list + (([&rest arg] + [&optional ["&optional" arg &rest arg]] + &optional ["&rest" arg] + ))) + +(def-edebug-spec interactive + (&optional &or stringp def-form)) ; @r{Notice: @code{def-form}} +@end example + +The specification for backquote below illustrates how to match +dotted lists and use @code{nil} to terminate recursion. It also +illustrates how components of a vector may be matched. (The actual +specification defined by Edebug does not support dotted lists because +doing so causes very deep recursion that could fail.) + +@example +(def-edebug-spec ` (backquote-form)) ;; alias just for clarity + +(def-edebug-spec backquote-form + (&or ([&or "," ",@@"] &or ("quote" backquote-form) form) + (backquote-form . [&or nil backquote-form]) + (vector &rest backquote-form) + sexp)) +@end example + + +@node Edebug Options +@subsection Edebug Options + + These options affect the behavior of Edebug: + +@defopt edebug-setup-hook +Functions to call before Edebug is used. Each time it is set to a new +value, Edebug will call those functions once and then +@code{edebug-setup-hook} is reset to @code{nil}. You could use this to +load up Edebug specifications associated with a package you are using +but only when you also use Edebug. +@xref{Instrumenting}. +@end defopt + +@defopt edebug-all-defs +If this is non-@code{nil}, normal evaluation of defining forms such as +@code{defun} and @code{defmacro} instruments them for Edebug. This +applies to @code{eval-defun}, @code{eval-region}, and +@code{eval-current-buffer}. @xref{Instrumenting}. +@end defopt + +@defopt edebug-all-forms +If this is non-@code{nil}, the commands @code{eval-defun}, @code{eval-region}, +and @code{eval-current-buffer} instrument all forms, even those that +don't define anything. + +Use the command @kbd{M-x edebug-all-forms} to toggle the value of this +option. +@xref{Instrumenting}. +@end defopt + +@defopt edebug-save-windows +If this is non-@code{nil}, Edebug saves and restores the window +configuration. That takes some time, so if your program does not care +what happens to the window configurations, it is better to set this +variable to @code{nil}. + +If the value is a list, only the listed windows are saved and +restored. + +You can use the @kbd{W} command in Edebug to change this variable +interactively. @xref{Edebug Display Update}. +@end defopt + +@defopt edebug-save-displayed-buffer-points +If non-@code{nil}, Edebug saves and restores point in all buffers. + +Saving and restoring point in other buffers is necessary if you are +debugging code that changes the point of a buffer which is displayed in +a non-selected window. If Edebug or the user then selects the window, +the buffer's point will change to the window's point. + +Saving and restoring point in all buffers is expensive, since it +requires selecting each window twice, so enable this only if you need +it. @xref{Edebug Display Update}. +@end defopt + +@defopt edebug-initial-mode +If this variable is non-@code{nil}, it specifies the initial execution +mode for Edebug when it is first activated. Possible values are +@code{step}, @code{next}, @code{go}, @code{Go-nonstop}, @code{trace}, +@code{Trace-fast}, @code{continue}, and @code{Continue-fast}. + +The default value is @code{step}. +@xref{Edebug Execution Modes}. +@end defopt + +@defopt edebug-trace +@findex edebug-print-trace-before +@findex edebug-print-trace-after +Non-@code{nil} means display a trace of function entry and exit. +Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one +function entry or exit per line, indented by the recursion level. + +The default value is @code{nil}. + +Also see @code{edebug-tracing}. +@xref{Tracing}. +@end defopt + +@defopt edebug-test-coverage +If non-@code{nil}, Edebug tests coverage of all expressions debugged. +This is done by comparing the result of each expression +with the previous result. Coverage is considered OK if two different +results are found. So to sufficiently test the coverage of your code, +try to execute it under conditions that evaluate all expressions more +than once, and produce different results for each expression. + +Use @kbd{M-x edebug-display-freq-count} to display the frequency count +and coverage information for a definition. +@xref{Coverage Testing}. +@end defopt + +@defopt edebug-continue-kbd-macro +If non-@code{nil}, continue defining or executing any keyboard macro +that is executing outside of Edebug. Use this with caution since it is not +debugged. +@xref{Edebug Execution Modes}. +@end defopt + +@defopt edebug-print-length +If non-@code{nil}, bind @code{print-length} to this while printing +results in Edebug. The default value is @code{50}. +@xref{Printing in Edebug}. +@end defopt + +@defopt edebug-print-level +If non-@code{nil}, bind @code{print-level} to this while printing +results in Edebug. The default value is @code{50}. +@end defopt + +@defopt edebug-print-circle +If non-@code{nil}, bind @code{print-circle} to this while printing +results in Edebug. The default value is @code{nil}. +@end defopt + +@defopt edebug-on-error +Edebug binds @code{debug-on-error} to this value, if +@code{debug-on-error} was previously @code{nil}. @xref{Trapping +Errors}. +@end defopt + +@defopt edebug-on-quit +Edebug binds @code{debug-on-quit} to this value, if +@code{debug-on-quit} was previously @code{nil}. @xref{Trapping +Errors}. +@end defopt + + If you change the values of @code{edebug-on-error} or +@code{edebug-on-quit} while Edebug is active, their values won't be used +until the @emph{next} time Edebug is invoked at a deeper command level. + +@ignore +@defopt edebug-unwrap-results +Non-@code{nil} if Edebug should unwrap results of expressions. This is +useful when debugging macros where the results of expressions are +instrumented expressions. But don't do this when results might be +circular, or an infinite loop will result. @xref{Debugging Backquote}. +@end defopt +@end ignore + +@defopt edebug-global-break-condition +If non-@code{nil}, an expression to test for at every stop point. +If the result is non-nil, then break. Errors are ignored. +@xref{Global Break Condition}. +@end defopt +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/eval.texi Mon Mar 28 20:21:44 1994 +0000 @@ -0,0 +1,695 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/eval +@node Evaluation, Control Structures, Symbols, Top +@chapter Evaluation +@cindex evaluation +@cindex interpreter +@cindex interpreter +@cindex value of expression + + The @dfn{evaluation} of expressions in Emacs Lisp is performed by the +@dfn{Lisp interpreter}---a program that receives a Lisp object as input +and computes its @dfn{value as an expression}. How it does this depends +on the data type of the object, according to rules described in this +chapter. The interpreter runs automatically to evaluate portions of +your program, but can also be called explicitly via the Lisp primitive +function @code{eval}. + +@ifinfo +@menu +* Intro Eval:: Evaluation in the scheme of things. +* Eval:: How to invoke the Lisp interpreter explicitly. +* Forms:: How various sorts of objects are evaluated. +* Quoting:: Avoiding evaluation (to put constants in the program). +@end menu + +@node Intro Eval +@section Introduction to Evaluation + + The Lisp interpreter, or evaluator, is the program which computes +the value of an expression which is given to it. When a function +written in Lisp is called, the evaluator computes the value of the +function by evaluating the expressions in the function body. Thus, +running any Lisp program really means running the Lisp interpreter. + + How the evaluator handles an object depends primarily on the data +type of the object. +@end ifinfo + +@cindex forms +@cindex expression + A Lisp object which is intended for evaluation is called an +@dfn{expression} or a @dfn{form}. The fact that expressions are data +objects and not merely text is one of the fundamental differences +between Lisp-like languages and typical programming languages. Any +object can be evaluated, but in practice only numbers, symbols, lists +and strings are evaluated very often. + + It is very common to read a Lisp expression and then evaluate the +expression, but reading and evaluation are separate activities, and +either can be performed alone. Reading per se does not evaluate +anything; it converts the printed representation of a Lisp object to the +object itself. It is up to the caller of @code{read} whether this +object is a form to be evaluated, or serves some entirely different +purpose. @xref{Input Functions}. + + Do not confuse evaluation with command key interpretation. The +editor command loop translates keyboard input into a command (an +interactively callable function) using the active keymaps, and then +uses @code{call-interactively} to invoke the command. The execution of +the command itself involves evaluation if the command is written in +Lisp, but that is not a part of command key interpretation itself. +@xref{Command Loop}. + +@cindex recursive evaluation + Evaluation is a recursive process. That is, evaluation of a form may +call @code{eval} to evaluate parts of the form. For example, evaluation +of a function call first evaluates each argument of the function call, +and then evaluates each form in the function body. Consider evaluation +of the form @code{(car x)}: the subform @code{x} must first be evaluated +recursively, so that its value can be passed as an argument to the +function @code{car}. + +@cindex environment + The evaluation of forms takes place in a context called the +@dfn{environment}, which consists of the current values and bindings of +all Lisp variables.@footnote{This definition of ``environment'' is +specifically not intended to include all the data which can affect the +result of a program.} Whenever the form refers to a variable without +creating a new binding for it, the value of the binding in the current +environment is used. @xref{Variables}. + +@cindex side effect + Evaluation of a form may create new environments for recursive +evaluation by binding variables (@pxref{Local Variables}). These +environments are temporary and vanish by the time evaluation of the form +is complete. The form may also make changes that persist; these changes +are called @dfn{side effects}. An example of a form that produces side +effects is @code{(setq foo 1)}. + + Finally, evaluation of one particular function call, @code{byte-code}, +invokes the @dfn{byte-code interpreter} on its arguments. Although the +byte-code interpreter is not the same as the Lisp interpreter, it uses +the same environment as the Lisp interpreter, and may on occasion invoke +the Lisp interpreter. (@xref{Byte Compilation}.) + + The details of what evaluation means for each kind of form are +described below (@pxref{Forms}). + +@node Eval +@section Eval + + Most often, forms are evaluated automatically, by virtue of their +occurrence in a program being run. On rare occasions, you may need to +write code that evaluates a form that is computed at run time, such as +after reading a form from text being edited or getting one from a +property list. On these occasions, use the @code{eval} function. + + The functions and variables described in this section evaluate +forms, specify limits to the evaluation process, or record recently +returned values. Loading a file also does evaluation +(@pxref{Loading}). + +@defun eval form +This is the basic function for performing evaluation. It evaluates +@var{form} in the current environment and returns the result. How the +evaluation proceeds depends on the type of the object (@pxref{Forms}). + +Since @code{eval} is a function, the argument expression that appears +in a call to @code{eval} is evaluated twice: once as preparation before +@code{eval} is called, and again by the @code{eval} function itself. +Here is an example: + +@example +@group +(setq foo 'bar) + @result{} bar +@end group +@group +(setq bar 'baz) + @result{} baz +;; @r{@code{eval} receives argument @code{bar}, which is the value of @code{foo}} +(eval foo) + @result{} baz +@end group +@end example + +The number of currently active calls to @code{eval} is limited to +@code{max-lisp-eval-depth} (see below). +@end defun + +@cindex evaluation of buffer contents +@deffn Command eval-current-buffer &optional stream +This function evaluates the forms in the current buffer. It reads +forms from the buffer and calls @code{eval} on them until the end of the +buffer is reached, or until an error is signaled and not handled. + +If @var{stream} is supplied, the variable @code{standard-output} is +bound to @var{stream} during the evaluation (@pxref{Output +Functions}). + +@code{eval-current-buffer} always returns @code{nil}. +@end deffn + +@deffn Command eval-region start end &optional stream +This function evaluates the forms in the current buffer in the region +defined by the positions @var{start} and @var{end}. It reads forms from +the region and calls @code{eval} on them until the end of the region is +reached, or until an error is signaled and not handled. + +If @var{stream} is supplied, @code{standard-output} is bound to it +for the duration of the command. + +@code{eval-region} always returns @code{nil}. +@end deffn + +@defvar max-lisp-eval-depth +This variable defines the maximum depth allowed in calls to @code{eval}, +@code{apply}, and @code{funcall} before an error is signaled (with error +message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). This counts +calling the functions mentioned in Lisp expression, and recursive +evaluation of function call arguments and function body forms. + +This limit, with the associated error when it is exceeded, is one way +that Lisp avoids infinite recursion on an ill-defined function. +@cindex Lisp nesting error + +The default value of this variable is 200. If you set it to a value +less than 100, Lisp will reset it to 100 if the given value is reached. + +@code{max-specpdl-size} provides another limit on nesting. +@xref{Local Variables}. +@end defvar + +@defvar values +The value of this variable is a list of the values returned by all the +expressions which were read from buffers (including the minibuffer), +evaluated, and printed. The elements are ordered most recent first. + +@example +@group +(setq x 1) + @result{} 1 +@end group +@group +(list 'A (1+ 2) auto-save-default) + @result{} (A 3 t) +@end group +@group +values + @result{} ((A 3 t) 1 @dots{}) +@end group +@end example + +This variable is useful for referring back to values of forms recently +evaluated. It is generally a bad idea to print the value of +@code{values} itself, since this may be very long. Instead, examine +particular elements, like this: + +@example +@group +;; @r{Refer to the most recent evaluation result.} +(nth 0 values) + @result{} (A 3 t) +@end group +@group +;; @r{That put a new element on,} +;; @r{so all elements move back one.} +(nth 1 values) + @result{} (A 3 t) +@end group +@group +;; @r{This gets the element that was next-to-last} +;; @r{before this example.} +(nth 3 values) + @result{} 1 +@end group +@end example +@end defvar + +@node Forms +@section Kinds of Forms + + A Lisp object that is intended to be evaluated is called a @dfn{form}. +How Emacs evaluates a form depends on its data type. Emacs has three +different kinds of form that are evaluated differently: symbols, lists, +and ``all other types''. This section describes all three kinds, +starting with ``all other types'' which are self-evaluating forms. + +@menu +* Self-Evaluating Forms:: Forms that evaluate to themselves. +* Symbol Forms:: Symbols evaluate as variables. +* Classifying Lists:: How to distinguish various sorts of list forms. +* Function Indirection:: When a symbol appears as the car of a list, + we find the real function via the symbol. +* Function Forms:: Forms that call functions. +* Macro Forms:: Forms that call macros. +* Special Forms:: ``Special forms'' are idiosyncratic primitives, + most of them extremely important. +* Autoloading:: Functions set up to load files + containing their real definitions. +@end menu + +@node Self-Evaluating Forms +@subsection Self-Evaluating Forms +@cindex vector evaluation +@cindex literal evaluation +@cindex self-evaluating form + + A @dfn{self-evaluating form} is any form that is not a list or symbol. +Self-evaluating forms evaluate to themselves: the result of evaluation +is the same object that was evaluated. Thus, the number 25 evaluates to +25, and the string @code{"foo"} evaluates to the string @code{"foo"}. +Likewise, evaluation of a vector does not cause evaluation of the +elements of the vector---it returns the same vector with its contents +unchanged. + +@example +@group +'123 ; @r{An object, shown without evaluation.} + @result{} 123 +@end group +@group +123 ; @r{Evaluated as usual---result is the same.} + @result{} 123 +@end group +@group +(eval '123) ; @r{Evaluated ``by hand''---result is the same.} + @result{} 123 +@end group +@group +(eval (eval '123)) ; @r{Evaluating twice changes nothing.} + @result{} 123 +@end group +@end example + + It is common to write numbers, characters, strings, and even vectors +in Lisp code, taking advantage of the fact that they self-evaluate. +However, it is quite unusual to do this for types that lack a read +syntax, because there's no way to write them textually; however, it is +possible to construct Lisp expressions containing these types by means +of a Lisp program. Here is an example: + +@example +@group +;; @r{Build an expression containing a buffer object.} +(setq buffer (list 'print (current-buffer))) + @result{} (print #<buffer eval.texi>) +@end group +@group +;; @r{Evaluate it.} +(eval buffer) + @print{} #<buffer eval.texi> + @result{} #<buffer eval.texi> +@end group +@end example + +@node Symbol Forms +@subsection Symbol Forms +@cindex symbol evaluation + + When a symbol is evaluated, it is treated as a variable. The result +is the variable's value, if it has one. If it has none (if its value +cell is void), an error is signaled. For more information on the use of +variables, see @ref{Variables}. + + In the following example, we set the value of a symbol with +@code{setq}. Then we evaluate the symbol, and get back the value that +@code{setq} stored. + +@example +@group +(setq a 123) + @result{} 123 +@end group +@group +(eval 'a) + @result{} 123 +@end group +@group +a + @result{} 123 +@end group +@end example + + The symbols @code{nil} and @code{t} are treated specially, so that the +value of @code{nil} is always @code{nil}, and the value of @code{t} is +always @code{t}. Thus, these two symbols act like self-evaluating +forms, even though @code{eval} treats them like any other symbol. + +@node Classifying Lists +@subsection Classification of List Forms +@cindex list form evaluation + + A form that is a nonempty list is either a function call, a macro +call, or a special form, according to its first element. These three +kinds of forms are evaluated in different ways, described below. The +remaining list elements constitute the @dfn{arguments} for the function, +macro, or special form. + + The first step in evaluating a nonempty list is to examine its first +element. This element alone determines what kind of form the list is +and how the rest of the list is to be processed. The first element is +@emph{not} evaluated, as it would be in some Lisp dialects such as +Scheme. + +@node Function Indirection +@subsection Symbol Function Indirection +@cindex symbol function indirection +@cindex indirection +@cindex void function + + If the first element of the list is a symbol then evaluation examines +the symbol's function cell, and uses its contents instead of the +original symbol. If the contents are another symbol, this process, +called @dfn{symbol function indirection}, is repeated until it obtains a +non-symbol. @xref{Function Names}, for more information about using a +symbol as a name for a function stored in the function cell of the +symbol. + + One possible consequence of this process is an infinite loop, in the +event that a symbol's function cell refers to the same symbol. Or a +symbol may have a void function cell, in which case the subroutine +@code{symbol-function} signals a @code{void-function} error. But if +neither of these things happens, we eventually obtain a non-symbol, +which ought to be a function or other suitable object. + +@kindex invalid-function +@cindex invalid function + More precisely, we should now have a Lisp function (a lambda +expression), a byte-code function, a primitive function, a Lisp macro, a +special form, or an autoload object. Each of these types is a case +described in one of the following sections. If the object is not one of +these types, the error @code{invalid-function} is signaled. + + The following example illustrates the symbol indirection process. We +use @code{fset} to set the function cell of a symbol and +@code{symbol-function} to get the function cell contents +(@pxref{Function Cells}). Specifically, we store the symbol @code{car} +into the function cell of @code{first}, and the symbol @code{first} into +the function cell of @code{erste}. + +@smallexample +@group +;; @r{Build this function cell linkage:} +;; ------------- ----- ------- ------- +;; | #<subr car> | <-- | car | <-- | first | <-- | erste | +;; ------------- ----- ------- ------- +@end group +@end smallexample + +@smallexample +@group +(symbol-function 'car) + @result{} #<subr car> +@end group +@group +(fset 'first 'car) + @result{} car +@end group +@group +(fset 'erste 'first) + @result{} first +@end group +@group +(erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.} + @result{} 1 +@end group +@end smallexample + + By contrast, the following example calls a function without any symbol +function indirection, because the first element is an anonymous Lisp +function, not a symbol. + +@smallexample +@group +((lambda (arg) (erste arg)) + '(1 2 3)) + @result{} 1 +@end group +@end smallexample + +@noindent +After that function is called, its body is evaluated; this does +involve symbol function indirection when calling @code{erste}. + + The built-in function @code{indirect-function} provides an easy way to +perform symbol function indirection explicitly. + +@c Emacs 19 feature +@defun indirect-function function +This function returns the meaning of @var{function} as a function. If +@var{function} is a symbol, then it finds @var{function}'s function +definition and starts over with that value. If @var{function} is not a +symbol, then it returns @var{function} itself. + +Here is how you could define @code{indirect-function} in Lisp: + +@smallexample +(defun indirect-function (function) + (if (symbolp function) + (indirect-function (symbol-function function)) + function)) +@end smallexample +@end defun + +@node Function Forms +@subsection Evaluation of Function Forms +@cindex function form evaluation +@cindex function call + + If the first element of a list being evaluated is a Lisp function +object, byte-code object or primitive function object, then that list is +a @dfn{function call}. For example, here is a call to the function +@code{+}: + +@example +(+ 1 x) +@end example + + The first step ni evaluating a function call is to evaluate the +remaining elements of the list in the order they appear. The results +are the actual argument values, one value for each list element. The +next step is to call the function with this list of arguments, +effectively using the function @code{apply} (@pxref{Calling Functions}). +If the function is written in Lisp, the arguments are used to bind the +argument variables of the function (@pxref{Lambda Expressions}); then +the forms in the function body are evaluated in order, and the value of +the last body form becomes the value of the function call. + +@node Macro Forms +@subsection Lisp Macro Evaluation +@cindex macro call evaluation + + If the first element of a list being evaluated is a macro object, then +the list is a @dfn{macro call}. When a macro call is evaluated, the +elements of the rest of the list are @emph{not} initially evaluated. +Instead, these elements themselves are used as the arguments of the +macro. The macro definition computes a replacement form, called the +@dfn{expansion} of the macro, to be evaluated in place of the original +form. The expansion may be any sort of form: a self-evaluating +constant, a symbol or a list. If the expansion is itself a macro call, +this process of expansion repeats until some other sort of form results. + + Normally, the argument expressions are not evaluated as part of +computing the macro expansion, but instead appear as part of the +expansion, so they are evaluated when the expansion is evaluated. + + For example, given a macro defined as follows: + +@example +@group +(defmacro cadr (x) + (list 'car (list 'cdr x))) +@end group +@end example + +@noindent +an expression such as @code{(cadr (assq 'handler list))} is a macro +call, and its expansion is: + +@example +(car (cdr (assq 'handler list))) +@end example + +@noindent +Note that the argument @code{(assq 'handler list)} appears in the +expansion. + +@xref{Macros}, for a complete description of Emacs Lisp macros. + +@node Special Forms +@subsection Special Forms +@cindex special form evaluation + + A @dfn{special form} is a primitive function specially marked so that +its arguments are not all evaluated. Most special forms define control +structures or perform variable bindings---things which functions cannot +do. + + Each special form has its own rules for which arguments are evaluated +and which are used without evaluation. Whether a particular argument is +evaluated may depend on the results of evaluating other arguments. + + Here is a list, in alphabetical order, of all of the special forms in +Emacs Lisp with a reference to where each is described. + +@table @code +@item and +@pxref{Combining Conditions} + +@item catch +@pxref{Catch and Throw} + +@item cond +@pxref{Conditionals} + +@item condition-case +@pxref{Handling Errors} + +@item defconst +@pxref{Defining Variables} + +@item defmacro +@pxref{Defining Macros} + +@item defun +@pxref{Defining Functions} + +@item defvar +@pxref{Defining Variables} + +@item function +@pxref{Anonymous Functions} + +@item if +@pxref{Conditionals} + +@item interactive +@pxref{Interactive Call} + +@item let +@itemx let* +@pxref{Local Variables} + +@item or +@pxref{Combining Conditions} + +@item prog1 +@itemx prog2 +@itemx progn +@pxref{Sequencing} + +@item quote +@pxref{Quoting} + +@item save-excursion +@pxref{Excursions} + +@item save-restriction +@pxref{Narrowing} + +@item save-window-excursion +@pxref{Window Configurations} + +@item setq +@pxref{Setting Variables} + +@item setq-default +@pxref{Creating Buffer-Local} + +@item track-mouse +@pxref{Mouse Tracking} + +@item unwind-protect +@pxref{Nonlocal Exits} + +@item while +@pxref{Iteration} + +@item with-output-to-temp-buffer +@pxref{Temporary Displays} +@end table + +@cindex CL note---special forms compared +@quotation +@b{Common Lisp note:} here are some comparisons of special forms in +GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and +@code{catch} are special forms in both Emacs Lisp and Common Lisp. +@code{defun} is a special form in Emacs Lisp, but a macro in Common +Lisp. @code{save-excursion} is a special form in Emacs Lisp, but +doesn't exist in Common Lisp. @code{throw} is a special form in +Common Lisp (because it must be able to throw multiple values), but it +is a function in Emacs Lisp (which doesn't have multiple +values).@refill +@end quotation + +@node Autoloading +@subsection Autoloading + + The @dfn{autoload} feature allows you to call a function or macro +whose function definition has not yet been loaded into Emacs. It +specifies which file contains the definition. When an autoload object +appears as a symbol's function definition, calling that symbol as a +function automatically loads the specified file; then it calls the real +definition loaded from that file. @xref{Autoload}. + +@node Quoting +@section Quoting +@cindex quoting + + The special form @code{quote} returns its single argument +``unchanged''. + +@defspec quote object +This special form returns @var{object}, without evaluating it. This +provides a way to include constant symbols and lists, which are not +self-evaluating objects, in a program. (It is not necessary to quote +self-evaluating objects such as numbers, strings, and vectors.) + +@cindex @samp{'} for quoting +@cindex quoting using apostrophe +@cindex apostrophe for quoting +Because @code{quote} is used so often in programs, Lisp provides a +convenient read syntax for it. An apostrophe character (@samp{'}) +followed by a Lisp object (in read syntax) expands to a list whose first +element is @code{quote}, and whose second element is the object. Thus, +the read syntax @code{'x} is an abbreviation for @code{(quote x)}. + +Here are some examples of expressions that use @code{quote}: + +@example +@group +(quote (+ 1 2)) + @result{} (+ 1 2) +@end group +@group +(quote foo) + @result{} foo +@end group +@group +'foo + @result{} foo +@end group +@group +''foo + @result{} (quote foo) +@end group +@group +'(quote foo) + @result{} (quote foo) +@end group +@group +['foo] + @result{} [(quote foo)] +@end group +@end example +@end defspec + + Other quoting constructs include @code{function} (@pxref{Anonymous +Functions}), which causes an anonymous lambda expression written in Lisp +to be compiled, and @code{`} (@pxref{Backquote}), which is used to quote +only part of a list, while computing and substituting other parts.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/keymaps.texi Mon Mar 28 20:21:44 1994 +0000 @@ -0,0 +1,1638 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/keymaps +@node Keymaps, Modes, Command Loop, Top +@chapter Keymaps +@cindex keymap + + The bindings between input events and commands are recorded in data +structures called @dfn{keymaps}. Each binding in a keymap associates +(or @dfn{binds}) an individual event type either with another keymap or +with a command. When an event is bound to a keymap, that keymap is +used to look up the next input event; this continues until a command +is found. The whole process is called @dfn{key lookup}. + +@menu +* Keymap Terminology:: Definitions of terms pertaining to keymaps. +* Format of Keymaps:: What a keymap looks like as a Lisp object. +* Creating Keymaps:: Functions to create and copy keymaps. +* Inheritance and Keymaps:: How one keymap can inherit the bindings + of another keymap. +* Prefix Keys:: Defining a key with a keymap as its definition. +* Menu Keymaps:: A keymap can define a menu. +* Active Keymaps:: Each buffer has a local keymap + to override the standard (global) bindings. + A minor mode can also override them. +* Key Lookup:: How extracting elements from keymaps works. +* Functions for Key Lookup:: How to request key lookup. +* Changing Key Bindings:: Redefining a key in a keymap. +* Key Binding Commands:: Interactive interfaces for redefining keys. +* Scanning Keymaps:: Looking through all keymaps, for printing help. +@end menu + +@node Keymap Terminology +@section Keymap Terminology +@cindex key +@cindex keystroke +@cindex key binding +@cindex binding of a key +@cindex complete key +@cindex undefined key + + A @dfn{keymap} is a table mapping event types to definitions (which +can be any Lisp objects, though only certain types are meaningful for +execution by the command loop). Given an event (or an event type) and a +keymap, Emacs can get the event's definition. Events include ordinary +@sc{ASCII} characters, function keys, and mouse actions (@pxref{Input +Events}). + + A sequence of input events that form a unit is called a +@dfn{key sequence}, or @dfn{key} for short. A sequence of one event +is always a key sequence, and so are some multi-event sequences. + + A keymap determines a binding or definition for any key sequence. If +the key sequence is a single event, its binding is the definition of the +event in the keymap. The binding of a key sequence of more than one +event is found by an iterative process: the binding of the first event +is found, and must be a keymap; then the second event's binding is found +in that keymap, and so on until all the events in the key sequence are +used up. + + If the binding of a key sequence is a keymap, we call the key sequence +a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because +no more characters can be added to it). If the binding is @code{nil}, +we call the key @dfn{undefined}. Examples of prefix keys are @kbd{C-c}, +@kbd{C-x}, and @kbd{C-x 4}. Examples of defined complete keys are +@kbd{X}, @key{RET}, and @kbd{C-x 4 C-f}. Examples of undefined complete +keys are @kbd{C-x C-g}, and @kbd{C-c 3}. @xref{Prefix Keys}, for more +details. + + The rule for finding the binding of a key sequence assumes that the +intermediate bindings (found for the events before the last) are all +keymaps; if this is not so, the sequence of events does not form a +unit---it is not really a key sequence. In other words, removing one or +more events from the end of any valid key must always yield a prefix +key. For example, @kbd{C-f C-f} is not a key; @kbd{C-f} is not a prefix +key, so a longer sequence starting with @kbd{C-f} cannot be a key. + + Note that the set of possible multi-event key sequences depends on the +bindings for prefix keys; therefore, it can be different for different +keymaps, and can change when bindings are changed. However, a one-event +sequence is always a key sequence, because it does not depend on any +prefix keys for its well-formedness. + + At any time, several primary keymaps are @dfn{active}---that is, in +use for finding key bindings. These are the @dfn{global map}, which is +shared by all buffers; the @dfn{local keymap}, which is usually +associated with a specific major mode; and zero or more @dfn{minor mode +keymaps} which belong to currently enabled minor modes. (Not all minor +modes have keymaps.) The local keymap bindings shadow (i.e., take +precedence over) the corresponding global bindings. The minor mode +keymaps shadow both local and global keymaps. @xref{Active Keymaps}, +for details. + +@node Format of Keymaps +@section Format of Keymaps +@cindex format of keymaps +@cindex keymap format +@cindex full keymap +@cindex sparse keymap + + A keymap is a list whose @sc{car} is the symbol @code{keymap}. The +remaining elements of the list define the key bindings of the keymap. +Use the function @code{keymapp} (see below) to test whether an object is +a keymap. + + An ordinary element is a cons cell of the form @code{(@var{type} .@: +@var{binding})}. This specifies one binding which applies to events of +type @var{type}. Each ordinary binding applies to events of a +particular @dfn{event type}, which is always a character or a symbol. +@xref{Classifying Events}. + +@cindex default key binding +@c Emacs 19 feature + A cons cell whose @sc{car} is @code{t} is a @dfn{default key binding}; +any event not bound by other elements of the keymap is given +@var{binding} as its binding. Default bindings allow a keymap to bind +all possible event types without having to enumerate all of them. A +keymap that has a default binding completely masks any lower-precedence +keymap. + + If an element of a keymap is a vector, the vector counts as bindings +for all the @sc{ASCII} characters; vector element @var{n} is the binding +for the character with code @var{n}. This is a more compact way to +record lots of bindings. A keymap with such a vector is called a +@dfn{full keymap}. Other keymaps are called @dfn{sparse keymaps}. + + When a keymap contains a vector, it always defines a binding for every +@sc{ASCII} character even if the vector element is @code{nil}. Such a +binding of @code{nil} overrides any default binding in the keymap. +However, default bindings are still meaningful for events that are not +@sc{ASCII} characters. A binding of @code{nil} does @emph{not} +override lower-precedence keymaps; thus, if the local map gives a +binding of @code{nil}, Emacs uses the binding from the global map. + +@cindex keymap prompt string +@cindex overall prompt string +@cindex prompt string of keymap + Aside from bindings, a keymap can also have a string as an element. +This is called the @dfn{overall prompt string} and makes it possible to +use the keymap as a menu. @xref{Menu Keymaps}. + +@cindex meta characters lookup + Keymaps do not directly record bindings for the meta characters, whose +codes are from 128 to 255. Instead, meta characters are regarded for +purposes of key lookup as sequences of two characters, the first of +which is @key{ESC} (or whatever is currently the value of +@code{meta-prefix-char}). Thus, the key @kbd{M-a} is really represented +as @kbd{@key{ESC} a}, and its global binding is found at the slot for +@kbd{a} in @code{esc-map} (@pxref{Prefix Keys}). + + Here as an example is the local keymap for Lisp mode, a sparse +keymap. It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c +C-l}, @kbd{M-C-q}, and @kbd{M-C-x}. + +@example +@group +lisp-mode-map +@result{} +@end group +@group +(keymap + ;; @key{TAB} + (9 . lisp-indent-line) +@end group +@group + ;; @key{DEL} + (127 . backward-delete-char-untabify) +@end group +@group + (3 keymap + ;; @kbd{C-c C-l} + (12 . run-lisp)) +@end group +@group + (27 keymap + ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}} + (17 . indent-sexp) + ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}} + (24 . lisp-send-defun))) +@end group +@end example + +@defun keymapp object +This function returns @code{t} if @var{object} is a keymap, @code{nil} +otherwise. Practically speaking, this function tests for a list whose +@sc{car} is @code{keymap}. + +@example +@group +(keymapp '(keymap)) + @result{} t +@end group +@group +(keymapp (current-global-map)) + @result{} t +@end group +@end example +@end defun + +@node Creating Keymaps +@section Creating Keymaps +@cindex creating keymaps + + Here we describe the functions for creating keymaps. + +@defun make-keymap &optional prompt +This function creates and returns a new full keymap (i.e., one which +contains a vector of length 128 for defining all the @sc{ASCII} +characters). The new keymap initially binds all @sc{ASCII} characters +to @code{nil}, and does not bind any other kind of event. + +@example +@group +(make-keymap) + @result{} (keymap [nil nil nil @dots{} nil nil]) +@end group +@end example + +If you specify @var{prompt}, that becomes the overall prompt string for +the keymap. The prompt string is useful for menu keymaps (@pxref{Menu +Keymaps}). +@end defun + +@defun make-sparse-keymap &optional prompt +This function creates and returns a new sparse keymap with no entries. +The new keymap does not bind any events. The argument @var{prompt} +specifies a prompt string, as in @code{make-keymap}. + +@example +@group +(make-sparse-keymap) + @result{} (keymap) +@end group +@end example +@end defun + +@defun copy-keymap keymap +This function returns a copy of @var{keymap}. Any keymaps which +appear directly as bindings in @var{keymap} are also copied recursively, +and so on to any number of levels. However, recursive copying does not +take place when the definition of a character is a symbol whose function +definition is a keymap; the same symbol appears in the new copy. +@c Emacs 19 feature + +@example +@group +(setq map (copy-keymap (current-local-map))) +@result{} (keymap +@end group +@group + ;; @r{(This implements meta characters.)} + (27 keymap + (83 . center-paragraph) + (115 . center-line)) + (9 . tab-to-tab-stop)) +@end group + +@group +(eq map (current-local-map)) + @result{} nil +@end group +@group +(equal map (current-local-map)) + @result{} t +@end group +@end example +@end defun + +@node Inheritance and Keymaps +@section Inheritance and Keymaps +@cindex keymap inheritance +@cindex inheriting a keymap's bindings + + A keymap can inherit the bindings of another keymap. Do do this, make +a keymap whose ``tail'' is another existing keymap to inherit from. +Such a keymap looks like this: + +@example +(keymap @var{bindings}@dots{} . @var{other-keymap}) +@end example + +@noindent +The effect is that this keymap inherits all the bindings of +@var{other-keymap}, whatever they may be at the time a key is looked up, +but can add to them or override them with @var{bindings}. + +If you change the bindings in @var{other-keymap} using @code{define-key} +or other key-binding functions, these changes are visible in the +inheriting keymap unless shadowed by @var{bindings}. The converse is +not true: if you use @code{define-key} to change the inheriting keymap, +that affects @var{bindings}, but has no effect on @var{other-keymap}. + +Here is an example showing how to make a keymap that inherits +from @code{text-mode-map}: + +@example +(setq my-mode-map (cons 'keymap text-mode-map)) +@end example + +@node Prefix Keys +@section Prefix Keys +@cindex prefix key + + A @dfn{prefix key} has an associated keymap which defines what to do +with key sequences that start with the prefix key. For example, +@kbd{C-x} is a prefix key, and it uses a keymap which is also stored in +the variable @code{ctl-x-map}. Here is a list of the standard prefix +keys of Emacs and their keymaps: + +@itemize @bullet +@item +@vindex esc-map +@findex ESC-prefix +@code{esc-map} is used for events that follow @key{ESC}. Thus, the +global definitions of all meta characters are actually found here. This +map is also the function definition of @code{ESC-prefix}. + +@item +@cindex @kbd{C-h} +@code{help-map} is used for events that follow @kbd{C-h}. + +@item +@cindex @kbd{C-c} +@vindex mode-specific-map +@code{mode-specific-map} is for events that follow @kbd{C-c}. This +map is not actually mode specific; its name was chosen to be informative +for the user in @kbd{C-h b} (@code{display-bindings}), where it +describes the main use of the @kbd{C-c} prefix key. + +@item +@cindex @kbd{C-x} +@vindex ctl-x-map +@findex Control-X-prefix +@code{ctl-x-map} is the variable name for the map used for events +that follow @kbd{C-x}. This map is also the function definition of +@code{Control-X-prefix}. + +@item +@cindex @kbd{C-x 4} +@vindex ctl-x-4-map +@code{ctl-x-4-map} is used for events that follow @kbd{C-x 4}. + +@c Emacs 19 feature +@item +@cindex @kbd{C-x 5} +@vindex ctl-x-5-map +@code{ctl-x-5-map} used is for events that follow @kbd{C-x 5}. + +@c Emacs 19 feature +@item +@cindex @kbd{C-x n} +@cindex @kbd{C-x r} +@cindex @kbd{C-x a} +The prefix keys @kbd{C-x n}, @kbd{C-x r} and @kbd{C-x a} use keymaps +that have no special name. +@end itemize + + The binding of a prefix key is the keymap to use for looking up the +events that follow the prefix key. (It may instead be a symbol whose +function definition is a keymap. The effect is the same, but the symbol +serves as a name for the prefix key.) Thus, the binding of @kbd{C-x} is +the symbol @code{Control-X-prefix}, whose function definition is the +keymap for @kbd{C-x} commands. (The same keymap is also the value of +@code{ctl-x-map}.) + + Prefix key definitions of this sort can appear in any active keymap. +The definitions of @kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as +prefix keys appear in the global map, so these prefix keys are always +available. Major and minor modes can redefine a key as a prefix by +putting a prefix key definition for it in the local map or the minor +mode's map. @xref{Active Keymaps}. + + If a key is defined as a prefix in more than one active map, then its +various definitions are in effect merged: the commands defined in the +minor mode keymaps come first, followed by those in the local map's +prefix definition, and then by those from the global map. + + In the following example, we make @kbd{C-p} a prefix key in the local +keymap, in such a way that @kbd{C-p} is identical to @kbd{C-x}. Then +the binding for @kbd{C-p C-f} is the function @code{find-file}, just +like @kbd{C-x C-f}. The key sequence @kbd{C-p 6} is not found in any +active keymap. + +@example +@group +(use-local-map (make-sparse-keymap)) + @result{} nil +@end group +@group +(local-set-key "\C-p" ctl-x-map) + @result{} nil +@end group +@group +(key-binding "\C-p\C-f") + @result{} find-file +@end group + +@group +(key-binding "\C-p6") + @result{} nil +@end group +@end example + +@defun define-prefix-command symbol +@cindex prefix command + This function defines @var{symbol} as a prefix command: it creates a +full keymap and stores it as @var{symbol}'s function definition. +Storing the symbol as the binding of a key makes the key a prefix key +which has a name. It also sets @var{symbol} as a variable, to have the +keymap as its value. The function returns @var{symbol}. + + In Emacs version 18, only the function definition of @var{symbol} was +set, not the value as a variable. +@end defun + +@node Menu Keymaps +@section Menu Keymaps +@cindex menu keymaps + +@c Emacs 19 feature +A keymap can define a menu as well as bindings for keyboard keys and +mouse button. Menus are usually actuated with the mouse, but they can +work with the keyboard also. + +@menu +* Defining Menus:: How to make a keymap that defines a menu. +* Mouse Menus:: How users actuate the menu with the mouse. +* Keyboard Menus:: How they actuate it with the keyboard. +* Menu Example:: Making a simple menu. +* Menu Bar:: How to customize the menu bar. +* Modifying Menus:: How to add new items to a menu. +@end menu + +@node Defining Menus +@subsection Defining Menus +@cindex defining menus +@cindex menu prompt string +@cindex prompt string (of menu) + +A keymap is suitable for menu use if it has an @dfn{overall prompt +string}, which is a string that appears as an element of the keymap. +(@xref{Format of Keymaps}.) The string should describe the purpose of +the menu. The easiest way to construct a keymap with a prompt string is +to specify the string as an argument when you call @code{make-keymap} or +@code{make-sparse-keymap} (@pxref{Creating Keymaps}). + +The individual bindings in the menu keymap should have item +strings; these strings become the items displayed in the menu. A +binding with a item string looks like this: + +@example +(@var{string} . @var{real-binding}) +@end example + +The item string for a binding should be short---one or two words. It +should describe the action of the command it corresponds to. + +As far as @code{define-key} is concerned, @var{string} is part of the +event's binding. However, @code{lookup-key} returns just +@var{real-binding}, and only @var{real-binding} is used for executing +the key. + +You can also supply a second string, called the help string, as follows: + +@example +(@var{string} @var{help-string} . @var{real-binding}) +@end example + +Currently Emacs does not actually use @var{help-string}; it knows only +how to ignore @var{help-string} in order to extract @var{real-binding}. +In the future we hope to make @var{help-string} serve as extended +documentation for the menu item, available on request. + +If @var{real-binding} is @code{nil}, then @var{string} appears in the +menu but cannot be selected. + +If @var{real-binding} is a symbol, and has a non-@code{nil} +@code{menu-enable} property, that property is an expression which +controls whether the menu item is enabled. Every time the keymap is +used to display a menu, Emacs evaluates the expression, and it enables +the menu item only if the expression's value is non-@code{nil}. When a +menu item is disabled, it is displayed in a ``fuzzy'' fashion, and +cannot be selected with the mouse. + +The order of items in the menu is the same as the order of bindings in +the keymap. Since @code{define-key} puts new bindings at the front, you +should define the menu items starting at the bottom of the menu and +moving to the top, if you care about the order. When you add an item to +an existing menu, you can specify its position in the menu using +@code{define-key-after} (@pxref{Modifying Menus}). + +You've probably noticed that menu items show the equivalent keyboard key +sequence (if any) to invoke the same command. To save time on +recalculation, menu display caches this information in a sublist in the +binding, like this: + +@c This line is not too long--rms. +@example +(@var{string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding}) +@end example + +Don't put these sublists in the menu item yourself; menu display +calculates them automatically. Don't add keyboard equivalents to the +item string yourself, for that is redundant. + +@node Mouse Menus +@subsection Menus and the Mouse + +The way to make a menu keymap produce a menu is to make it the +definition of a prefix key. + +If the prefix key ends with a mouse event, Emacs handles the menu keymap +by popping up a visible menu, so that the user can select a choice with +the mouse. When the user clicks on a menu item, the event generated is +whatever character or symbol has the binding which brought about that +menu item. (A menu item may generate a series of events if the menu has +multiple levels or comes from the menu bar.) + +It's often best to use a button-down event to trigger the menu. Then +the user can select a menu item by releasing the button. + +A single keymap can appear as multiple menu panes, if you explicitly +arrange for this. The way to do this is to make a keymap for each pane, +then create a binding for each of those maps in the main keymap of the +menu. Give each of these bindings a item string that starts with +@samp{@@}. The rest of the item string becomes the name of the pane. +See the file @file{lisp/mouse.el} for an example of this. Any ordinary +bindings with @samp{@@}-less item strings are grouped into one pane, +which appears along with the other panes explicitly created for the +submaps. + +X toolkit menus don't have panes; instead, they can have submenus. +Every nested keymap becomes a submenu, whether the item string starts +with @samp{@@} or not. In a toolkit version of Emacs, The only thing +special about @samp{@@} at the beginning of an item string is that the +@samp{@@} doesn't appear in the menu item. + +You can also get multiple panes from separate keymaps. The full +definition of a prefix key always comes from merging the definitions +supplied by the various active keymaps (minor mode, local, and +global). When more than one of these keymaps is a menu, each of them +makes a separate pane or panes. @xref{Active Keymaps}. + +In toolkit versions of Emacs, menus don't have panes, so submenus are +used to represent the separate keymaps. Each keymap's contribution +becomes one submenu. + +A Lisp program can explicitly pop up a menu and receive the user's +choice. You can use keymaps for this also. @xref{Pop-Up Menus}. + +@node Keyboard Menus +@subsection Menus and the Keyboard + +When a prefix key ending with a keyboard event (a character or function +key) has a definition that is a menu keymap, the user can use the +keyboard to choose a menu item. + +Emacs displays the menu alternatives (the item strings of the +bindings) in the echo area. If they don't all fit at once, the user can +type @key{SPC} to see the next line of alternatives. Successive uses of +@key{SPC} eventually get to the end of the menu and then cycle around to +the beginning. + +When the user has found the desired alternative from the menu, he or she +should type the corresponding character---the one whose binding is that +alternative. + +In a menu intended for keyboard use, each menu item must clearly +indicate what character to type. The best convention to use is to make +the character the first letter of the item string. That is something +users will understand without being told. + +This way of using menus in an Emacs-like editor was inspired by the +Hierarkey system. + +@defvar menu-prompt-more-char +This variable specifies the character to use to ask to see +the next line of a menu. Its initial value is 32, the code +for @key{SPC}. +@end defvar + +@node Menu Example +@subsection Menu Example + + Here is a simple example of how to set up a menu for mouse use. + +@example +(defvar my-menu-map + (make-sparse-keymap "Key Commands <==> Functions")) +(fset 'help-for-keys my-menu-map) + +(define-key my-menu-map [bindings] + '("List all keystroke commands" . describe-bindings)) +(define-key my-menu-map [key] + '("Describe key briefly" . describe-key-briefly)) +(define-key my-menu-map [key-verbose] + '("Describe key verbose" . describe-key)) +(define-key my-menu-map [function] + '("Describe Lisp function" . describe-function)) +(define-key my-menu-map [where-is] + '("Where is this command" . where-is)) + +(define-key global-map [C-S-down-mouse-1] 'help-for-keys) +@end example + + The symbols used in the key sequences bound in the menu are fictitious +``function keys''; they don't appear on the keyboard, but that doesn't +stop you from using them in the menu. Their names were chosen to be +mnemonic, because they show up in the output of @code{where-is} and +@code{apropos} to identify the corresponding menu items. + + However, if you want the menu to be usable from the keyboard as well, +you must bind real @sc{ASCII} characters as well as fictitious function +keys. + +@node Menu Bar +@subsection The Menu Bar +@cindex menu bar + + Most window systems allow each frame to have a @dfn{menu bar}---a +permanently displayed menu stretching horizontally across the top of the +frame. The items of the menu bar are the subcommands of the fake +``function key'' @code{menu-bar}, as defined by all the active keymaps. + + To add an item to the menu bar, invent a fake ``function key'' of your +own (let's call it @var{key}), and make a binding for the key sequence +@code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap, +so that pressing a button on the menu bar item leads to another menu. + + When more than one active keymap defines the same fake function key +for the menu bar, the item appears just once. If the user clicks on +that menu bar item, it brings up a single, combined submenu containing +all the subcommands of that item---the global subcommands, the local +subcommands, and the minor mode subcommands, all together. + + In order for a frame to display a menu bar, its @code{menu-bar-lines} +parameter must be greater than zero. Emacs uses just one line for the +menu bar itself; if you specify more than one line, the other lines +serve to separate the menu bar from the windows in the frame. We +recommend you try 1 or 2 as the value of @code{menu-bar-lines}. @xref{X +Frame Parameters}. + + Here's an example of setting up a menu bar item: + +@smallexample +(modify-frame-parameters (selected-frame) '((menu-bar-lines . 2))) + +;; @r{Make a menu keymap (with a prompt string)} +;; @r{and make it the menu bar item's definition.} +(define-key global-map [menu-bar words] + (cons "Words" (make-sparse-keymap "Words"))) + +@group +;; @r{Define specific subcommands in the item's menu.} +(define-key global-map + [menu-bar words forward] + '("Forward word" . forward-word)) +@end group +@group +(define-key global-map + [menu-bar words backward] + '("Backward word" . backward-word)) +@end group +@end smallexample + + A local keymap can cancel a menu bar item made by the global keymap by +rebinding the same fake function key with @code{undefined} as the +binding. For example, this is how Dired suppresses the @samp{Edit} menu +bar item: + +@example +(define-key dired-mode-map [menu-bar edit] 'undefined) +@end example + +@noindent +@code{edit} is the fake function key used by the global map for the +@samp{Edit} menu bar item. The main reason to suppress a global +menu bar item is to regain space for mode-specific items. + +@defvar menu-bar-final-items +Normally the menu bar shows global items followed by items defined by the +local maps. + +This variable holds a list of fake function keys for items to display at +the end of the menu bar rather than in normal sequence. The default +value is @code{(help)}; thus, the @samp{Help} menu item normally appears +at the end of the menu bar, following local menu items. +@end defvar + +@node Modifying Menus +@subsection Modifying Menus + + When you insert a new item in an existing menu, you probably want to +put it in a particular place among the menu's existing items. If you +use @code{define-key} to add the item, it normally goes at the front of +the menu. To put it elsewhere, use @code{define-key-after}: + +@defun define-key-after map key binding after +Define a binding in @var{map} for @var{key}, with value @var{binding}, +just like @code{define-key}, but position the binding in @var{map} after +the binding for the key @var{after}. For example, + +@example +(define-key-after my-menu [drink] + '("Drink" . drink-command) [eat]) +@end example + +@noindent +makes a binding for the fake function key @key{drink} and puts it +right after the binding for @key{eat}. +@end defun + +@node Active Keymaps +@section Active Keymaps +@cindex active keymap +@cindex global keymap +@cindex local keymap + + Emacs normally contains many keymaps; at any given time, just a few of +them are @dfn{active} in that they participate in the interpretation +of user input. These are the global keymap, the current buffer's +local keymap, and the keymaps of any enabled minor modes. + + The @dfn{global keymap} holds the bindings of keys that are defined +regardless of the current buffer, such as @kbd{C-f}. The variable +@code{global-map} holds this keymap, which is always active. + + Each buffer may have another keymap, its @dfn{local keymap}, which may +contain new or overriding definitions for keys. The current buffer's +local keymap is always active except when @code{overriding-local-map} +overrides it. Text properties can specify an alternative local map for +certain parts of the buffer; see @ref{Special Properties}. + + Each minor mode may have a keymap; if it does, the keymap is active +when the minor mode is enabled. + + The variable @code{overriding-local-map}, if non-@code{nil}, specifies +another local keymap that overrides the buffer's local map and all the +minor mode keymaps. + + All the active keymaps are used together to determine what command to +execute when a key is entered. Emacs searches these maps one by one, in +order of decreasing precedence, until it finds a binding in one of the maps. + + Normally, Emacs @emph{first} searches for the key in the minor mode +maps (one map at a time); if they do not supply a binding for the key, +Emacs searches the local map; if that too has no binding, Emacs then +searches the global map. However, if @code{overriding-local-map} is +non-@code{nil}, Emacs searches that map first, followed by the global +map. + + The procedure for searching a single keymap is called +@dfn{key lookup}; see @ref{Key Lookup}. + +@cindex major mode keymap + Since every buffer that uses the same major mode normally uses the +very same local keymap, it may appear as if the keymap is local to the +mode. A change to the local keymap of a buffer (using +@code{local-set-key}, for example) will be seen also in the other +buffers that share that keymap. + + The local keymaps that are used for Lisp mode, C mode, and several +other major modes exist even if they have not yet been used. These +local maps are the values of the variables @code{lisp-mode-map}, +@code{c-mode-map}, and so on. For most other modes, which are less +frequently used, the local keymap is constructed only when the mode is +used for the first time in a session. + + The minibuffer has local keymaps, too; they contain various completion +and exit commands. @xref{Intro to Minibuffers}. + + @xref{Standard Keymaps}, for a list of standard keymaps. + +@defvar global-map + This variable contains the default global keymap that maps Emacs +keyboard input to commands. The global keymap is normally this keymap. +The default global keymap is a full keymap that binds +@code{self-insert-command} to all of the printing characters. + +It is normal practice to change the bindings in the global map, but you +should not assign this variable any value other than the keymap it starts +out with. +@end defvar + +@defun current-global-map + This function returns the current global keymap. This is the +same as the value of @code{global-map} unless you change one or the +other. + +@example +@group +(current-global-map) +@result{} (keymap [set-mark-command beginning-of-line @dots{} + delete-backward-char]) +@end group +@end example +@end defun + +@defun current-local-map + This function returns the current buffer's local keymap, or @code{nil} +if it has none. In the following example, the keymap for the +@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap +in which the entry for @key{ESC}, @sc{ASCII} code 27, is another sparse +keymap. + +@example +@group +(current-local-map) +@result{} (keymap + (10 . eval-print-last-sexp) + (9 . lisp-indent-line) + (127 . backward-delete-char-untabify) +@end group +@group + (27 keymap + (24 . eval-defun) + (17 . indent-sexp))) +@end group +@end example +@end defun + +@defun current-minor-mode-maps +This function returns a list of the keymaps of currently enabled minor modes. +@end defun + +@defun use-global-map keymap + This function makes @var{keymap} the new current global keymap. It +returns @code{nil}. + + It is very unusual to change the global keymap. +@end defun + +@defun use-local-map keymap + This function makes @var{keymap} the new local keymap of the current +buffer. If @var{keymap} is @code{nil}, then the buffer has no local +keymap. @code{use-local-map} returns @code{nil}. Most major mode +commands use this function. +@end defun + +@c Emacs 19 feature +@defvar minor-mode-map-alist +This variable is an alist describing keymaps that may or may not be +active according to the values of certain variables. Its elements look +like this: + +@example +(@var{variable} . @var{keymap}) +@end example + +The keymap @var{keymap} is active whenever @var{variable} has a +non-@code{nil} value. Typically @var{variable} is the variable which +enables or disables a minor mode. @xref{Keymaps and Minor Modes}. + +Note that elements of @code{minor-mode-map-alist} do not have the same +structure as elements of @code{minor-mode-alist}. The map must be the +@sc{cdr} of the element; a list with the map as the second element will +not do. + +What's more, the keymap itself must appear in the @sc{cdr}. It does not +work to store a variable in the @sc{cdr} and make the map the value of +that variable. + +When more than one minor mode keymap is active, their order of priority +is the order of @code{minor-mode-map-alist}. But you should design +minor modes so that they don't interfere with each other. If you do +this properly, the order will not matter. + +See also @code{minor-mode-key-binding} in @ref{Functions for Key +Lookup}. See @ref{Keymaps and Minor Modes}, for more information about +minor modes. +@end defvar + +@defvar overriding-local-map +If non-@code{nil}, a keymap to use instead of the buffer's local keymap +and instead of all the minor mode keymaps. This keymap, if any, +overrides all other maps that would have been active, except for the +current global map. +@end defvar + +@node Key Lookup +@section Key Lookup +@cindex key lookup +@cindex keymap entry + + @dfn{Key lookup} is the process of finding the binding of a key +sequence from a given keymap. Actual execution of the binding is not +part of key lookup. + + Key lookup uses just the event types of each event in the key +sequence; the rest of the event is ignored. In fact, a key sequence +used for key lookup may designate mouse events with just their types +(symbols) instead of with entire mouse events (lists). @xref{Input +Events}. Such a pseudo-key-sequence is insufficient for +@code{command-execute}, but it is sufficient for looking up or rebinding +a key. + + When the key sequence consists of multiple events, key lookup +processes the events sequentially: the binding of the first event is +found, and must be a keymap; then the second event's binding is found in +that keymap, and so on until all the events in the key sequence are used +up. (The binding thus found for the last event may or may not be a +keymap.) Thus, the process of key lookup is defined in terms of a +simpler process for looking up a single event in a keymap. How that is +done depends on the type of object associated with the event in that +keymap. + + Let's use the term @dfn{keymap entry} to describe the value found by +looking up an event type in a keymap. (This doesn't include the item +string and other extra elements in menu key bindings because +@code{lookup-key} and other key lookup functions don't include them in +the returned value.) While any Lisp object may be stored in a keymap as +a keymap entry, not all make sense for key lookup. Here is a list of +the meaningful kinds of keymap entries: + +@table @asis +@item @code{nil} +@cindex @code{nil} in keymap +@code{nil} means that the events used so far in the lookup form an +undefined key. When a keymap fails to mention an event type at all, and +has no default binding, that is equivalent to a binding of @code{nil} +for that event type. + +@item @var{keymap} +@cindex keymap in keymap +The events used so far in the lookup form a prefix key. The next +event of the key sequence is looked up in @var{keymap}. + +@item @var{command} +@cindex command in keymap +The events used so far in the lookup form a complete key, +and @var{command} is its binding. + +@item @var{string} +@itemx @var{vector} +@cindex string in keymap +The events used so far in the lookup form a complete key, whose +binding is a keyboard macro. See @ref{Keyboard Macros}, for more +information. + +@item @var{list} +@cindex list in keymap +The meaning of a list depends on the types of the elements of the list. + +@itemize @bullet +@item +If the @sc{car} of @var{list} is the symbol @code{keymap}, then the list +is a keymap, and is treated as a keymap (see above). + +@item +@cindex @code{lambda} in keymap +If the @sc{car} of @var{list} is @code{lambda}, then the list is a +lambda expression. This is presumed to be a command, and is treated as +such (see above). + +@item +If the @sc{car} of @var{list} is a keymap and the @sc{cdr} is an event +type, then this is an @dfn{indirect entry}: + +@example +(@var{othermap} . @var{othertype}) +@end example + +When key lookup encounters an indirect entry, it looks up instead the +binding of @var{othertype} in @var{othermap} and uses that. + +This feature permits you to define one key as an alias for another key. +For example, an entry whose @sc{car} is the keymap called @code{esc-map} +and whose @sc{cdr} is 32 (the code for space) means, ``Use the global +binding of @kbd{Meta-@key{SPC}}, whatever that may be.'' +@end itemize + +@item @var{symbol} +@cindex symbol in keymap +The function definition of @var{symbol} is used in place of +@var{symbol}. If that too is a symbol, then this process is repeated, +any number of times. Ultimately this should lead to an object which is +a keymap, a command or a keyboard macro. A list is allowed if it is a +keymap or a command, but indirect entries are not understood when found +via symbols. + +Note that keymaps and keyboard macros (strings and vectors) are not +valid functions, so a symbol with a keymap, string or vector as its +function definition is also invalid as a function. It is, however, +valid as a key binding. If the definition is a keyboard macro, then the +symbol is also valid as an argument to @code{command-execute} +(@pxref{Interactive Call}). + +@cindex @code{undefined} in keymap +The symbol @code{undefined} is worth special mention: it means to treat +the key as undefined. Strictly speaking, the key is defined, and its +binding is the command @code{undefined}; but that command does the same +thing that is done automatically for an undefined key: it rings the bell +(by calling @code{ding}) but does not signal an error. + +@cindex preventing prefix key +@code{undefined} is used in local keymaps to override a global key +binding and make the key ``undefined'' locally. A local binding of +@code{nil} would fail to do this because it would not override the +global binding. + +@item @var{anything else} +If any other type of object is found, the events used so far in the +lookup form a complete key, and the object is its binding, but the +binding is not executable as a command. +@end table + + In short, a keymap entry may be a keymap, a command, a keyboard macro, +a symbol which leads to one of them, or an indirection or @code{nil}. +Here is an example of a sparse keymap with two characters bound to +commands and one bound to another keymap. This map is the normal value +of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB}, +127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for +@kbd{C-x}. + +@example +@group +(keymap (9 . lisp-indent-line) + (127 . backward-delete-char-untabify) + (27 keymap (17 . indent-sexp) (24 . eval-defun))) +@end group +@end example + +@node Functions for Key Lookup +@section Functions for Key Lookup + + Here are the functions and variables pertaining to key lookup. + +@defun lookup-key keymap key &optional accept-defaults +This function returns the definition of @var{key} in @var{keymap}. If +the string or vector @var{key} is not a valid key sequence according to +the prefix keys specified in @var{keymap} (which means it is ``too +long'' and has extra events at the end), then the value is a number, the +number of events at the front of @var{key} that compose a complete key. + +@c Emacs 19 feature +If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key} +considers default bindings as well as bindings for the specific events +in @var{key}. Otherwise, @code{lookup-key} reports only bindings for +the specific sequence @var{key}, ignoring default bindings except when +an element of @var{key} is @code{t}. + +All the other functions described in this chapter that look up keys use +@code{lookup-key}. + +@example +@group +(lookup-key (current-global-map) "\C-x\C-f") + @result{} find-file +@end group +@group +(lookup-key (current-global-map) "\C-x\C-f12345") + @result{} 2 +@end group +@end example + + If @var{key} contains a meta character, that character is implicitly +replaced by a two-character sequence: the value of +@code{meta-prefix-char}, followed by the corresponding non-meta +character. Thus, the first example below is handled by conversion into +the second example. + +@example +@group +(lookup-key (current-global-map) "\M-f") + @result{} forward-word +@end group +@group +(lookup-key (current-global-map) "\ef") + @result{} forward-word +@end group +@end example + +Unlike @code{read-key-sequence}, this function does not modify the +specified events in ways that discard information (@pxref{Key Sequence +Input}). In particular, it does not convert letters to lower case and +it does not change drag events to clicks. +@end defun + +@deffn Command undefined +Used in keymaps to undefine keys. It calls @code{ding}, but does +not cause an error. +@end deffn + +@defun key-binding key &optional accept-defaults +This function returns the binding for @var{key} in the current +keymaps, trying all the active keymaps. The result is @code{nil} if +@var{key} is undefined in the keymaps. + +@c Emacs 19 feature +The argument @var{accept-defaults} controls checking for default +bindings, as in @code{lookup-key}. + +An error is signaled if @var{key} is not a string or a vector. + +@example +@group +(key-binding "\C-x\C-f") + @result{} find-file +@end group +@end example +@end defun + +@defun local-key-binding key &optional accept-defaults +This function returns the binding for @var{key} in the current +local keymap, or @code{nil} if it is undefined there. + +@c Emacs 19 feature +The argument @var{accept-defaults} controls checking for default bindings, +as in @code{lookup-key} (above). +@end defun + +@defun global-key-binding key &optional accept-defaults +This function returns the binding for command @var{key} in the +current global keymap, or @code{nil} if it is undefined there. + +@c Emacs 19 feature +The argument @var{accept-defaults} controls checking for default bindings, +as in @code{lookup-key} (above). +@end defun + +@c Emacs 19 feature +@defun minor-mode-key-binding key &optional accept-defaults +This function returns a list of all the active minor mode bindings of +@var{key}. More precisely, it returns an alist of pairs +@code{(@var{modename} . @var{binding})}, where @var{modename} is the the +variable which enables the minor mode, and @var{binding} is @var{key}'s +binding in that mode. If @var{key} has no minor-mode bindings, the +value is @code{nil}. + +If the first binding is not a prefix command, all subsequent bindings +from other minor modes are omitted, since they would be completely +shadowed. Similarly, the list omits non-prefix bindings that follow +prefix bindings. + +The argument @var{accept-defaults} controls checking for default +bindings, as in @code{lookup-key} (above). +@end defun + +@defvar meta-prefix-char +@cindex @key{ESC} +This variable is the meta-prefix character code. It is used when +translating a meta character to a two-character sequence so it can be +looked up in a keymap. For useful results, the value should be a prefix +event (@pxref{Prefix Keys}). The default value is 27, which is the +@sc{ASCII} code for @key{ESC}. + +As long as the value of @code{meta-prefix-char} remains 27, key +lookup translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally +defined as the @code{backward-word} command. However, if you set +@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will +translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the +@code{switch-to-buffer} command. + +@smallexample +@group +meta-prefix-char ; @r{The default value.} + @result{} 27 +@end group +@group +(key-binding "\M-b") + @result{} backward-word +@end group +@group +?\C-x ; @r{The print representation} + @result{} 24 ; @r{of a character.} +@end group +@group +(setq meta-prefix-char 24) + @result{} 24 +@end group +@group +(key-binding "\M-b") + @result{} switch-to-buffer ; @r{Now, typing @kbd{M-b} is} + ; @r{like typing @kbd{C-x b}.} + +(setq meta-prefix-char 27) ; @r{Avoid confusion!} + @result{} 27 ; @r{Restore the default value!} +@end group +@end smallexample +@end defvar + +@node Changing Key Bindings +@section Changing Key Bindings +@cindex changing key bindings +@cindex rebinding + + The way to rebind a key is to change its entry in a keymap. If you +change the global keymap, the change is effective in all buffers (except +those that override the global binding with a local one). If you change +the current buffer's local map, that usually affects all buffers using +the same major mode. The @code{global-set-key} and @code{local-set-key} +functions are convenient interfaces for these operations. Or you can +use @code{define-key} and specify explicitly which map to change. + + People often use @code{global-set-key} in their @file{.emacs} file for +simple customization. For example, + +@smallexample +(global-set-key "\C-x\C-\\" 'next-line) +@end smallexample + +@noindent +or + +@smallexample +(global-set-key [?\C-x ?\C-\\] 'next-line) +@end smallexample + +@noindent +redefines @kbd{C-x C-\} to move down a line. + +@smallexample +(global-set-key [M-mouse-1] 'mouse-set-point) +@end smallexample + +@noindent +redefines the first (leftmost) mouse button, typed with the Meta key, to +set point where you click. + +@cindex meta character key constants +@cindex control character key constants + In writing the key sequence to rebind, it is useful to use the special +escape sequences for control and meta characters (@pxref{String Type}). +The syntax @samp{\C-} means that the following character is a control +character and @samp{\M-} means that the following character is a meta +character. Thus, the string @code{"\M-x"} is read as containing a +single @kbd{M-x}, @code{"\C-f"} is read as containing a single +@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as +containing a single @kbd{C-M-x}. + + For the functions below, an error is signaled if @var{keymap} is not a +keymap or if @var{key} is not a string or vector representing a key +sequence. You can use event types (symbols) as shorthand for events +that are lists. + +@defun define-key keymap key binding + This function sets the binding for @var{key} in @var{keymap}. (If +@var{key} is more than one event long, the change is actually made +in another keymap reached from @var{keymap}.) The argument +@var{binding} can be any Lisp object, but only certain types are +meaningful. (For a list of meaningful types, see @ref{Key Lookup}.) +The value returned by @code{define-key} is @var{binding}. + +@cindex invalid prefix key error +@cindex key sequence error + Every prefix of @var{key} must be a prefix key (i.e., bound to a +keymap) or undefined; otherwise an error is signaled. + +If some prefix of @var{key} is undefined, then @code{define-key} defines +it as a prefix key so that the rest of @var{key} may be defined as +specified. +@end defun + + This example creates a sparse keymap and makes a number of bindings: + +@smallexample +@group +(setq map (make-sparse-keymap)) + @result{} (keymap) +@end group +@group +(define-key map "\C-f" 'forward-char) + @result{} forward-char +@end group +@group +map + @result{} (keymap (6 . forward-char)) +@end group + +@group +;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.} +(define-key map "\C-xf" 'forward-word) + @result{} forward-word +@end group +@group +map +@result{} (keymap + (24 keymap ; @kbd{C-x} + (102 . forward-word)) ; @kbd{f} + (6 . forward-char)) ; @kbd{C-f} +@end group + +@group +;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.} +(define-key map "\C-p" ctl-x-map) +;; @code{ctl-x-map} +@result{} [nil @dots{} find-file @dots{} backward-kill-sentence] +@end group + +@group +;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.} +(define-key map "\C-p\C-f" 'foo) +@result{} 'foo +@end group +@group +map +@result{} (keymap ; @r{Note @code{foo} in @code{ctl-x-map}.} + (16 keymap [nil @dots{} foo @dots{} backward-kill-sentence]) + (24 keymap + (102 . forward-word)) + (6 . forward-char)) +@end group +@end smallexample + +@noindent +Note that storing a new binding for @kbd{C-p C-f} actually works by +changing an entry in @code{ctl-x-map}, and this has the effect of +changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the +default global map. + +@defun substitute-key-definition olddef newdef keymap &optional oldmap +@cindex replace bindings +This function replaces @var{olddef} with @var{newdef} for any keys in +@var{keymap} that were bound to @var{olddef}. In other words, +@var{olddef} is replaced with @var{newdef} wherever it appears. The +function returns @code{nil}. + +For example, this redefines @kbd{C-x C-f}, if you do it in an Emacs with +standard bindings: + +@smallexample +@group +(substitute-key-definition + 'find-file 'find-file-read-only (current-global-map)) +@end group +@end smallexample + +@c Emacs 19 feature +If @var{oldmap} is non-@code{nil}, then its bindings determine which +keys to rebind. The rebindings still happen in @var{newmap}, not in +@var{oldmap}. Thus, you can change one map under the control of the +bindings in another. For example, + +@smallexample +(substitute-key-definition + 'delete-backward-char 'my-funny-delete + my-map global-map) +@end smallexample + +@noindent +puts the special deletion command in @code{my-map} for whichever keys +are globally bound to the standard deletion command. + +@ignore +@c Emacs 18 only +Prefix keymaps that appear within @var{keymap} are not checked +recursively for keys bound to @var{olddef}; they are not changed at all. +Perhaps it would be better to check nested keymaps recursively. +@end ignore + +Here is an example showing a keymap before and after substitution: + +@smallexample +@group +(setq map '(keymap + (?1 . olddef-1) + (?2 . olddef-2) + (?3 . olddef-1))) +@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1)) +@end group + +@group +(substitute-key-definition 'olddef-1 'newdef map) +@result{} nil +@end group +@group +map +@result{} (keymap (49 . newdef) (50 . olddef-2) (51 . newdef)) +@end group +@end smallexample +@end defun + +@defun suppress-keymap keymap &optional nodigits +@cindex @code{self-insert-command} override +This function changes the contents of the full keymap @var{keymap} by +making all the printing characters undefined. More precisely, it binds +them to the command @code{undefined}. This makes ordinary insertion of +text impossible. @code{suppress-keymap} returns @code{nil}. + +If @var{nodigits} is @code{nil}, then @code{suppress-keymap} defines +digits to run @code{digit-argument}, and @kbd{-} to run +@code{negative-argument}. Otherwise it makes them undefined like the +rest of the printing characters. + +@cindex yank suppression +@cindex @code{quoted-insert} suppression +The @code{suppress-keymap} function does not make it impossible to +modify a buffer, as it does not suppress commands such as @code{yank} +and @code{quoted-insert}. To prevent any modification of a buffer, make +it read-only (@pxref{Read Only Buffers}). + +Since this function modifies @var{keymap}, you would normally use it +on a newly created keymap. Operating on an existing keymap +that is used for some other purpose is likely to cause trouble; for +example, suppressing @code{global-map} would make it impossible to use +most of Emacs. + +Most often, @code{suppress-keymap} is used to initialize local +keymaps of modes such as Rmail and Dired where insertion of text is not +desirable and the buffer is read-only. Here is an example taken from +the file @file{emacs/lisp/dired.el}, showing how the local keymap for +Dired mode is set up: + +@smallexample +@group + @dots{} + (setq dired-mode-map (make-keymap)) + (suppress-keymap dired-mode-map) + (define-key dired-mode-map "r" 'dired-rename-file) + (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted) + (define-key dired-mode-map "d" 'dired-flag-file-deleted) + (define-key dired-mode-map "v" 'dired-view-file) + (define-key dired-mode-map "e" 'dired-find-file) + (define-key dired-mode-map "f" 'dired-find-file) + @dots{} +@end group +@end smallexample +@end defun + +@node Key Binding Commands +@section Commands for Binding Keys + + This section describes some convenient interactive interfaces for +changing key bindings. They work by calling @code{define-key}. + +@deffn Command global-set-key key definition + This function sets the binding of @var{key} in the current global map +to @var{definition}. + +@smallexample +@group +(global-set-key @var{key} @var{definition}) +@equiv{} +(define-key (current-global-map) @var{key} @var{definition}) +@end group +@end smallexample +@end deffn + +@deffn Command global-unset-key key +@cindex unbinding keys + This function removes the binding of @var{key} from the current +global map. + +One use of this function is in preparation for defining a longer key +which uses it implicitly as a prefix---which would not be allowed if +@var{key} has a non-prefix binding. For example: + +@smallexample +@group +(global-unset-key "\C-l") + @result{} nil +@end group +@group +(global-set-key "\C-l\C-l" 'redraw-display) + @result{} nil +@end group +@end smallexample + +This function is implemented simply using @code{define-key}: + +@smallexample +@group +(global-unset-key @var{key}) +@equiv{} +(define-key (current-global-map) @var{key} nil) +@end group +@end smallexample +@end deffn + +@deffn Command local-set-key key definition + This function sets the binding of @var{key} in the current local +keymap to @var{definition}. + +@smallexample +@group +(local-set-key @var{key} @var{definition}) +@equiv{} +(define-key (current-local-map) @var{key} @var{definition}) +@end group +@end smallexample +@end deffn + +@deffn Command local-unset-key key + This function removes the binding of @var{key} from the current +local map. + +@smallexample +@group +(local-unset-key @var{key}) +@equiv{} +(define-key (current-local-map) @var{key} nil) +@end group +@end smallexample +@end deffn + +@node Scanning Keymaps +@section Scanning Keymaps + + This section describes functions used to scan all the current keymaps +for the sake of printing help information. + +@defun accessible-keymaps keymap &optional prefix +This function returns a list of all the keymaps that can be accessed +(via prefix keys) from @var{keymap}. The value is an association list +with elements of the form @code{(@var{key} .@: @var{map})}, where +@var{key} is a prefix key whose definition in @var{keymap} is +@var{map}. + +The elements of the alist are ordered so that the @var{key} increases +in length. The first element is always @code{("" .@: @var{keymap})}, +because the specified keymap is accessible from itself with a prefix of +no events. + +If @var{prefix} is given, it should be a prefix key sequence; then +@code{accessible-keymaps} includes only the submaps whose prefixes start +with @var{prefix}. These elements look just as they do in the value of +@code{(accessible-keymaps)}; the only difference is that some elements +are omitted. + +In the example below, the returned alist indicates that the key +@key{ESC}, which is displayed as @samp{^[}, is a prefix key whose +definition is the sparse keymap @code{(keymap (83 .@: center-paragraph) +(115 .@: foo))}. + +@smallexample +@group +(accessible-keymaps (current-local-map)) +@result{}(("" keymap + (27 keymap ; @r{Note this keymap for @key{ESC} is repeated below.} + (83 . center-paragraph) + (115 . center-line)) + (9 . tab-to-tab-stop)) +@end group + +@group + ("^[" keymap + (83 . center-paragraph) + (115 . foo))) +@end group +@end smallexample + +In the following example, @kbd{C-h} is a prefix key that uses a sparse +keymap starting with @code{(keymap (118 . describe-variable)@dots{})}. +Another prefix, @kbd{C-x 4}, uses a keymap which happens to be +@code{ctl-x-4-map}. The event @code{mode-line} is one of several dummy +events used as prefixes for mouse actions in special parts of a window. + +@smallexample +@group +(accessible-keymaps (current-global-map)) +@result{} (("" keymap [set-mark-command beginning-of-line @dots{} + delete-backward-char]) +@end group +@group + ("^H" keymap (118 . describe-variable) @dots{} + (8 . help-for-help)) +@end group +@group + ("^X" keymap [x-flush-mouse-queue @dots{} + backward-kill-sentence]) +@end group +@group + ("^[" keymap [mark-sexp backward-sexp @dots{} + backward-kill-word]) +@end group + ("^X4" keymap (15 . display-buffer) @dots{}) +@group + ([mode-line] keymap + (S-mouse-2 . mouse-split-window-horizontally) @dots{})) +@end group +@end smallexample + +@noindent +These are not all the keymaps you would see in an actual case. +@end defun + +@defun where-is-internal command &optional keymap firstonly noindirect +This function returns a list of key sequences (of any length) that are +bound to @var{command} in a set of keymaps. + +The argument @var{command} can be any object; it is compared with all +keymap entries using @code{eq}. + +If @var{keymap} is @code{nil}, then the maps used are the current active +keymaps, disregarding @code{overriding-local-map} (that is, pretending +its value is @code{nil}). If @var{keymap} is non-@code{nil}, then the +maps searched are @var{keymap} and the global keymap. + +Usually it's best to use @code{overriding-local-map} as the expression +for @var{keymap}. Then @code{where-is-internal} searches precisely the +keymaps that are active. To search only the global map, pass +@code{(keymap)} (an empty keymap) as @var{keymap}. + +If @var{firstonly} is @code{non-ascii}, then the value is a single +string representing the first key sequence found, rather than a list of +all possible key sequences. If @var{firstonly} is @code{t}, then the +value is the first key sequence, except that key sequences consisting +entirely of @sc{ASCII} characters (or meta variants of @sc{ASCII} +characters) are preferred to all other key sequences. + +If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't +follow indirections to other keymaps or slots. This makes it possible +to search for an indirect definition itself. + +This function is used by @code{where-is} (@pxref{Help, , Help, emacs, +The GNU Emacs Manual}). + +@smallexample +@group +(where-is-internal 'describe-function) + @result{} ("\^hf" "\^hd") +@end group +@end smallexample +@end defun + +@deffn Command describe-bindings prefix +This function creates a listing of all defined keys, and their +definitions. It writes the listing in a buffer named @samp{*Help*} and +displays it in a window. + +The listing describes meta characters as @key{ESC} followed by the +corresponding non-meta character. + +When several characters with consecutive @sc{ASCII} codes have the +same definition, they are shown together, as +@samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to +know the @sc{ASCII} codes to understand which characters this means. +For example, in the default global map, the characters @samp{@key{SPC} +..@: ~} are described by a single line. @key{SPC} is @sc{ASCII} 32, +@kbd{~} is @sc{ASCII} 126, and the characters between them include all +the normal printing characters, (e.g., letters, digits, punctuation, +etc.@:); all these characters are bound to @code{self-insert-command}. + +If @var{prefix} is non-@code{nil}, it should be a prefix key; then the +listing includes only keys that start with @var{prefix}. +@end deffn
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/lists.texi Mon Mar 28 20:21:44 1994 +0000 @@ -0,0 +1,1384 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/lists +@node Lists, Sequences Arrays Vectors, Strings and Characters, Top +@chapter Lists +@cindex list +@cindex element (of list) + + A @dfn{list} represents a sequence of zero or more elements (which may +be any Lisp objects). The important difference between lists and +vectors is that two or more lists can share part of their structure; in +addition, you can insert or delete elements in a list without copying +the whole list. + +@menu +* Cons Cells:: How lists are made out of cons cells. +* Lists as Boxes:: Graphical notation to explain lists. +* List-related Predicates:: Is this object a list? Comparing two lists. +* List Elements:: Extracting the pieces of a list. +* Building Lists:: Creating list structure. +* Modifying Lists:: Storing new pieces into an existing list. +* Sets And Lists:: A list can represent a finite mathematical set. +* Association Lists:: A list can represent a finite relation or mapping. +@end menu + +@node Cons Cells +@section Lists and Cons Cells +@cindex lists and cons cells +@cindex @code{nil} and lists + + Lists in Lisp are not a primitive data type; they are built up from +@dfn{cons cells}. A cons cell is a data object which represents an ordered +pair. It records two Lisp objects, one labeled as the @sc{car}, and the +other labeled as the @sc{cdr}. These names are traditional; @sc{cdr} is +pronounced ``could-er.'' + + A list is a series of cons cells chained together, one cons cell per +element of the list. By convention, the @sc{car}s of the cons cells are +the elements of the list, and the @sc{cdr}s are used to chain the list: +the @sc{cdr} of each cons cell is the following cons cell. The @sc{cdr} +of the last cons cell is @code{nil}. This asymmetry between the +@sc{car} and the @sc{cdr} is entirely a matter of convention; at the +level of cons cells, the @sc{car} and @sc{cdr} slots have the same +characteristics. + + The symbol @code{nil} is considered a list as well as a symbol; it is +the list with no elements. For convenience, the symbol @code{nil} is +considered to have @code{nil} as its @sc{cdr} (and also as its +@sc{car}). + + The @sc{cdr} of any nonempty list @var{l} is a list containing all the +elements of @var{l} except the first. + +@node Lists as Boxes +@comment node-name, next, previous, up +@section Lists as Linked Pairs of Boxes +@cindex box representation for lists +@cindex lists represented as boxes +@cindex cons cell as box + + A cons cell can be illustrated as a pair of boxes. The first box +represents the @sc{car} and the second box represents the @sc{cdr}. +Here is an illustration of the two-element list, @code{(tulip lily)}, +made from two cons cells: + +@example +@group + --------------- --------------- +| car | cdr | | car | cdr | +| tulip | o---------->| lily | nil | +| | | | | | + --------------- --------------- +@end group +@end example + + Each pair of boxes represents a cons cell. Each box ``refers to'', +``points to'' or ``contains'' a Lisp object. (These terms are +synonymous.) The first box, which is the @sc{car} of the first cons +cell, contains the symbol @code{tulip}. The arrow from the @sc{cdr} of +the first cons cell to the second cons cell indicates that the @sc{cdr} +of the first cons cell points to the second cons cell. + + The same list can be illustrated in a different sort of box notation +like this: + +@example +@group + ___ ___ ___ ___ + |___|___|--> |___|___|--> nil + | | + | | + --> tulip --> lily +@end group +@end example + + Here is a more complex illustration, showing the three-element list, +@code{((pine needles) oak maple)}, the first element of which is a +two-element list: + +@example +@group + ___ ___ ___ ___ ___ ___ + |___|___|--> |___|___|--> |___|___|--> nil + | | | + | | | + | --> oak --> maple + | + | ___ ___ ___ ___ + --> |___|___|--> |___|___|--> nil + | | + | | + --> pine --> needles +@end group +@end example + + The same list represented in the first box notation looks like this: + +@example +@group + -------------- -------------- -------------- +| car | cdr | | car | cdr | | car | cdr | +| o | o------->| oak | o------->| maple | nil | +| | | | | | | | | | + -- | --------- -------------- -------------- + | + | + | -------------- ---------------- + | | car | cdr | | car | cdr | + ------>| pine | o------->| needles | nil | + | | | | | | + -------------- ---------------- +@end group +@end example + + @xref{List Type}, for the read and print syntax of lists, and for more +``box and arrow'' illustrations of lists. + +@node List-related Predicates +@section Predicates on Lists + + The following predicates test whether a Lisp object is an atom, is a +cons cell or is a list, or whether it is the distinguished object +@code{nil}. (Many of these predicates can be defined in terms of the +others, but they are used so often that it is worth having all of them.) + +@defun consp object +This function returns @code{t} if @var{object} is a cons cell, @code{nil} +otherwise. @code{nil} is not a cons cell, although it @emph{is} a list. +@end defun + +@defun atom object +@cindex atoms +This function returns @code{t} if @var{object} is an atom, @code{nil} +otherwise. All objects except cons cells are atoms. The symbol +@code{nil} is an atom and is also a list; it is the only Lisp object +which is both. + +@example +(atom @var{object}) @equiv{} (not (consp @var{object})) +@end example +@end defun + +@defun listp object +This function returns @code{t} if @var{object} is a cons cell or +@code{nil}. Otherwise, it returns @code{nil}. + +@example +@group +(listp '(1)) + @result{} t +@end group +@group +(listp '()) + @result{} t +@end group +@end example +@end defun + +@defun nlistp object +This function is the opposite of @code{listp}: it returns @code{t} if +@var{object} is not a list. Otherwise, it returns @code{nil}. + +@example +(listp @var{object}) @equiv{} (not (nlistp @var{object})) +@end example +@end defun + +@defun null object +This function returns @code{t} if @var{object} is @code{nil}, and +returns @code{nil} otherwise. This function is identical to @code{not}, +but as a matter of clarity we use @code{null} when @var{object} is +considered a list and @code{not} when it is considered a truth value +(see @code{not} in @ref{Combining Conditions}). + +@example +@group +(null '(1)) + @result{} nil +@end group +@group +(null '()) + @result{} t +@end group +@end example +@end defun + +@need 1000 + +@node List Elements +@section Accessing Elements of Lists +@cindex list elements + +@defun car cons-cell +This function returns the value pointed to by the first pointer of the +cons cell @var{cons-cell}. Expressed another way, this function +returns the @sc{car} of @var{cons-cell}. + +As a special case, if @var{cons-cell} is @code{nil}, then @code{car} +is defined to return @code{nil}; therefore, any list is a valid argument +for @code{car}. An error is signaled if the argument is not a cons cell +or @code{nil}. + +@example +@group +(car '(a b c)) + @result{} a +@end group +@group +(car '()) + @result{} nil +@end group +@end example +@end defun + +@defun cdr cons-cell +This function returns the value pointed to by the second pointer of +the cons cell @var{cons-cell}. Expressed another way, this function +returns the @sc{cdr} of @var{cons-cell}. + +As a special case, if @var{cons-cell} is @code{nil}, then @code{cdr} +is defined to return @code{nil}; therefore, any list is a valid argument +for @code{cdr}. An error is signaled if the argument is not a cons cell +or @code{nil}. + +@example +@group +(cdr '(a b c)) + @result{} (b c) +@end group +@group +(cdr '()) + @result{} nil +@end group +@end example +@end defun + +@defun car-safe object +This function lets you take the @sc{car} of a cons cell while avoiding +errors for other data types. It returns the @sc{car} of @var{object} if +@var{object} is a cons cell, @code{nil} otherwise. This is in contrast +to @code{car}, which signals an error if @var{object} is not a list. + +@example +@group +(car-safe @var{object}) +@equiv{} +(let ((x @var{object})) + (if (consp x) + (car x) + nil)) +@end group +@end example +@end defun + +@defun cdr-safe object +This function lets you take the @sc{cdr} of a cons cell while +avoiding errors for other data types. It returns the @sc{cdr} of +@var{object} if @var{object} is a cons cell, @code{nil} otherwise. +This is in contrast to @code{cdr}, which signals an error if +@var{object} is not a list. + +@example +@group +(cdr-safe @var{object}) +@equiv{} +(let ((x @var{object})) + (if (consp x) + (cdr x) + nil)) +@end group +@end example +@end defun + +@defun nth n list +This function returns the @var{n}th element of @var{list}. Elements +are numbered starting with zero, so the @sc{car} of @var{list} is +element number zero. If the length of @var{list} is @var{n} or less, +the value is @code{nil}. + +If @var{n} is negative, @code{nth} returns the first element of +@var{list}. + +@example +@group +(nth 2 '(1 2 3 4)) + @result{} 3 +@end group +@group +(nth 10 '(1 2 3 4)) + @result{} nil +@end group +@group +(nth -3 '(1 2 3 4)) + @result{} 1 + +(nth n x) @equiv{} (car (nthcdr n x)) +@end group +@end example +@end defun + +@defun nthcdr n list +This function returns the @var{n}th @sc{cdr} of @var{list}. In other +words, it removes the first @var{n} links of @var{list} and returns +what follows. + +If @var{n} is zero or negative, @code{nthcdr} returns all of +@var{list}. If the length of @var{list} is @var{n} or less, +@code{nthcdr} returns @code{nil}. + +@example +@group +(nthcdr 1 '(1 2 3 4)) + @result{} (2 3 4) +@end group +@group +(nthcdr 10 '(1 2 3 4)) + @result{} nil +@end group +@group +(nthcdr -3 '(1 2 3 4)) + @result{} (1 2 3 4) +@end group +@end example +@end defun + +@node Building Lists +@comment node-name, next, previous, up +@section Building Cons Cells and Lists +@cindex cons cells +@cindex building lists + + Many functions build lists, as lists reside at the very heart of Lisp. +@code{cons} is the fundamental list-building function; however, it is +interesting to note that @code{list} is used more times in the source +code for Emacs than @code{cons}. + +@defun cons object1 object2 +This function is the fundamental function used to build new list +structure. It creates a new cons cell, making @var{object1} the +@sc{car}, and @var{object2} the @sc{cdr}. It then returns the new cons +cell. The arguments @var{object1} and @var{object2} may be any Lisp +objects, but most often @var{object2} is a list. + +@example +@group +(cons 1 '(2)) + @result{} (1 2) +@end group +@group +(cons 1 '()) + @result{} (1) +@end group +@group +(cons 1 2) + @result{} (1 . 2) +@end group +@end example + +@cindex consing +@code{cons} is often used to add a single element to the front of a +list. This is called @dfn{consing the element onto the list}. For +example: + +@example +(setq list (cons newelt list)) +@end example + +Note that there is no conflict between the variable named @code{list} +used in this example and the function named @code{list} described below; +any symbol can serve both purposes. +@end defun + +@defun list &rest objects +This function creates a list with @var{objects} as its elements. The +resulting list is always @code{nil}-terminated. If no @var{objects} +are given, the empty list is returned. + +@example +@group +(list 1 2 3 4 5) + @result{} (1 2 3 4 5) +@end group +@group +(list 1 2 '(3 4 5) 'foo) + @result{} (1 2 (3 4 5) foo) +@end group +@group +(list) + @result{} nil +@end group +@end example +@end defun + +@defun make-list length object +This function creates a list of length @var{length}, in which all the +elements have the identical value @var{object}. Compare +@code{make-list} with @code{make-string} (@pxref{Creating Strings}). + +@example +@group +(make-list 3 'pigs) + @result{} (pigs pigs pigs) +@end group +@group +(make-list 0 'pigs) + @result{} nil +@end group +@end example +@end defun + +@defun append &rest sequences +@cindex copying lists +This function returns a list containing all the elements of +@var{sequences}. The @var{sequences} may be lists, vectors, or strings. +All arguments except the last one are copied, so none of them are +altered. + + The final argument to @code{append} may be any object but it is +typically a list. The final argument is not copied or converted; it +becomes part of the structure of the new list. + + Here is an example: + +@example +@group +(setq trees '(pine oak)) + @result{} (pine oak) +(setq more-trees (append '(maple birch) trees)) + @result{} (maple birch pine oak) +@end group + +@group +trees + @result{} (pine oak) +more-trees + @result{} (maple birch pine oak) +@end group +@group +(eq trees (cdr (cdr more-trees))) + @result{} t +@end group +@end example + +You can see what happens by looking at a box diagram. The variable +@code{trees} is set to the list @code{(pine oak)} and then the variable +@code{more-trees} is set to the list @code{(maple birch pine oak)}. +However, the variable @code{trees} continues to refer to the original +list: + +@smallexample +@group +more-trees trees +| | +| ___ ___ ___ ___ -> ___ ___ ___ ___ + --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil + | | | | + | | | | + --> maple -->birch --> pine --> oak +@end group +@end smallexample + +An empty sequence contributes nothing to the value returned by +@code{append}. As a consequence of this, a final @code{nil} argument +forces a copy of the previous argument. + +@example +@group +trees + @result{} (pine oak) +@end group +@group +(setq wood (append trees ())) + @result{} (pine oak) +@end group +@group +wood + @result{} (pine oak) +@end group +@group +(eq wood trees) + @result{} nil +@end group +@end example + +@noindent +This once was the usual way to copy a list, before the function +@code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}. + +With the help of @code{apply}, we can append all the lists in a list of +lists: + +@example +@group +(apply 'append '((a b c) nil (x y z) nil)) + @result{} (a b c x y z) +@end group +@end example + +If no @var{sequences} are given, @code{nil} is returned: + +@example +@group +(append) + @result{} nil +@end group +@end example + +See @code{nconc} in @ref{Rearrangement}, for a way to join lists with no +copying. + +Integers are also allowed as arguments to @code{append}. They are +converted to strings of digits making up the decimal print +representation of the integer, and these strings are then appended. +Here's what happens: + +@example +@group +(setq trees '(pine oak)) + @result{} (pine oak) +@end group +@group +(char-to-string 54) + @result{} "6" +@end group +@group +(setq longer-list (append trees 6 '(spruce))) + @result{} (pine oak 54 spruce) +@end group +@group +(setq x-list (append trees 6 6)) + @result{} (pine oak 54 . 6) +@end group +@end example + +This special case exists for compatibility with Mocklisp, and we don't +recommend you take advantage of it. If you want to convert an integer +in this way, use @code{format} (@pxref{Formatting Strings}) or +@code{number-to-string} (@pxref{String Conversion}). +@end defun + +@defun reverse list +This function creates a new list whose elements are the elements of +@var{list}, but in reverse order. The original argument @var{list} is +@emph{not} altered. + +@example +@group +(setq x '(1 2 3 4)) + @result{} (1 2 3 4) +@end group +@group +(reverse x) + @result{} (4 3 2 1) +x + @result{} (1 2 3 4) +@end group +@end example +@end defun + +@node Modifying Lists +@section Modifying Existing List Structure + + You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the +primitives @code{setcar} and @code{setcdr}. + +@cindex CL note---@code{rplaca} vrs @code{setcar} +@quotation +@findex rplaca +@findex rplacd +@b{Common Lisp note:} Common Lisp uses functions @code{rplaca} and +@code{rplacd} to alter list structure; they change structure the same +way as @code{setcar} and @code{setcdr}, but the Common Lisp functions +return the cons cell while @code{setcar} and @code{setcdr} return the +new @sc{car} or @sc{cdr}. +@end quotation + +@menu +* Setcar:: Replacing an element in a list. +* Setcdr:: Replacing part of the list backbone. + This can be used to remove or add elements. +* Rearrangement:: Reordering the elements in a list; combining lists. +@end menu + +@node Setcar +@subsection Altering List Elements with @code{setcar} + + Changing the @sc{car} of a cons cell is done with @code{setcar}, which +replaces one element of a list with a different element. + +@defun setcar cons object +This function stores @var{object} as the new @sc{car} of @var{cons}, +replacing its previous @sc{car}. It returns the value @var{object}. +For example: + +@example +@group +(setq x '(1 2)) + @result{} (1 2) +@end group +@group +(setcar x 4) + @result{} 4 +@end group +@group +x + @result{} (4 2) +@end group +@end example +@end defun + + When a cons cell is part of the shared structure of several lists, +storing a new @sc{car} into the cons changes one element of each of +these lists. Here is an example: + +@example +@group +;; @r{Create two lists that are partly shared.} +(setq x1 '(a b c)) + @result{} (a b c) +(setq x2 (cons 'z (cdr x1))) + @result{} (z b c) +@end group + +@group +;; @r{Replace the @sc{car} of a shared link.} +(setcar (cdr x1) 'foo) + @result{} foo +x1 ; @r{Both lists are changed.} + @result{} (a foo c) +x2 + @result{} (z foo c) +@end group + +@group +;; @r{Replace the @sc{car} of a link that is not shared.} +(setcar x1 'baz) + @result{} baz +x1 ; @r{Only one list is changed.} + @result{} (baz foo c) +x2 + @result{} (z foo c) +@end group +@end example + + Here is a graphical depiction of the shared structure of the two lists +in the variables @code{x1} and @code{x2}, showing why replacing @code{b} +changes them both: + +@example +@group + ___ ___ ___ ___ ___ ___ +x1---> |___|___|----> |___|___|--> |___|___|--> nil + | --> | | + | | | | + --> a | --> b --> c + | + ___ ___ | +x2--> |___|___|-- + | + | + --> z +@end group +@end example + + Here is an alternative form of box diagram, showing the same relationship: + +@example +@group +x1: + -------------- -------------- -------------- +| car | cdr | | car | cdr | | car | cdr | +| a | o------->| b | o------->| c | nil | +| | | -->| | | | | | + -------------- | -------------- -------------- + | +x2: | + -------------- | +| car | cdr | | +| z | o---- +| | | + -------------- +@end group +@end example + +@node Setcdr +@subsection Altering the CDR of a List + + The lowest-level primitive for modifying a @sc{cdr} is @code{setcdr}: + +@defun setcdr cons object +This function stores @var{object} into the @sc{cdr} of @var{cons}. The +value returned is @var{object}, not @var{cons}. +@end defun + + Here is an example of replacing the @sc{cdr} of a list with a +different list. All but the first element of the list are removed in +favor of a different sequence of elements. The first element is +unchanged, because it resides in the @sc{car} of the list, and is not +reached via the @sc{cdr}. + +@example +@group +(setq x '(1 2 3)) + @result{} (1 2 3) +@end group +@group +(setcdr x '(4)) + @result{} (4) +@end group +@group +x + @result{} (1 4) +@end group +@end example + + You can delete elements from the middle of a list by altering the +@sc{cdr}s of the cons cells in the list. For example, here we delete +the second element, @code{b}, from the list @code{(a b c)}, by changing +the @sc{cdr} of the first cell: + +@example +@group +(setq x1 '(a b c)) + @result{} (a b c) +(setcdr x1 (cdr (cdr x1))) + @result{} (c) +x1 + @result{} (a c) +@end group +@end example + + Here is the result in box notation: + +@example +@group + -------------------- + | | + -------------- | -------------- | -------------- +| car | cdr | | | car | cdr | -->| car | cdr | +| a | o----- | b | o-------->| c | nil | +| | | | | | | | | + -------------- -------------- -------------- +@end group +@end example + +@noindent +The second cons cell, which previously held the element @code{b}, still +exists and its @sc{car} is still @code{b}, but it no longer forms part +of this list. + + It is equally easy to insert a new element by changing @sc{cdr}s: + +@example +@group +(setq x1 '(a b c)) + @result{} (a b c) +(setcdr x1 (cons 'd (cdr x1))) + @result{} (d b c) +x1 + @result{} (a d b c) +@end group +@end example + + Here is this result in box notation: + +@smallexample +@group + -------------- ------------- ------------- +| car | cdr | | car | cdr | | car | cdr | +| a | o | -->| b | o------->| c | nil | +| | | | | | | | | | | + --------- | -- | ------------- ------------- + | | + ----- -------- + | | + | --------------- | + | | car | cdr | | + -->| d | o------ + | | | + --------------- +@end group +@end smallexample + +@node Rearrangement +@subsection Functions that Rearrange Lists +@cindex rearrangement of lists +@cindex modification of lists + + Here are some functions that rearrange lists ``destructively'' by +modifying the @sc{cdr}s of their component cons cells. We call these +functions ``destructive'' because they chew up the original lists passed +to them as arguments, to produce a new list that is the returned value. + +@defun nconc &rest lists +@cindex concatenating lists +@cindex joining lists +This function returns a list containing all the elements of @var{lists}. +Unlike @code{append} (@pxref{Building Lists}), the @var{lists} are +@emph{not} copied. Instead, the last @sc{cdr} of each of the +@var{lists} is changed to refer to the following list. The last of the +@var{lists} is not altered. For example: + +@example +@group +(setq x '(1 2 3)) + @result{} (1 2 3) +@end group +@group +(nconc x '(4 5)) + @result{} (1 2 3 4 5) +@end group +@group +x + @result{} (1 2 3 4 5) +@end group +@end example + + Since the last argument of @code{nconc} is not itself modified, it is +reasonable to use a constant list, such as @code{'(4 5)}, as in the +above example. For the same reason, the last argument need not be a +list: + +@example +@group +(setq x '(1 2 3)) + @result{} (1 2 3) +@end group +@group +(nconc x 'z) + @result{} (1 2 3 . z) +@end group +@group +x + @result{} (1 2 3 . z) +@end group +@end example + +A common pitfall is to use a quoted constant list as a non-last +argument to @code{nconc}. If you do this, your program will change +each time you run it! Here is what happens: + +@smallexample +@group +(defun add-foo (x) ; @r{We want this function to add} + (nconc '(foo) x)) ; @r{@code{foo} to the front of its arg.} +@end group + +@group +(symbol-function 'add-foo) + @result{} (lambda (x) (nconc (quote (foo)) x)) +@end group + +@group +(setq xx (add-foo '(1 2))) ; @r{It seems to work.} + @result{} (foo 1 2) +@end group +@group +(setq xy (add-foo '(3 4))) ; @r{What happened?} + @result{} (foo 1 2 3 4) +@end group +@group +(eq xx xy) + @result{} t +@end group + +@group +(symbol-function 'add-foo) + @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x))) +@end group +@end smallexample +@end defun + +@defun nreverse list +@cindex reversing a list + This function reverses the order of the elements of @var{list}. +Unlike @code{reverse}, @code{nreverse} alters its argument destructively +by reversing the @sc{cdr}s in the cons cells forming the list. The cons +cell which used to be the last one in @var{list} becomes the first cell +of the value. + + For example: + +@example +@group +(setq x '(1 2 3 4)) + @result{} (1 2 3 4) +@end group +@group +x + @result{} (1 2 3 4) +(nreverse x) + @result{} (4 3 2 1) +@end group +@group +;; @r{The cell that was first is now last.} +x + @result{} (1) +@end group +@end example + + To avoid confusion, we usually store the result of @code{nreverse} +back in the same variable which held the original list: + +@example +(setq x (nreverse x)) +@end example + + Here is the @code{nreverse} of our favorite example, @code{(a b c)}, +presented graphically: + +@smallexample +@group +@r{Original list head:} @r{Reversed list:} + ------------- ------------- ------------ +| car | cdr | | car | cdr | | car | cdr | +| a | nil |<-- | b | o |<-- | c | o | +| | | | | | | | | | | | | + ------------- | --------- | - | -------- | - + | | | | + ------------- ------------ +@end group +@end smallexample +@end defun + +@defun sort list predicate +@cindex stable sort +@cindex sorting lists +This function sorts @var{list} stably, though destructively, and +returns the sorted list. It compares elements using @var{predicate}. A +stable sort is one in which elements with equal sort keys maintain their +relative order before and after the sort. Stability is important when +successive sorts are used to order elements according to different +criteria. + +The argument @var{predicate} must be a function that accepts two +arguments. It is called with two elements of @var{list}. To get an +increasing order sort, the @var{predicate} should return @code{t} if the +first element is ``less than'' the second, or @code{nil} if not. + +The destructive aspect of @code{sort} is that it rearranges the cons +cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort +function would create new cons cells to store the elements in their +sorted order. If you wish to make a sorted copy without destroying the +original, copy it first with @code{copy-sequence} and then sort. + +Sorting does not change the @sc{car}s of the cons cells in @var{list}; +the cons cell that originally contained the element @code{a} in +@var{list} still has @code{a} in its @sc{car} after sorting, but it now +appears in a different position in the list due to the change of +@sc{cdr}s. For example: + +@example +@group +(setq nums '(1 3 2 6 5 4 0)) + @result{} (1 3 2 6 5 4 0) +@end group +@group +(sort nums '<) + @result{} (0 1 2 3 4 5 6) +@end group +@group +nums + @result{} (1 2 3 4 5 6) +@end group +@end example + +@noindent +Note that the list in @code{nums} no longer contains 0; this is the same +cons cell that it was before, but it is no longer the first one in the +list. Don't assume a variable that formerly held the argument now holds +the entire sorted list! Instead, save the result of @code{sort} and use +that. Most often we store the result back into the variable that held +the original list: + +@example +(setq nums (sort nums '<)) +@end example + +@xref{Sorting}, for more functions that perform sorting. +See @code{documentation} in @ref{Accessing Documentation}, for a +useful example of @code{sort}. +@end defun + +@ifinfo + See @code{delq}, in @ref{Sets And Lists}, for another function +that modifies cons cells. +@end ifinfo +@iftex + The function @code{delq} in the following section is another example +of destructive list manipulation. +@end iftex + +@node Sets And Lists +@section Using Lists as Sets +@cindex lists as sets +@cindex sets + + A list can represent an unordered mathematical set---simply consider a +value an element of a set if it appears in the list, and ignore the +order of the list. To form the union of two sets, use @code{append} (as +long as you don't mind having duplicate elements). Other useful +functions for sets include @code{memq} and @code{delq}, and their +@code{equal} versions, @code{member} and @code{delete}. + +@cindex CL note---lack @code{union}, @code{set} +@quotation +@b{Common Lisp note:} Common Lisp has functions @code{union} (which +avoids duplicate elements) and @code{intersection} for set operations, +but GNU Emacs Lisp does not have them. You can write them in Lisp if +you wish. +@end quotation + +@defun memq object list +@cindex membership in a list +This function tests to see whether @var{object} is a member of +@var{list}. If it is, @code{memq} returns a list starting with the +first occurrence of @var{object}. Otherwise, it returns @code{nil}. +The letter @samp{q} in @code{memq} says that it uses @code{eq} to +compare @var{object} against the elements of the list. For example: + +@example +@group +(memq 2 '(1 2 3 2 1)) + @result{} (2 3 2 1) +@end group +@group +(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} + @result{} nil +@end group +@end example +@end defun + +@defun delq object list +@cindex deletion of elements +This function destructively removes all elements @code{eq} to +@var{object} from @var{list}. The letter @samp{q} in @code{delq} says +that it uses @code{eq} to compare @var{object} against the elements of +the list, like @code{memq}. +@end defun + +When @code{delq} deletes elements from the front of the list, it does so +simply by advancing down the list and returning a sublist that starts +after those elements: + +@example +@group +(delq 'a '(a b c)) @equiv{} (cdr '(a b c)) +@end group +@end example + +When an element to be deleted appears in the middle of the list, +removing it involves changing the @sc{cdr}s (@pxref{Setcdr}). + +@example +@group +(setq sample-list '(1 2 3 (4))) + @result{} (1 2 3 (4)) +@end group +@group +(delq 1 sample-list) + @result{} (2 3 (4)) +@end group +@group +sample-list + @result{} (1 2 3 (4)) +@end group +@group +(delq 2 sample-list) + @result{} (1 3 (4)) +@end group +@group +sample-list + @result{} (1 3 (4)) +@end group +@end example + +Note that @code{(delq 2 sample-list)} modifies @code{sample-list} to +splice out the second element, but @code{(delq 1 sample-list)} does not +splice anything---it just returns a shorter list. Don't assume that a +variable which formerly held the argument @var{list} now has fewer +elements, or that it still holds the original list! Instead, save the +result of @code{delq} and use that. Most often we store the result back +into the variable that held the original list: + +@example +(setq flowers (delq 'rose flowers)) +@end example + +In the following example, the @code{(4)} that @code{delq} attempts to match +and the @code{(4)} in the @code{sample-list} are not @code{eq}: + +@example +@group +(delq '(4) sample-list) + @result{} (1 3 (4)) +@end group +@end example + +The following two functions are like @code{memq} and @code{delq} but use +@code{equal} rather than @code{eq} to compare elements. They are new in +Emacs 19. + +@defun member object list +The function @code{member} tests to see whether @var{object} is a member +of @var{list}, comparing members with @var{object} using @code{equal}. +If @var{object} is a member, @code{member} returns a list starting with +its first occurrence in @var{list}. Otherwise, it returns @code{nil}. + +Compare this with @code{memq}: + +@example +@group +(member '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are @code{equal}.} + @result{} ((2)) +@end group +@group +(memq '(2) '((1) (2))) ; @r{@code{(2)} and @code{(2)} are not @code{eq}.} + @result{} nil +@end group +@group +;; @r{Two strings with the same contents are @code{equal}.} +(member "foo" '("foo" "bar")) + @result{} ("foo" "bar") +@end group +@end example +@end defun + +@defun delete object list +This function destructively removes all elements @code{equal} to +@var{object} from @var{list}. It is to @code{delq} as @code{member} is +to @code{memq}: it uses @code{equal} to compare elements with +@var{object}, like @code{member}; when it finds an element that matches, +it removes the element just as @code{delq} would. For example: + +@example +@group +(delete '(2) '((2) (1) (2))) + @result{} '((1)) +@end group +@end example +@end defun + +@quotation +@b{Common Lisp note:} The functions @code{member} and @code{delete} in +GNU Emacs Lisp are derived from Maclisp, not Common Lisp. The Common +Lisp versions do not use @code{equal} to compare elements. +@end quotation + +@node Association Lists +@section Association Lists +@cindex association list +@cindex alist + + An @dfn{association list}, or @dfn{alist} for short, records a mapping +from keys to values. It is a list of cons cells called +@dfn{associations}: the @sc{car} of each cell is the @dfn{key}, and the +@sc{cdr} is the @dfn{associated value}.@footnote{This usage of ``key'' +is not related to the term ``key sequence''; it means a value used to +look up an item in a table. In this case, the table is the alist, and +the alist associations are the items.} + + Here is an example of an alist. The key @code{pine} is associated with +the value @code{cones}; the key @code{oak} is associated with +@code{acorns}; and the key @code{maple} is associated with @code{seeds}. + +@example +@group +'((pine . cones) + (oak . acorns) + (maple . seeds)) +@end group +@end example + + The associated values in an alist may be any Lisp objects; so may the +keys. For example, in the following alist, the symbol @code{a} is +associated with the number @code{1}, and the string @code{"b"} is +associated with the @emph{list} @code{(2 3)}, which is the @sc{cdr} of +the alist element: + +@example +((a . 1) ("b" 2 3)) +@end example + + Sometimes it is better to design an alist to store the associated +value in the @sc{car} of the @sc{cdr} of the element. Here is an +example: + +@example +'((rose red) (lily white) (buttercup yellow)) +@end example + +@noindent +Here we regard @code{red} as the value associated with @code{rose}. One +advantage of this method is that you can store other related +information---even a list of other items---in the @sc{cdr} of the +@sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see +below) to find the element containing a given value. When neither of +these considerations is important, the choice is a matter of taste, as +long as you are consistent about it for any given alist. + + Note that the same alist shown above could be regarded as having the +associated value in the @sc{cdr} of the element; the value associated +with @code{rose} would be the list @code{(red)}. + + Association lists are often used to record information that you might +otherwise keep on a stack, since new associations may be added easily to +the front of the list. When searching an association list for an +association with a given key, the first one found is returned, if there +is more than one. + + In Emacs Lisp, it is @emph{not} an error if an element of an +association list is not a cons cell. The alist search functions simply +ignore such elements. Many other versions of Lisp signal errors in such +cases. + + Note that property lists are similar to association lists in several +respects. A property list behaves like an association list in which +each key can occur only once. @xref{Property Lists}, for a comparison +of property lists and association lists. + +@defun assoc key alist +This function returns the first association for @var{key} in +@var{alist}. It compares @var{key} against the alist elements using +@code{equal} (@pxref{Equality Predicates}). It returns @code{nil} if no +association in @var{alist} has a @sc{car} @code{equal} to @var{key}. +For example: + +@smallexample +(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) + @result{} ((pine . cones) (oak . acorns) (maple . seeds)) +(assoc 'oak trees) + @result{} (oak . acorns) +(cdr (assoc 'oak trees)) + @result{} acorns +(assoc 'birch trees) + @result{} nil +@end smallexample + +Here is another example in which the keys and values are not symbols: + +@smallexample +(setq needles-per-cluster + '((2 "Austrian Pine" "Red Pine") + (3 "Pitch Pine") + (5 "White Pine"))) + +(cdr (assoc 3 needles-per-cluster)) + @result{} ("Pitch Pine") +(cdr (assoc 2 needles-per-cluster)) + @result{} ("Austrian Pine" "Red Pine") +@end smallexample +@end defun + +@defun assq key alist +This function is like @code{assoc} in that it returns the first +association for @var{key} in @var{alist}, but it makes the comparison +using @code{eq} instead of @code{equal}. @code{assq} returns @code{nil} +if no association in @var{alist} has a @sc{car} @code{eq} to @var{key}. +This function is used more often than @code{assoc}, since @code{eq} is +faster than @code{equal} and most alists use symbols as keys. +@xref{Equality Predicates}. + +@smallexample +(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) + @result{} ((pine . cones) (oak . acorns) (maple . seeds)) +(assq 'pine trees) + @result{} (pine . cones) +@end smallexample + +On the other hand, @code{assq} is not usually useful in alists where the +keys may not be symbols: + +@smallexample +(setq leaves + '(("simple leaves" . oak) + ("compound leaves" . horsechestnut))) + +(assq "simple leaves" leaves) + @result{} nil +(assoc "simple leaves" leaves) + @result{} ("simple leaves" . oak) +@end smallexample +@end defun + +@defun rassq value alist +This function returns the first association with value @var{value} in +@var{alist}. It returns @code{nil} if no association in @var{alist} has +a @sc{cdr} @code{eq} to @var{value}. + +@code{rassq} is like @code{assq} except that it compares the @sc{cdr} of +each @var{alist} association instead of the @sc{car}. You can think of +this as ``reverse @code{assq}'', finding the key for a given value. + +For example: + +@smallexample +(setq trees '((pine . cones) (oak . acorns) (maple . seeds))) + +(rassq 'acorns trees) + @result{} (oak . acorns) +(rassq 'spores trees) + @result{} nil +@end smallexample + +Note that @code{rassq} cannot search for a value stored in the @sc{car} +of the @sc{cdr} of an element: + +@smallexample +(setq colors '((rose red) (lily white) (buttercup yellow))) + +(rassq 'white colors) + @result{} nil +@end smallexample + +In this case, the @sc{cdr} of the association @code{(lily white)} is not +the symbol @code{white}, but rather the list @code{(white)}. This +becomes clearer if the association is written in dotted pair notation: + +@smallexample +(lily white) @equiv{} (lily . (white)) +@end smallexample +@end defun + +@defun copy-alist alist +@cindex copying alists +This function returns a two-level deep copy of @var{alist}: it creates a +new copy of each association, so that you can alter the associations of +the new alist without changing the old one. + +@smallexample +@group +(setq needles-per-cluster + '((2 . ("Austrian Pine" "Red Pine")) + (3 . "Pitch Pine") + (5 . "White Pine"))) +@result{} +((2 "Austrian Pine" "Red Pine") + (3 . "Pitch Pine") + (5 . "White Pine")) + +(setq copy (copy-alist needles-per-cluster)) +@result{} +((2 "Austrian Pine" "Red Pine") + (3 . "Pitch Pine") + (5 . "White Pine")) + +(eq needles-per-cluster copy) + @result{} nil +(equal needles-per-cluster copy) + @result{} t +(eq (car needles-per-cluster) (car copy)) + @result{} nil +(cdr (car (cdr needles-per-cluster))) + @result{} "Pitch Pine" +(eq (cdr (car (cdr needles-per-cluster))) + (cdr (car (cdr copy)))) + @result{} t +@end group +@end smallexample +@end defun + +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/macros.texi Mon Mar 28 20:21:44 1994 +0000 @@ -0,0 +1,593 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/macros +@node Macros, Loading, Functions, Top +@chapter Macros +@cindex macros + + @dfn{Macros} enable you to define new control constructs and other +language features. A macro is defined much like a function, but instead +of telling how to compute a value, it tells how to compute another Lisp +expression which will in turn compute the value. We call this +expression the @dfn{expansion} of the macro. + + Macros can do this because they operate on the unevaluated expressions +for the arguments, not on the argument values as functions do. They can +therefore construct an expansion containing these argument expressions +or parts of them. + + If you are using a macro to do something an ordinary function could +do, just for the sake of speed, consider using an inline function +instead. @xref{Inline Functions}. + +@menu +* Simple Macro:: A basic example. +* Expansion:: How, when and why macros are expanded. +* Compiling Macros:: How macros are expanded by the compiler. +* Defining Macros:: How to write a macro definition. +* Backquote:: Easier construction of list structure. +* Problems with Macros:: Don't evaluate the macro arguments too many times. + Don't hide the user's variables. +@end menu + +@node Simple Macro +@section A Simple Example of a Macro + + Suppose we would like to define a Lisp construct to increment a +variable value, much like the @code{++} operator in C. We would like to +write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}. +Here's a macro definition that does the job: + +@findex inc +@example +@group +(defmacro inc (var) + (list 'setq var (list '1+ var))) +@end group +@end example + + When this is called with @code{(inc x)}, the argument @code{var} has +the value @code{x}---@emph{not} the @emph{value} of @code{x}. The body +of the macro uses this to construct the expansion, which is @code{(setq +x (1+ x))}. Once the macro definition returns this expansion, Lisp +proceeds to evaluate it, thus incrementing @code{x}. + +@node Expansion +@section Expansion of a Macro Call +@cindex expansion of macros +@cindex macro call + + A macro call looks just like a function call in that it is a list which +starts with the name of the macro. The rest of the elements of the list +are the arguments of the macro. + + Evaluation of the macro call begins like evaluation of a function call +except for one crucial difference: the macro arguments are the actual +expressions appearing in the macro call. They are not evaluated before +they are given to the macro definition. By contrast, the arguments of a +function are results of evaluating the elements of the function call +list. + + Having obtained the arguments, Lisp invokes the macro definition just +as a function is invoked. The argument variables of the macro are bound +to the argument values from the macro call, or to a list of them in the +case of a @code{&rest} argument. And the macro body executes and +returns its value just as a function body does. + + The second crucial difference between macros and functions is that the +value returned by the macro body is not the value of the macro call. +Instead, it is an alternate expression for computing that value, also +known as the @dfn{expansion} of the macro. The Lisp interpreter +proceeds to evaluate the expansion as soon as it comes back from the +macro. + + Since the expansion is evaluated in the normal manner, it may contain +calls to other macros. It may even be a call to the same macro, though +this is unusual. + + You can see the expansion of a given macro call by calling +@code{macroexpand}. + +@defun macroexpand form &optional environment +@cindex macro expansion +This function expands @var{form}, if it is a macro call. If the result +is another macro call, it is expanded in turn, until something which is +not a macro call results. That is the value returned by +@code{macroexpand}. If @var{form} is not a macro call to begin with, it +is returned as given. + +Note that @code{macroexpand} does not look at the subexpressions of +@var{form} (although some macro definitions may do so). Even if they +are macro calls themselves, @code{macroexpand} does not expand them. + +The function @code{macroexpand} does not expand calls to inline functions. +Normally there is no need for that, since a call to an inline function is +no harder to understand than a call to an ordinary function. + +If @var{environment} is provided, it specifies an alist of macro +definitions that shadow the currently defined macros. Byte compilation +uses this feature. + +@smallexample +@group +(defmacro inc (var) + (list 'setq var (list '1+ var))) + @result{} inc +@end group + +@group +(macroexpand '(inc r)) + @result{} (setq r (1+ r)) +@end group + +@group +(defmacro inc2 (var1 var2) + (list 'progn (list 'inc var1) (list 'inc var2))) + @result{} inc2 +@end group + +@group +(macroexpand '(inc2 r s)) + @result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.} +@end group +@end smallexample +@end defun + +@node Compiling Macros +@section Macros and Byte Compilation +@cindex byte-compiling macros + + You might ask why we take the trouble to compute an expansion for a +macro and then evaluate the expansion. Why not have the macro body +produce the desired results directly? The reason has to do with +compilation. + + When a macro call appears in a Lisp program being compiled, the Lisp +compiler calls the macro definition just as the interpreter would, and +receives an expansion. But instead of evaluating this expansion, it +compiles the expansion as if it had appeared directly in the program. +As a result, the compiled code produces the value and side effects +intended for the macro, but executes at full compiled speed. This would +not work if the macro body computed the value and side effects +itself---they would be computed at compile time, which is not useful. + + In order for compilation of macro calls to work, the macros must be +defined in Lisp when the calls to them are compiled. The compiler has a +special feature to help you do this: if a file being compiled contains a +@code{defmacro} form, the macro is defined temporarily for the rest of +the compilation of that file. To use this feature, you must define the +macro in the same file where it is used and before its first use. + + Byte-compiling a file executes any @code{require} calls at top-level +in the file. This is in case the file needs the required packages for +proper compilation. One way to ensure that necessary macro definitions +are available during compilation is to require the file that defines +them. @xref{Features}. + +@node Defining Macros +@section Defining Macros + + A Lisp macro is a list whose @sc{car} is @code{macro}. Its @sc{cdr} should +be a function; expansion of the macro works by applying the function +(with @code{apply}) to the list of unevaluated argument-expressions +from the macro call. + + It is possible to use an anonymous Lisp macro just like an anonymous +function, but this is never done, because it does not make sense to pass +an anonymous macro to mapping functions such as @code{mapcar}. In +practice, all Lisp macros have names, and they are usually defined with +the special form @code{defmacro}. + +@defspec defmacro name argument-list body-forms@dots{} +@code{defmacro} defines the symbol @var{name} as a macro that looks +like this: + +@example +(macro lambda @var{argument-list} . @var{body-forms}) +@end example + +This macro object is stored in the function cell of @var{name}. The +value returned by evaluating the @code{defmacro} form is @var{name}, but +usually we ignore this value. + +The shape and meaning of @var{argument-list} is the same as in a +function, and the keywords @code{&rest} and @code{&optional} may be used +(@pxref{Argument List}). Macros may have a documentation string, but +any @code{interactive} declaration is ignored since macros cannot be +called interactively. +@end defspec + +@node Backquote +@section Backquote +@cindex backquote (list substitution) +@cindex ` (list substitution) + + Macros often need to construct large list structures from a mixture of +constants and nonconstant parts. To make this easier, use the macro +@code{`} (often called @dfn{backquote}). + + Backquote allows you to quote a list, but selectively evaluate +elements of that list. In the simplest case, it is identical to the +special form @code{quote} (@pxref{Quoting}). For example, these +two forms yield identical results: + +@example +@group +(` (a list of (+ 2 3) elements)) + @result{} (a list of (+ 2 3) elements) +@end group +@group +(quote (a list of (+ 2 3) elements)) + @result{} (a list of (+ 2 3) elements) +@end group +@end example + +@findex , @{(with Backquote)} +The special marker, @code{,}, inside of the argument to backquote, +indicates a value that isn't constant. Backquote evaluates the +argument of @code{,} and puts the value in the list structure: + +@example +@group +(list 'a 'list 'of (+ 2 3) 'elements) + @result{} (a list of 5 elements) +@end group +@group +(` (a list of (, (+ 2 3)) elements)) + @result{} (a list of 5 elements) +@end group +@end example + +@findex ,@@ @{(with Backquote)} +@cindex splicing (with backquote) +You can also @dfn{splice} an evaluated value into the resulting list, +using the special marker @code{,@@}. The elements of the spliced list +become elements at the same level as the other elements of the resulting +list. The equivalent code without using @code{`} is often unreadable. +Here are some examples: + +@example +@group +(setq some-list '(2 3)) + @result{} (2 3) +@end group +@group +(cons 1 (append some-list '(4) some-list)) + @result{} (1 2 3 4 2 3) +@end group +@group +(` (1 (,@@ some-list) 4 (,@@ some-list))) + @result{} (1 2 3 4 2 3) +@end group + +@group +(setq list '(hack foo bar)) + @result{} (hack foo bar) +@end group +@group +(cons 'use + (cons 'the + (cons 'words (append (cdr list) '(as elements))))) + @result{} (use the words foo bar as elements) +@end group +@group +(` (use the words (,@@ (cdr list)) as elements)) + @result{} (use the words foo bar as elements) +@end group +@end example + +Emacs 18 had a bug which made the previous example fail. The bug +affected @code{,@@} followed only by constant elements. If you are +concerned with Emacs 18 compatibility, you can work around the bug like +this: + +@example +(` (use the words (,@@ (cdr list)) as elements @code{(,@@ nil)})) +@end example + +@noindent +@code{(,@@ nil)} avoids the problem by being a nonconstant element that +does not affect the result. + +@defmac ` list +This macro quotes @var{list} except for any sublists of the form +@code{(, @var{subexp})} or @code{(,@@ @var{listexp})}. Backquote +replaces these sublists with the value of @var{subexp} (as a single +element) or @var{listexp} (by splicing). Backquote copies the structure +of @var{list} down to the places where variable parts are substituted. + +@ignore @c these work now! +There are certain contexts in which @samp{,} would not be recognized and +should not be used: + +@smallexample +@group +;; @r{Use of a @samp{,} expression as the @sc{cdr} of a list.} +(` (a . (, 1))) ; @r{Not @code{(a . 1)}} + @result{} (a \, 1) +@end group + +@group +;; @r{Use of @samp{,} in a vector.} +(` [a (, 1) c]) ; @r{Not @code{[a 1 c]}} + @error{} Wrong type argument +@end group +@end smallexample +@end ignore +@end defmac + +@cindex CL note---@samp{,}, @samp{,@@} as functions +@quotation +@b{Common Lisp note:} in Common Lisp, @samp{,} and @samp{,@@} are implemented +as reader macros, so they do not require parentheses. Emacs Lisp implements +them as functions because reader macros are not supported (to save space). +@end quotation + +@node Problems with Macros +@section Common Problems Using Macros + + The basic facts of macro expansion have counterintuitive consequences. +This section describes some important consequences that can lead to +trouble, and rules to follow to avoid trouble. + +@menu +* Argument Evaluation:: The expansion should evaluate each macro arg once. +* Surprising Local Vars:: Local variable bindings in the expansion + require special care. +* Eval During Expansion:: Don't evaluate them; put them in the expansion. +* Repeated Expansion:: Avoid depending on how many times expansion is done. +@end menu + +@node Argument Evaluation +@subsection Evaluating Macro Arguments Repeatedly + + When defining a macro you must pay attention to the number of times +the arguments will be evaluated when the expansion is executed. The +following macro (used to facilitate iteration) illustrates the problem. +This macro allows us to write a simple ``for'' loop such as one might +find in Pascal. + +@findex for +@smallexample +@group +(defmacro for (var from init to final do &rest body) + "Execute a simple \"for\" loop. +For example, (for i from 1 to 10 do (print i))." + (list 'let (list (list var init)) + (cons 'while (cons (list '<= var final) + (append body (list (list 'inc var))))))) +@end group +@result{} for + +@group +(for i from 1 to 3 do + (setq square (* i i)) + (princ (format "\n%d %d" i square))) +@expansion{} +@end group +@group +(let ((i 1)) + (while (<= i 3) + (setq square (* i i)) + (princ (format "%d %d" i square)) + (inc i))) +@end group +@group + + @print{}1 1 + @print{}2 4 + @print{}3 9 +@result{} nil +@end group +@end smallexample + +@noindent +(The arguments @code{from}, @code{to}, and @code{do} in this macro are +``syntactic sugar''; they are entirely ignored. The idea is that you +will write noise words (such as @code{from}, @code{to}, and @code{do}) +in those positions in the macro call.) + +This macro suffers from the defect that @var{final} is evaluated on +every iteration. If @var{final} is a constant, this is not a problem. +If it is a more complex form, say @code{(long-complex-calculation x)}, +this can slow down the execution significantly. If @var{final} has side +effects, executing it more than once is probably incorrect. + +@cindex macro argument evaluation +A well-designed macro definition takes steps to avoid this problem by +producing an expansion that evaluates the argument expressions exactly +once unless repeated evaluation is part of the intended purpose of the +macro. Here is a correct expansion for the @code{for} macro: + +@smallexample +@group +(let ((i 1) + (max 3)) + (while (<= i max) + (setq square (* i i)) + (princ (format "%d %d" i square)) + (inc i))) +@end group +@end smallexample + +Here is a macro definition that creates this expansion: + +@smallexample +@group +(defmacro for (var from init to final do &rest body) + "Execute a simple for loop: (for i from 1 to 10 do (print i))." + (` (let (((, var) (, init)) + (max (, final))) + (while (<= (, var) max) + (,@@ body) + (inc (, var)))))) +@end group +@end smallexample + + Unfortunately, this introduces another problem. +@ifinfo +Proceed to the following node. +@end ifinfo + +@node Surprising Local Vars +@subsection Local Variables in Macro Expansions + +@ifinfo + In the previous section, the definition of @code{for} was fixed as +follows to make the expansion evaluate the macro arguments the proper +number of times: + +@smallexample +@group +(defmacro for (var from init to final do &rest body) + "Execute a simple for loop: (for i from 1 to 10 do (print i))." +@end group +@group + (` (let (((, var) (, init)) + (max (, final))) + (while (<= (, var) max) + (,@@ body) + (inc (, var)))))) +@end group +@end smallexample +@end ifinfo + + The new definition of @code{for} has a new problem: it introduces a +local variable named @code{max} which the user does not expect. This +causes trouble in examples such as the following: + +@example +@group +(let ((max 0)) + (for x from 0 to 10 do + (let ((this (frob x))) + (if (< max this) + (setq max this))))) +@end group +@end example + +@noindent +The references to @code{max} inside the body of the @code{for}, which +are supposed to refer to the user's binding of @code{max}, really access +the binding made by @code{for}. + +The way to correct this is to use an uninterned symbol instead of +@code{max} (@pxref{Creating Symbols}). The uninterned symbol can be +bound and referred to just like any other symbol, but since it is created +by @code{for}, we know that it cannot appear in the user's program. +Since it is not interned, there is no way the user can put it into the +program later. It will never appear anywhere except where put by +@code{for}. Here is a definition of @code{for} which works this way: + +@smallexample +@group +(defmacro for (var from init to final do &rest body) + "Execute a simple for loop: (for i from 1 to 10 do (print i))." + (let ((tempvar (make-symbol "max"))) + (` (let (((, var) (, init)) + ((, tempvar) (, final))) + (while (<= (, var) (, tempvar)) + (,@@ body) + (inc (, var))))))) +@end group +@end smallexample + +@noindent +This creates an uninterned symbol named @code{max} and puts it in the +expansion instead of the usual interned symbol @code{max} that appears +in expressions ordinarily. + +@node Eval During Expansion +@subsection Evaluating Macro Arguments in Expansion + + Another problem can happen if you evaluate any of the macro argument +expressions during the computation of the expansion, such as by calling +@code{eval} (@pxref{Eval}). If the argument is supposed to refer to the +user's variables, you may have trouble if the user happens to use a +variable with the same name as one of the macro arguments. Inside the +macro body, the macro argument binding is the most local binding of this +variable, so any references inside the form being evaluated do refer +to it. Here is an example: + +@example +@group +(defmacro foo (a) + (list 'setq (eval a) t)) + @result{} foo +@end group +@group +(setq x 'b) +(foo x) @expansion{} (setq b t) + @result{} t ; @r{and @code{b} has been set.} +;; @r{but} +(setq a 'c) +(foo a) @expansion{} (setq a t) + @result{} t ; @r{but this set @code{a}, not @code{c}.} + +@end group +@end example + + It makes a difference whether the user's variable is named @code{a} or +@code{x}, because @code{a} conflicts with the macro argument variable +@code{a}. + + Another reason not to call @code{eval} in a macro definition is that +it probably won't do what you intend in a compiled program. The +byte-compiler runs macro definitions while compiling the program, when +the program's own computations (which you might have wished to access +with @code{eval}) don't occur and its local variable bindings don't +exist. + + The safe way to work with the run-time value of an expression is to +put the expression into the macro expansion, so that its value is +computed as part of executing the expansion. + +@node Repeated Expansion +@subsection How Many Times is the Macro Expanded? + + Occasionally problems result from the fact that a macro call is +expanded each time it is evaluated in an interpreted function, but is +expanded only once (during compilation) for a compiled function. If the +macro definition has side effects, they will work differently depending +on how many times the macro is expanded. + + In particular, constructing objects is a kind of side effect. If the +macro is called once, then the objects are constructed only once. In +other words, the same structure of objects is used each time the macro +call is executed. In interpreted operation, the macro is reexpanded +each time, producing a fresh collection of objects each time. Usually +this does not matter---the objects have the same contents whether they +are shared or not. But if the surrounding program does side effects +on the objects, it makes a difference whether they are shared. Here is +an example: + +@lisp +@group +(defmacro empty-object () + (list 'quote (cons nil nil))) +@end group + +@group +(defun initialize (condition) + (let ((object (empty-object))) + (if condition + (setcar object condition)) + object)) +@end group +@end lisp + +@noindent +If @code{initialize} is interpreted, a new list @code{(nil)} is +constructed each time @code{initialize} is called. Thus, no side effect +survives between calls. If @code{initialize} is compiled, then the +macro @code{empty-object} is expanded during compilation, producing a +single ``constant'' @code{(nil)} that is reused and altered each time +@code{initialize} is called. + +One way to avoid pathological cases like this is to think of +@code{empty-object} as a funny kind of constant, not as a memory +allocation construct. You wouldn't use @code{setcar} on a constant such +as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)} +either.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/os.texi Mon Mar 28 20:21:44 1994 +0000 @@ -0,0 +1,1355 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/os +@node System Interface, Display, Processes, Top +@chapter Operating System Interface + + This chapter is about starting and getting out of Emacs, access to +values in the operating system environment, and terminal input, output +and flow control. + + @xref{Building Emacs}, for related information. See also +@ref{Display}, for additional operating system status information +pertaining to the terminal and the screen. + +@menu +* Starting Up:: Customizing Emacs start-up processing. +* Getting Out:: How exiting works (permanent or temporary). +* System Environment:: Distinguish the name and kind of system. +* User Identification:: Finding the name and user id of the user. +* Time of Day:: Getting the current time. +* Timers:: Setting a timer to call a function at a certain time. +* Terminal Input:: Recording terminal input for debugging. +* Terminal Output:: Recording terminal output for debugging. +* Special Keysyms:: Defining system-specific key symbols for X windows. +* Flow Control:: How to turn output flow control on or off. +* Batch Mode:: Running Emacs without terminal interaction. +@end menu + +@node Starting Up +@section Starting Up Emacs + + This section describes what Emacs does when it is started, and how you +can customize these actions. + +@menu +* Start-up Summary:: Sequence of actions Emacs performs at start-up. +* Init File:: Details on reading the init file (@file{.emacs}). +* Terminal-Specific:: How the terminal-specific Lisp file is read. +* Command Line Arguments:: How command line arguments are processed, + and how you can customize them. +@end menu + +@node Start-up Summary +@subsection Summary: Sequence of Actions at Start Up +@cindex initialization +@cindex start up of Emacs +@cindex @file{startup.el} + + The order of operations performed (in @file{startup.el}) by Emacs when +it is started up is as follows: + +@enumerate +@item +It loads the initialization library for the window system, if you are +using a window system. This library's name is +@file{term/@var{windowsystem}-win.el}. + +@item +It initializes the X window frame and faces, if appropriate. + +@item +It runs the normal hook @code{before-init-hook}. + +@item +It loads the library @file{site-start}, unless the option +@samp{-no-site-file} was specified. The library's file name is usually +@file{site-start.el}. +@cindex @file{site-start.el} + +@item +It loads the file @file{~/.emacs} unless @samp{-q} was specified on +command line. (This is not done in @samp{-batch} mode.) The @samp{-u} +option can specify the user name whose home directory should be used +instead of @file{~}. + +@item +It loads the library @file{default} unless @code{inhibit-default-init} +is non-@code{nil}. (This is not done in @samp{-batch} mode or if +@samp{-q} was specified on command line.) The library's file name is +usually @file{default.el}. +@cindex @file{default.el} + +@item +It runs the normal hook @code{after-init-hook}. + +@item +It sets the major mode according to @code{initial-major-mode}, provided +the buffer @samp{*scratch*} is still current and still in Fundamental +mode. + +@item +It loads the terminal-specific Lisp file, if any, except when in batch +mode or using a window system. + +@item +It displays the initial echo area message, unless you have suppressed +that with @code{inhibit-startup-echo-area-message}. + +@item +It processes any remaining command line arguments. + +@item +It runs @code{term-setup-hook}. + +@item +It calls @code{frame-notice-user-settings}, which modifies the +parameters of the selected frame according to whatever the init files +specify. + +@item +It runs @code{window-setup-hook}. @xref{Window Systems}. + +@item +It displays copyleft, nonwarranty and basic use information, provided +there were no remaining command line arguments (a few steps above) and +the value of @code{inhibit-startup-message} is @code{nil}. +@end enumerate + +@defopt inhibit-startup-message +This variable inhibits the initial startup messages (the nonwarranty, +etc.). If it is non-@code{nil}, then the messages are not printed. + +This variable exists so you can set it in your personal init file, once +you are familiar with the contents of the startup message. Do not set +this variable in the init file of a new user, or in a way that affects +more than one user, because that would prevent new users from receiving +the information they are supposed to see. +@end defopt + +@defopt inhibit-startup-echo-area-message +This variable controls the display of the startup echo area message. +You can suppress the startup echo area message by adding text with this +form to your @file{.emacs} file: + +@example +(setq inhibit-startup-echo-area-message + "@var{your-login-name}") +@end example + +Simply setting @code{inhibit-startup-echo-area-message} to your login +name is not sufficient to inhibit the message; Emacs explicitly checks +whether @file{.emacs} contains an expression as shown above. Your login +name must appear in the expression as a Lisp string constant. + +This way, you can easily inhibit the message for yourself if you wish, +but thoughtless copying of your @file{.emacs} file will not inhibit the +message for someone else. +@end defopt + +@node Init File +@subsection The Init File: @file{.emacs} +@cindex init file +@cindex @file{.emacs} + + When you start Emacs, it normally attempts to load the file +@file{.emacs} from your home directory. This file, if it exists, must +contain Lisp code. It is called your @dfn{init file}. The command line +switches @samp{-q} and @samp{-u} affect the use of the init file; +@samp{-q} says not to load an init file, and @samp{-u} says to load a +specified user's init file instead of yours. @xref{Entering Emacs, , , +emacs, The GNU Emacs Manual}. + +@cindex default init file + A site may have a @dfn{default init file}, which is the library named +@file{default.el}. Emacs finds the @file{default.el} file through the +standard search path for libraries (@pxref{How Programs Do Loading}). +The Emacs distribution does not come with this file; sites may provide +one for local customizations. If the default init file exists, it is +loaded whenever you start Emacs, except in batch mode or if @samp{-q} is +specified. But your own personal init file, if any, is loaded first; if +it sets @code{inhibit-default-init} to a non-@code{nil} value, then +Emacs does not subsequently load the @file{default.el} file. + + Another file for site-customization is @file{site-start.el}. Emacs +loads this @emph{before} the user's init file. You can inhibit the +loading of this file with the option @samp{-no-site-file}. + + If there is a great deal of code in your @file{.emacs} file, you +should move it into another file named @file{@var{something}.el}, +byte-compile it (@pxref{Byte Compilation}), and make your @file{.emacs} +file load the other file using @code{load} (@pxref{Loading}). + + @xref{Init File Examples, , , emacs, The GNU Emacs Manual}, for +examples of how to make various commonly desired customizations in your +@file{.emacs} file. + +@defopt inhibit-default-init +This variable prevents Emacs from loading the default initialization +library file for your session of Emacs. If its value is non-@code{nil}, +then the default library is not loaded. The default value is +@code{nil}. +@end defopt + +@defvar before-init-hook +@defvarx after-init-hook +These two normal hooks are run just before, and just after, loading of +the user's init file, @file{default.el}, and/or @file{site-start.el}. +@end defvar + +@node Terminal-Specific +@subsection Terminal-Specific Initialization +@cindex terminal-specific initialization + + Each terminal type can have its own Lisp library that Emacs loads when +run on that type of terminal. For a terminal type named @var{termtype}, +the library is called @file{term/@var{termtype}}. Emacs finds the file +by searching the @code{load-path} directories as it does for other +files, and trying the @samp{.elc} and @samp{.el} suffixes. Normally, +terminal-specific Lisp library is located in @file{emacs/lisp/term}, a +subdirectory of the @file{emacs/lisp} directory in which most Emacs Lisp +libraries are kept.@refill + + The library's name is constructed by concatenating the value of the +variable @code{term-file-prefix} and the terminal type. Normally, +@code{term-file-prefix} has the value @code{"term/"}; changing this +is not recommended. + + The usual function of a terminal-specific library is to enable special +keys to send sequences that Emacs can recognize. It may also need to +set or add to @code{function-key-map} if the Termcap entry does not +specify all the terminal's function keys. @xref{Terminal Input}. + +@cindex Termcap + When the name of the terminal type contains a hyphen, only the part of +the name before the first hyphen is significant in choosing the library +name. Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use +the @file{term/aaa} library. If necessary, the library can evaluate +@code{(getenv "TERM")} to find the full name of the terminal +type.@refill + + Your @file{.emacs} file can prevent the loading of the +terminal-specific library by setting the variable +@code{term-file-prefix} to @code{nil}. This feature is useful when +experimenting with your own peculiar customizations. + + You can also arrange to override some of the actions of the +terminal-specific library by setting the variable +@code{term-setup-hook}. This is a normal hook which Emacs runs using +@code{run-hooks} at the end of Emacs initialization, after loading both +your @file{.emacs} file and any terminal-specific libraries. You can +use this variable to define initializations for terminals that do not +have their own libraries. @xref{Hooks}. + +@defvar term-file-prefix +@cindex @code{TERM} environment variable +If the @code{term-file-prefix} variable is non-@code{nil}, Emacs loads +a terminal-specific initialization file as follows: + +@example +(load (concat term-file-prefix (getenv "TERM"))) +@end example + +@noindent +You may set the @code{term-file-prefix} variable to @code{nil} in your +@file{.emacs} file if you do not wish to load the +terminal-initialization file. To do this, put the following in +your @file{.emacs} file: @code{(setq term-file-prefix nil)}. +@end defvar + +@defvar term-setup-hook +This variable is a normal hook which Emacs runs after loading your +@file{.emacs} file, the default initialization file (if any) and the +terminal-specific Lisp file. + +You can use @code{term-setup-hook} to override the definitions made by a +terminal-specific file. +@end defvar + + See @code{window-setup-hook} in @ref{Window Systems}, for a related +feature. + +@node Command Line Arguments +@subsection Command Line Arguments +@cindex command line arguments + + You can use command line arguments to request various actions when you +start Emacs. Since you do not need to start Emacs more than once per +day, and will often leave your Emacs session running longer than that, +command line arguments are hardly ever used. As a practical matter, it +is best to avoid making the habit of using them, since this habit would +encourage you to kill and restart Emacs unnecessarily often. These +options exist for two reasons: to be compatible with other editors (for +invocation by other programs) and to enable shell scripts to run +specific Lisp programs. + + This section describes how Emacs processes command line arguments, +and how you can customize them. + +@ignore + (Note that some other editors require you to start afresh each time +you want to edit a file. With this kind of editor, you will probably +specify the file as a command line argument. The recommended way to +use GNU Emacs is to start it only once, just after you log in, and do +all your editing in the same Emacs process. Each time you want to edit +a different file, you visit it with the existing Emacs, which eventually +comes to have many files in it ready for editing. Usually you do not +kill the Emacs until you are about to log out.) +@end ignore + +@defun command-line +This function parses the command line which Emacs was called with, +processes it, loads the user's @file{.emacs} file and displays the +initial nonwarranty information, etc. +@end defun + +@defvar command-line-processed +The value of this variable is @code{t} once the command line has been +processed. + +If you redump Emacs by calling @code{dump-emacs}, you may wish to set +this variable to @code{nil} first in order to cause the new dumped Emacs +to process its new command line arguments. +@end defvar + +@defvar command-switch-alist +@cindex switches on command line +@cindex options on command line +@cindex command line options +The value of this variable is an alist of user-defined command-line +options and associated handler functions. This variable exists so you +can add elements to it. + +A @dfn{command line option} is an argument on the command line of the +form: + +@example +-@var{option} +@end example + +The elements of the @code{command-switch-alist} look like this: + +@example +(@var{option} . @var{handler-function}) +@end example + +The @var{handler-function} is called to handle @var{option} and receives +the option name as its sole argument. + +In some cases, the option is followed in the command line by an +argument. In these cases, the @var{handler-function} can find all the +remaining command-line arguments in the variable +@code{command-line-args-left}. (The entire list of command-line +arguments is in @code{command-line-args}.) + +The command line arguments are parsed by the @code{command-line-1} +function in the @file{startup.el} file. See also @ref{Command +Switches, , Command Line Switches and Arguments, emacs, The GNU Emacs +Manual}. +@end defvar + +@defvar command-line-args +The value of this variable is the list of command line arguments passed +to Emacs. +@end defvar + +@defvar command-line-functions +This variable's value is a list of functions for handling an +unrecognized command-line argument. Each time the next argument to be +processed has no special meaning, the functions in this list are called, +in the order they appear, until one of them returns a non-@code{nil} +value. + +These functions are called with no arguments. They can access the +command-line argument under consideration through the variable +@code{argi}. The remaining arguments (not including the current one) +are in the variable @code{command-line-args-left}. + +When a function recognizes and processes the argument in @code{argi}, it +should return a non-@code{nil} value to say it has dealt with that +argument. If it has also dealt with some of the following arguments, it +can indicate that by deleting them from @code{command-line-args-left}. + +If all of these functions return @code{nil}, then the argument is used +as a file name to visit. +@end defvar + +@node Getting Out +@section Getting Out of Emacs +@cindex exiting Emacs + + There are two ways to get out of Emacs: you can kill the Emacs job, +which exits permanently, or you can suspend it, which permits you to +reenter the Emacs process later. As a practical matter, you seldom kill +Emacs---only when you are about to log out. Suspending is much more +common. + +@menu +* Killing Emacs:: Exiting Emacs irreversibly. +* Suspending Emacs:: Exiting Emacs reversibly. +@end menu + +@node Killing Emacs +@comment node-name, next, previous, up +@subsection Killing Emacs +@cindex killing Emacs + + Killing Emacs means ending the execution of the Emacs process. The +parent process normally resumes control. The low-level primitive for +killing Emacs is @code{kill-emacs}. + +@defun kill-emacs &optional exit-data +This function exits the Emacs process and kills it. + +If @var{exit-data} is an integer, then it is used as the exit status +of the Emacs process. (This is useful primarily in batch operation; see +@ref{Batch Mode}.) + +If @var{exit-data} is a string, its contents are stuffed into the +terminal input buffer so that the shell (or whatever program next reads +input) can read them. +@end defun + + All the information in the Emacs process, aside from files that have +been saved, is lost when the Emacs is killed. Because killing Emacs +inadvertently can lose a lot of work, Emacs queries for confirmation +before actually terminating if you have buffers that need saving or +subprocesses that are running. This is done in the function +@code{save-buffers-kill-emacs}. + +@defvar kill-emacs-query-functions +After asking the standard questions, @code{save-buffers-kill-emacs} +calls the functions in the list @code{kill-buffer-query-functions}, in +order of appearance, with no arguments. These functions can ask for +additional confirmation from the user. If any of them returns +non-@code{nil}, Emacs is not killed. +@end defvar + +@defvar kill-emacs-hook +This variable is a normal hook; once @code{save-buffers-kill-emacs} is +finished with all file saving and confirmation, it runs the functions in +this hook. +@end defvar + +@node Suspending Emacs +@subsection Suspending Emacs +@cindex suspending Emacs + + @dfn{Suspending Emacs} means stopping Emacs temporarily and returning +control to its superior process, which is usually the shell. This +allows you to resume editing later in the same Emacs process, with the +same buffers, the same kill ring, the same undo history, and so on. To +resume Emacs, use the appropriate command in the parent shell---most +likely @code{fg}. + + Some operating systems do not support suspension of jobs; on these +systems, ``suspension'' actually creates a new shell temporarily as a +subprocess of Emacs. Then you would exit the shell to return to Emacs. + + Suspension is not useful with window systems such as X, because the +Emacs job may not have a parent that can resume it again, and in any +case you can give input to some other job such as a shell merely by +moving to a different window. Therefore, suspending is not allowed +when Emacs is an X client. + +@defun suspend-emacs string +This function stops Emacs and returns control to the superior process. +If and when the superior process resumes Emacs, @code{suspend-emacs} +returns @code{nil} to its caller in Lisp. + +If @var{string} is non-@code{nil}, its characters are sent to be read +as terminal input by Emacs's superior shell. The characters in +@var{string} are not echoed by the superior shell; only the results +appear. + +Before suspending, @code{suspend-emacs} runs the normal hook +@code{suspend-hook}. In Emacs version 18, @code{suspend-hook} was not a +normal hook; its value was a single function, and if its value was +non-@code{nil}, then @code{suspend-emacs} returned immediately without +actually suspending anything. + +After the user resumes Emacs, it runs the normal hook +@code{suspend-resume-hook}. @xref{Hooks}. + +The next redisplay after resumption will redraw the entire screen, +unless the variable @code{no-redraw-on-reenter} is non-@code{nil} +(@pxref{Refresh Screen}). + +In the following example, note that @samp{pwd} is not echoed after +Emacs is suspended. But it is read and executed by the shell. + +@smallexample +@group +(suspend-emacs) + @result{} nil +@end group + +@group +(add-hook 'suspend-hook + (function (lambda () + (or (y-or-n-p + "Really suspend? ") + (error "Suspend cancelled"))))) + @result{} (lambda nil + (or (y-or-n-p "Really suspend? ") + (error "Suspend cancelled"))) +@end group +@group +(add-hook 'suspend-resume-hook + (function (lambda () (message "Resumed!")))) + @result{} (lambda nil (message "Resumed!")) +@end group +@group +(suspend-emacs "pwd") + @result{} nil +@end group +@group +---------- Buffer: Minibuffer ---------- +Really suspend? @kbd{y} +---------- Buffer: Minibuffer ---------- +@end group + +@group +---------- Parent Shell ---------- +lewis@@slug[23] % /user/lewis/manual +lewis@@slug[24] % fg +@end group + +@group +---------- Echo Area ---------- +Resumed! +@end group +@end smallexample +@end defun + +@defvar suspend-hook +This variable is a normal hook run before suspending. +@end defvar + +@defvar suspend-resume-hook +This variable is a normal hook run after suspending. +@end defvar + +@node System Environment +@section Operating System Environment +@cindex operating system environment + + Emacs provides access to variables in the operating system environment +through various functions. These variables include the name of the +system, the user's @sc{uid}, and so on. + +@defvar system-type +The value of this variable is a symbol indicating the type of +operating system Emacs is operating on. Here is a table of the symbols +for the operating systems that Emacs can run on up to version 19.1. + +@table @code +@item aix-v3 +AIX. + +@item berkeley-unix +Berkeley BSD. + +@item hpux +Hewlett-Packard operating system. + +@item irix +Silicon Graphics Irix system. + +@item rtu +Masscomp RTU, UCB universe. + +@item unisoft-unix +UniSoft UniPlus. + +@item usg-unix-v +AT&T System V. + +@item vax-vms +VAX VMS. + +@item xenix +SCO Xenix 386. +@end table + +We do not wish to add new symbols to make finer distinctions unless it +is absolutely necessary! In fact, we hope to eliminate some of these +alternatives in the future. We recommend using +@code{system-configuration} to distinguish between different operating +systems. +@end defvar + +@defvar system-configuration +This variable holds the three-part configuration name for the +hardware/software configuration of your system, as a string. The +convenient way to test parts of this string is with @code{string-match}. +@end defvar + +@defun system-name +This function returns the name of the machine you are running on. +@example +(system-name) + @result{} "prep.ai.mit.edu" +@end example +@end defun + +@defun getenv var +@cindex environment variable access +This function returns the value of the environment variable @var{var}, +as a string. Within Emacs, the environment variable values are kept in +the Lisp variable @code{process-environment}. + +@example +@group +(getenv "USER") + @result{} "lewis" +@end group + +@group +lewis@@slug[10] % printenv +PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin +USER=lewis +@end group +@group +TERM=ibmapa16 +SHELL=/bin/csh +HOME=/user/lewis +@end group +@end example +@end defun + +@c Emacs 19 feature +@deffn Command setenv variable value +This command sets the value of the environment variable named +@var{variable} to @var{value}. Both arguments should be strings. This +function works by modifying @code{process-environment}; binding that +variable with @code{let} is also reasonable practice. +@end deffn + +@defvar process-environment +This variable is a list of strings, each describing one environment +variable. The functions @code{getenv} and @code{setenv} work by means +of this variable. + +@smallexample +@group +process-environment +@result{} ("l=/usr/stanford/lib/gnuemacs/lisp" + "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin" + "USER=lewis" +@end group +@group + "TERM=ibmapa16" + "SHELL=/bin/csh" + "HOME=/user/lewis") +@end group +@end smallexample +@end defvar + +@defun load-average +This function returns the current 1 minute, 5 minute and 15 minute +load averages in a list. The values are integers that are 100 times +the system load averages. (The load averages indicate the number of +processes trying to run.) + +@example +@group +(load-average) + @result{} (169 48 36) +@end group + +@group +lewis@@rocky[5] % uptime + 11:55am up 1 day, 19:37, 3 users, + load average: 1.69, 0.48, 0.36 +@end group +@end example +@end defun + +@defun emacs-pid +This function returns the process @sc{id} of the Emacs process. +@end defun + +@defun setprv privilege-name &optional setp getprv +This function sets or resets a VMS privilege. (It does not exist on +Unix.) The first arg is the privilege name, as a string. The second +argument, @var{setp}, is @code{t} or @code{nil}, indicating whether the +privilege is to be turned on or off. Its default is @code{nil}. The +function returns @code{t} if successful, @code{nil} otherwise. + + If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv} +does not change the privilege, but returns @code{t} or @code{nil} +indicating whether the privilege is currently enabled. +@end defun + +@node User Identification +@section User Identification + +@defun user-login-name +This function returns the name under which the user is logged in. If +the environment variable @code{LOGNAME} is set, that value is used. +Otherwise, if the environment variable @code{USER} is set, that value is +used. Otherwise, the value is based on the effective @sc{uid}, not the +real @sc{uid}. + +@example +@group +(user-login-name) + @result{} "lewis" +@end group +@end example +@end defun + +@defun user-real-login-name +This function returns the user name corresponding to Emacs's real +@sc{uid}. This ignores the effective @sc{uid} and ignores the +environment variables @code{LOGNAME} and @code{USER}. +@end defun + +@defun user-full-name +This function returns the full name of the user. + +@example +@group +(user-full-name) + @result{} "Bil Lewis" +@end group +@end example +@end defun + +@defun user-real-uid +This function returns the real @sc{uid} of the user. + +@example +@group +(user-real-uid) + @result{} 19 +@end group +@end example +@end defun + +@defun user-uid +This function returns the effective @sc{uid} of the user. +@end defun + +@node Time of Day +@section Time of Day + + This section explains how to determine the current time and the time +zone. + +@defun current-time-string &optional time-value +This function returns the current time and date as a humanly-readable +string. The format of the string is unvarying; the number of characters +used for each part is always the same, so you can reliably use +@code{substring} to extract pieces of it. However, it would be wise to +count the characters from the beginning of the string rather than from +the end, as additional information may be added at the end. + +@c Emacs 19 feature +The argument @var{time-value}, if given, specifies a time to format +instead of the current time. The argument should be a cons cell +containing two integers, or a list whose first two elements are +integers. Thus, you can use times obtained from @code{current-time} +(see below) and from @code{file-attributes} (@pxref{File Attributes}). + +@example +@group +(current-time-string) + @result{} "Wed Oct 14 22:21:05 1987" +@end group +@end example +@end defun + +@c Emacs 19 feature +@defun current-time +This function returns the system's time value as a list of three +integers: @code{(@var{high} @var{low} @var{microsec})}. The integers +@var{high} and @var{low} combine to give the number of seconds since +0:00 January 1, 1970, which is +@ifinfo +@var{high} * 2**16 + @var{low}. +@end ifinfo +@tex +$high*-2^{16}+low$. +@end tex + +The third element, @var{microsec}, gives the microseconds since the +start of the current second (or 0 for systems that return time only on +the resolution of a second). + +The first two elements can be compared with file time values such as you +get with the function @code{file-attributes}. @xref{File Attributes}. +@end defun + +@c Emacs 19 feature +@defun current-time-zone &optional time-value +This function returns a list describing the time zone that the user is +in. + +The value has the form @code{(@var{offset} @var{name})}. Here +@var{offset} is an integer giving the number of seconds ahead of UTC +(east of Greenwich). A negative value means west of Greenwich. The +second element, @var{name} is a string giving the name of the time +zone. Both elements change when daylight savings time begins or ends; +if the user has specified a time zone that does not use a seasonal time +adjustment, then the value is constant through time. + +If the operating system doesn't supply all the information necessary to +compute the value, both elements of the list are @code{nil}. + +The argument @var{time-value}, if given, specifies a time to analyze +instead of the current time. The argument should be a cons cell +containing two integers, or a list whose first two elements are +integers. Thus, you can use times obtained from @code{current-time} +(see below) and from @code{file-attributes} (@pxref{File Attributes}). +@end defun + +@node Timers +@section Timers + +You can set up a timer to call a function at a specified future time. + +@defun run-at-time time repeat function &rest args +This function arranges to call @var{function} with arguments @var{args} +at time @var{time}. The argument @var{function} is a function to call +later, and @var{args} are the arguments to give it when it is called. +The time @var{time} is specified as a string. + +Absolute times may be specified in a wide variety of formats; The form +@samp{@var{hour}:@var{min}:@var{sec} @var{timezone} +@var{month}/@var{day}/@var{year}}, where all fields are numbers, works; +the format that @code{current-time-string} returns is also allowed. + +To specify a relative time, use numbers followed by units. +For example: + +@table @samp +@item 1 min +denotes 1 minute from now. +@item 1 min 5 sec +denotes 65 seconds from now. +@item 1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year +denotes exactly 103 months, 123 days, and 10862 seconds from now. +@end table + +If @var{time} is an integer, that specifies a relative time measured in +seconds. + +The argument @var{repeat} specifies how often to repeat the call. If +@var{repeat} is @code{nil}, there are no repetitions; @var{function} is +called just once, at @var{time}. If @var{repeat} is an integer, it +specifies a repetition period measured in seconds. +@end defun + +@defun cancel-timer timer +Cancel the requested action for @var{timer}, which should be a value +previously returned by @code{run-at-time}. This cancels the effect of +that call to @code{run-at-time}; the arrival of the specified time will +not cause anything special to happen. +@end defun + +@node Terminal Input +@section Terminal Input +@cindex terminal input + + This section describes functions and variables for recording or +manipulating terminal input. See @ref{Display}, for related +functions. + +@menu +* Input Modes:: Options for how input is processed. +* Translating Input:: Low level conversion of some characters or events + into others. +* Recording Input:: Saving histories of recent or all input events. +@end menu + +@node Input Modes +@subsection Input Modes +@cindex input modes +@cindex terminal input modes + +@defun set-input-mode interrupt flow meta quit-char +This function sets the mode for reading keyboard input. If +@var{interrupt} is non-null, then Emacs uses input interrupts. If it is +@code{nil}, then it uses @sc{cbreak} mode. + +If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} (@kbd{C-q}, +@kbd{C-s}) flow control for output to terminal. This has no effect except +in @sc{cbreak} mode. @xref{Flow Control}. + +The default setting is system dependent. Some systems always use +@sc{cbreak} mode regardless of what is specified. + +@c Emacs 19 feature +The argument @var{meta} controls support for input character codes +above 127. If @var{meta} is @code{t}, Emacs converts characters with +the 8th bit set into Meta characters. If @var{meta} is @code{nil}, +Emacs disregards the 8th bit; this is necessary when the terminal uses +it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil}, +Emacs uses all 8 bits of input unchanged. This is good for terminals +using European 8-bit character sets. + +@c Emacs 19 feature +If @var{quit-char} is non-@code{nil}, it specifies the character to +use for quitting. Normally this character is @kbd{C-g}. +@xref{Quitting}. +@end defun + +The @code{current-input-mode} function returns the input mode settings +Emacs is currently using. + +@c Emacs 19 feature +@defun current-input-mode +This function returns current mode for reading keyboard input. It +returns a list, corresponding to the arguments of @code{set-input-mode}, +of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in +which: +@table @var +@item interrupt +is non-@code{nil} when Emacs is using interrupt-driven input. If +@code{nil}, Emacs is using @sc{cbreak} mode. +@item flow +is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s}) +flow control for output to the terminal. This value has no effect +unless @var{interrupt} is non-@code{nil}. +@item meta +is non-@code{t} if Emacs treats the eighth bit of input characters as +the meta bit; @code{nil} means Emacs clears the eighth bit of every +input character; any other value means Emacs uses all eight bits as the +basic character code. +@item quit +is the character Emacs currently uses for quitting, usually @kbd{C-g}. +@end table +@end defun + +@defvar meta-flag +This variable used to control whether to treat the eight bit in keyboard +input characters as the @key{Meta} bit. @code{nil} meant no, and +anything else meant yes. This variable existed in Emacs versions 18 and +earlier but no longer exists in Emacs 19; use @code{set-input-mode} +instead. +@end defvar + +@node Translating Input +@subsection Translating Input Events +@cindex translating input events + + This section describes features for translating input events into other +input events before they become part of key sequences. + +@c Emacs 19 feature +@defvar extra-keyboard-modifiers +This variable lets Lisp programs ``press'' the modifier keys on the +keyboard. The value is a bit mask: + +@table @asis +@item 1 +The @key{SHIFT} key. +@item 2 +The @key{LOCK} key. +@item 4 +The @key{CTL} key. +@item 8 +The @key{META} key. +@end table + +Each time the user types a keyboard key, it is altered as if the +modifier keys specified in the bit mask were held down. + +When you use X windows, the program can ``press'' any of the modifier +keys in this way. Otherwise, only the @key{CTL} and @key{META} keys can +be virtually pressed. +@end defvar + +@defvar keyboard-translate-table +This variable is the translate table for keyboard characters. It lets +you reshuffle the keys on the keyboard without changing any command +bindings. Its value must be a string or @code{nil}. + +If @code{keyboard-translate-table} is a string, then each character read +from the keyboard is looked up in this string and the character in the +string is used instead. If the string is of length @var{n}, character codes +@var{n} and up are untranslated. + +In the example below, we set @code{keyboard-translate-table} to a +string of 128 characters. Then we fill it in to swap the characters +@kbd{C-s} and @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}. +Subsequently, typing @kbd{C-\} has all the usual effects of typing +@kbd{C-s}, and vice versa. (@xref{Flow Control} for more information on +this subject.) + +@cindex flow control example +@example +@group +(defun evade-flow-control () + "Replace C-s with C-\ and C-q with C-^." + (interactive) +@end group +@group + (let ((the-table (make-string 128 0))) + (let ((i 0)) + (while (< i 128) + (aset the-table i i) + (setq i (1+ i)))) +@end group + ;; @r{Swap @kbd{C-s} and @kbd{C-\}.} + (aset the-table ?\034 ?\^s) + (aset the-table ?\^s ?\034) +@group + ;; @r{Swap @kbd{C-q} and @kbd{C-^}.} + (aset the-table ?\036 ?\^q) + (aset the-table ?\^q ?\036) + (setq keyboard-translate-table the-table))) +@end group +@end example + +Note that this translation is the first thing that happens to a +character after it is read from the terminal. Record-keeping features +such as @code{recent-keys} and dribble files record the characters after +translation. +@end defvar + +@defun keyboard-translate from to +This function modifies @code{keyboard-translate-table} to translate +character code @var{from} into character code @var{to}. It creates +or enlarges the translate table if necessary. +@end defun + +@defvar function-key-map +This variable holds a keymap which describes the character sequences +sent by function keys on an ordinary character terminal. This keymap +uses the data structure as other keymaps, but is used differently: it +specifies translations to make while reading events. + +If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector +@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a +key sequence, it is replaced with the events in @var{v}. + +For example, VT100 terminals send @kbd{@key{ESC} O P} when the +keypad PF1 key is pressed. Therefore, we want Emacs to translate +that sequence of events into the single event @code{pf1}. We accomplish +this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in +@code{function-key-map}, when using a VT100. + +Thus, typing @kbd{C-c @key{PF1}} sends the character sequence @kbd{C-c +@key{ESC} O P}; later the function @code{read-key-sequence} translates +this back into @kbd{C-c @key{PF1}}, which it returns as the vector +@code{[?\C-c pf1]}. + +Entries in @code{function-key-map} are ignored if they conflict with +bindings made in the minor mode, local, or global keymaps. The intent +is that the character sequences that function keys send should not have +command bindings in their own right. + +The value of @code{function-key-map} is usually set up automatically +according to the terminal's Terminfo or Termcap entry, but sometimes +those need help from terminal-specific Lisp files. Emacs comes with +terminal-specific files for many common terminals; their main purpose is +to make entries in @code{function-key-map} beyond those that can be +deduced from Termcap and Terminfo. @xref{Terminal-Specific}. + +Emacs versions 18 and earlier used totally different means of detecting +the character sequences that represent function keys. +@end defvar + +@defvar key-translation-map +This variable is another keymap used just like @code{function-key-map} +to translate input events into other events. It differs from +@code{function-key-map} in two ways: + +@itemize @bullet +@item +@code{key-translation-map} goes to work after @code{function-key-map} is +finished; it receives the results of translation by +@code{function-key-map}. + +@item +@code{key-translation-map} overrides actual key bindings. +@end itemize + +The intent of @code{key-translation-map} is for users to map one +character set to another, including ordinary characters normally bound +to @code{self-insert-command}. +@end defvar + +@cindex key translation function +You can use @code{function-key-map} or @code{key-translation-map} for +more than simple aliases, by using a function, instead of a key +sequence, as the ``translation'' of a key. Then this function is called +to compute the translation of that key. + +The key translation function receives one argument, which is the prompt +that was specified in @code{read-key-sequence}---or @code{nil} if the +key sequence is being read by the editor command loop. In most cases +you can ignore the prompt value. + +If the function reads input itself, it can have the effect of altering +the event that follows. For example, here's how to define @kbd{C-c h} +to turn the character that follows into a Hyper character: + +@example +(defun hyperify (prompt) + (let ((e (read-event))) + (vector (if (numberp e) + (logior (lsh 1 20) e) + (if (memq 'hyper (event-modifiers e)) + e + (add-event-modifier "H-" e)))))) + +(defun add-event-modifier (string e) + (let ((symbol (if (symbolp e) e (car e)))) + (setq symbol (intern (concat string + (symbol-name symbol)))) + (if (symbolp e) + symbol + (cons symbol (cdr e))))) + +(define-key function-key-map "\C-ch" 'hyperify) +@end example + +@pindex iso-transl +@cindex Latin-1 character set (input) +@cindex ISO Latin-1 characters (input) +The @file{iso-transl} library uses this feature to provide a way of +inputting non-ASCII Latin-1 characters. + +@node Recording Input +@subsection Recording Input + +@defun recent-keys +This function returns a vector containing the last 100 input events +from the keyboard or mouse. All input events are included, whether or +not they were used as parts of key sequences. Thus, you always get the +last 100 inputs, not counting keyboard macros. (Events from keyboard +macros are excluded because they are less interesting for debugging; it +should be enough to see the events which invoked the macros.) +@end defun + +@deffn Command open-dribble-file filename +@cindex dribble file +This function opens a @dfn{dribble file} named @var{filename}. When a +dribble file is open, each input event from the keyboard or mouse (but +not those from keyboard macros) is written in that file. A +non-character event is expressed using its printed representation +surrounded by @samp{<@dots{}>}. + +You close the dribble file by calling this function with an argument +of @code{nil}. + +This function is normally used to record the input necessary to +trigger an Emacs bug, for the sake of a bug report. + +@example +@group +(open-dribble-file "~/dribble") + @result{} nil +@end group +@end example +@end deffn + + See also the @code{open-termscript} function (@pxref{Terminal Output}). + +@node Terminal Output +@section Terminal Output +@cindex terminal output + + The terminal output functions send output to the terminal or keep +track of output sent to the terminal. The variable @code{baud-rate} +tells you what Emacs thinks is the output speed of the terminal. + +@defvar baud-rate +This variable's value is the output speed of the terminal, as far as +Emacs knows. Setting this variable does not change the speed of actual +data transmission, but the value is used for calculations such as +padding. It also affects decisions about whether to scroll part of the +screen or repaint---even when using a window system, (We designed it +this way despite the fact that a window system has no true ``output +speed'', to give you a way to tune these decisions.) + +The value is measured in baud. +@end defvar + + If you are running across a network, and different parts of the +network work at different baud rates, the value returned by Emacs may be +different from the value used by your local terminal. Some network +protocols communicate the local terminal speed to the remote machine, so +that Emacs and other programs can get the proper value, but others do +not. If Emacs has the wrong value, it makes decisions that are less +than optimal. To fix the problem, set @code{baud-rate}. + +@defun baud-rate +This function returns the value of the variable @code{baud-rate}. In +Emacs versions 18 and earlier, this was the only way to find out the +terminal speed. +@end defun + +@defun send-string-to-terminal string +This function sends @var{string} to the terminal without alteration. +Control characters in @var{string} have terminal-dependent effects. + +One use of this function is to define function keys on terminals that +have downloadable function key definitions. For example, this is how on +certain terminals to define function key 4 to move forward four +characters (by transmitting the characters @kbd{C-u C-f} to the +computer): + +@example +@group +(send-string-to-terminal "\eF4\^U\^F") + @result{} nil +@end group +@end example +@end defun + +@deffn Command open-termscript filename +@cindex termscript file +This function is used to open a @dfn{termscript file} that will record +all the characters sent by Emacs to the terminal. It returns +@code{nil}. Termscript files are useful for investigating problems +where Emacs garbles the screen, problems that are due to incorrect +Termcap entries or to undesirable settings of terminal options more +often than to actual Emacs bugs. Once you are certain which characters +were actually output, you can determine reliably whether they correspond +to the Termcap specifications in use. + +See also @code{open-dribble-file} in @ref{Terminal Input}. + +@example +@group +(open-termscript "../junk/termscript") + @result{} nil +@end group +@end example +@end deffn + +@node Special Keysyms +@section System-Specific X11 Keysyms + +To define system-specific X11 keysyms, set the variable +@code{system-key-alist}. + +@defvar system-key-alist +This variable's value should be an alist with one element for each +system-specific keysym. An element has this form: @code{(@var{code} +. @var{symbol})}, where @var{code} is the numeric keysym code (not +including the ``vendor specific'' bit, 1 << 28), and @var{symbol} is the +name for the function key. + +For example @code{(168 . mute-acute)} defines a system-specific key used +by HP X servers whose numeric code is (1 << 28) + 168. + +It is not a problem if the alist defines keysyms for other X servers, as +long as they don't conflict with the ones used by the X server actually +in use. +@end defvar + +@node Flow Control +@section Flow Control +@cindex flow control characters + + This section attempts to answer the question ``Why does Emacs choose +to use flow-control characters in its command character set?'' For a +second view on this issue, read the comments on flow control in the +@file{emacs/INSTALL} file from the distribution; for help with Termcap +entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}. + +@cindex @kbd{C-s} +@cindex @kbd{C-q} + At one time, most terminals did not need flow control, and none used +@code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of +@kbd{C-s} and @kbd{C-q} as command characters was uncontroversial. +Emacs, for economy of keystrokes and portability, used nearly all the +@sc{ASCII} control characters, with mnemonic meanings when possible; +thus, @kbd{C-s} for search and @kbd{C-q} for quote. + + Later, some terminals were introduced which required these characters +for flow control. They were not very good terminals for full-screen +editing, so Emacs maintainers did not pay attention. In later years, +flow control with @kbd{C-s} and @kbd{C-q} became widespread among +terminals, but by this time it was usually an option. And the majority +of users, who can turn flow control off, were unwilling to switch to +less mnemonic key bindings for the sake of flow control. + + So which usage is ``right'', Emacs's or that of some terminal and +concentrator manufacturers? This question has no simple answer. + + One reason why we are reluctant to cater to the problems caused by +@kbd{C-s} and @kbd{C-q} is that they are gratuitous. There are other +techniques (albeit less common in practice) for flow control that +preserve transparency of the character stream. Note also that their use +for flow control is not an official standard. Interestingly, on the +model 33 teletype with a paper tape punch (which is very old), @kbd{C-s} +and @kbd{C-q} were sent by the computer to turn the punch on and off! + + GNU Emacs version 19 provides a convenient way of enabling flow +control if you want it: call the function @code{enable-flow-control}. + +@defun enable-flow-control +This function enables use of @kbd{C-s} and @kbd{C-q} for output flow +control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases +for them using @code{keyboard-translate-table} (@pxref{Translating Input}). +@end defun + +You can use the function @code{enable-flow-control-on} in your +@file{.emacs} file to enable flow control automatically on certain +terminal types. + +@defun enable-flow-control-on &rest termtypes +This function enables flow control, and the aliases @kbd{C-\} and @kbd{C-^}, +if the terminal type is one of @var{termtypes}. For example: + +@smallexample +(enable-flow-control-on "vt200" "vt300" "vt101" "vt131") +@end smallexample +@end defun + + Here is how @code{enable-flow-control} does its job: + +@enumerate +@item +@cindex @sc{cbreak} +It sets @sc{cbreak} mode for terminal input, and tells the operating +system to handle flow control, with @code{(set-input-mode nil t)}. + +@item +It sets up @code{keyboard-translate-table} to translate @kbd{C-\} and +@kbd{C-^} into @kbd{C-s} and @kbd{C-q} were typed. Except at its very +lowest level, Emacs never knows that the characters typed were anything +but @kbd{C-s} and @kbd{C-q}, so you can in effect type them as @kbd{C-\} +and @kbd{C-^} even when they are input for other commands. +@xref{Translating Input}. + +If the terminal is the source of the flow control characters, then once +you enable kernel flow control handling, you probably can make do with +less padding than normal for that terminal. You can reduce the amount +of padding by customizing the Termcap entry. You can also reduce it by +setting @code{baud-rate} to a smaller value so that Emacs uses a smaller +speed when calculating the padding needed. @xref{Terminal Output}. + +@node Batch Mode +@section Batch Mode +@cindex batch mode +@cindex noninteractive use + + The command line option @samp{-batch} causes Emacs to run +noninteractively. In this mode, Emacs does not read commands from the +terminal, it does not alter the terminal modes, and it does not expect +to be outputting to an erasable screen. The idea is that you specify +Lisp programs to run; when they are finished, Emacs should exit. The +way to specify the programs to run is with @samp{-l @var{file}}, which +loads the library named @var{file}, and @samp{-f @var{function}}, which +calls @var{function} with no arguments. + + Any Lisp program output that would normally go to the echo area, +either using @code{message} or using @code{prin1}, etc., with @code{t} +as the stream, goes instead to Emacs's standard output descriptor when +in batch mode. Thus, Emacs behaves much like a noninteractive +application program. (The echo area output that Emacs itself normally +generates, such as command echoing, is suppressed entirely.) + +@defvar noninteractive +This variable is non-@code{nil} when Emacs is running in batch mode. +@end defvar
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/processes.texi Mon Mar 28 20:21:44 1994 +0000 @@ -0,0 +1,1139 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/processes +@node Processes, System Interface, Abbrevs, Top +@chapter Processes +@cindex child process +@cindex parent process +@cindex subprocess +@cindex process + + In the terminology of operating systems, a @dfn{process} is a space in +which a program can execute. Emacs runs in a process. Emacs Lisp +programs can invoke other programs in processes of their own. These are +called @dfn{subprocesses} or @dfn{child processes} of the Emacs process, +which is their @dfn{parent process}. + + A subprocess of Emacs may be @dfn{synchronous} or @dfn{asynchronous}, +depending on how it is created. When you create a synchronous +subprocess, the Lisp program waits for the subprocess to terminate +before continuing execution. When you create an asynchronous +subprocess, it can run in parallel with the Lisp program. This kind of +subprocess is represented within Emacs by a Lisp object which is also +called a ``process''. Lisp programs can use this object to communicate +with the subprocess or to control it. For example, you can send +signals, obtain status information, receive output from the process, or +send input to it. + +@defun processp object +This function returns @code{t} if @var{object} is a process, +@code{nil} otherwise. +@end defun + +@menu +* Subprocess Creation:: Functions that start subprocesses. +* Synchronous Processes:: Details of using synchronous subprocesses. +* Asynchronous Processes:: Starting up an asynchronous subprocess. +* Deleting Processes:: Eliminating an asynchronous subprocess. +* Process Information:: Accessing run-status and other attributes. +* Input to Processes:: Sending input to an asynchronous subprocess. +* Signals to Processes:: Stopping, continuing or interrupting + an asynchronous subprocess. +* Output from Processes:: Collecting output from an asynchronous subprocess. +* Sentinels:: Sentinels run when process run-status changes. +* Transaction Queues:: Transaction-based communication with subprocesses. +* TCP:: Opening network connections. +@end menu + +@node Subprocess Creation +@section Functions that Create Subprocesses + + There are three functions that create a new subprocess in which to run +a program. One of them, @code{start-process}, creates an asynchronous +process and returns a process object (@pxref{Asynchronous Processes}). +The other two, @code{call-process} and @code{call-process-region}, +create a synchronous process and do not return a process object +(@pxref{Synchronous Processes}). + + Synchronous and asynchronous processes are explained in following +sections. Since the three functions are all called in a similar +fashion, their common arguments are described here. + +@cindex execute program +@cindex @code{PATH} environment variable +@cindex @code{HOME} environment variable + In all cases, the function's @var{program} argument specifies the +program to be run. An error is signaled if the file is not found or +cannot be executed. If the file name is relative, the variable +@code{exec-path} contains a list of directories to search. Emacs +initializes @code{exec-path} when it starts up, based on the value of +the environment variable @code{PATH}. The standard file name +constructs, @samp{~}, @samp{.}, and @samp{..}, are interpreted as usual +in @code{exec-path}, but environment variable substitutions +(@samp{$HOME}, etc.) are not recognized; use +@code{substitute-in-file-name} to perform them (@pxref{File Name +Expansion}). + + Each of the subprocess-creating functions has a @var{buffer-or-name} +argument which specifies where the standard output from the program will +go. If @var{buffer-or-name} is @code{nil}, that says to discard the +output unless a filter function handles it. (@xref{Filter Functions}, +and @ref{Streams}.) Normally, you should avoid having multiple +processes send output to the same buffer because their output would be +intermixed randomly. + +@cindex program arguments + All three of the subprocess-creating functions have a @code{&rest} +argument, @var{args}. The @var{args} must all be strings, and they are +supplied to @var{program} as separate command line arguments. Wildcard +characters and other shell constructs are not allowed in these strings, +since they are passed directly to the specified program. + + @strong{Please note:} the argument @var{program} contains only the +name of the program; it may not contain any command-line arguments. You +must use @var{args} to provide those. + + The subprocess gets its current directory from the value of +@code{default-directory} (@pxref{File Name Expansion}). + +@cindex environment variables, subprocesses + The subprocess inherits its environment from Emacs; but you can +specify overrides for it with @code{process-environment}. @xref{System +Environment}. + +@defvar exec-directory +@pindex wakeup +The value of this variable is the name of a directory (a string) that +contains programs that come with GNU Emacs, that are intended for Emacs +to invoke. The program @code{wakeup} is an example of such a program; +the @code{display-time} command uses it to get a reminder once per +minute. +@end defvar + +@defopt exec-path +The value of this variable is a list of directories to search for +programs to run in subprocesses. Each element is either the name of a +directory (i.e., a string), or @code{nil}, which stands for the default +directory (which is the value of @code{default-directory}). +@cindex program directories + +The value of @code{exec-path} is used by @code{call-process} and +@code{start-process} when the @var{program} argument is not an absolute +file name. +@end defopt + +@node Synchronous Processes +@section Creating a Synchronous Process +@cindex synchronous subprocess + + After a @dfn{synchronous process} is created, Emacs waits for the +process to terminate before continuing. Starting Dired is an example of +this: it runs @code{ls} in a synchronous process, then modifies the +output slightly. Because the process is synchronous, the entire +directory listing arrives in the buffer before Emacs tries to do +anything with it. + + While Emacs waits for the synchronous subprocess to terminate, the +user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill +the subprocess with a @code{SIGINT} signal; but it waits until the +subprocess actually terminates before quitting. If during that time the +user types another @kbd{C-g}, that kills the subprocess instantly with +@code{SIGKILL} and quits immediately. @xref{Quitting}. + + The synchronous subprocess functions returned @code{nil} in version +18. In version 19, they return an indication of how the process +terminated. + +@defun call-process program &optional infile buffer-or-name display &rest args +This function calls @var{program} in a separate process and waits for +it to finish. + +The standard input for the process comes from file @var{infile} if +@var{infile} is not @code{nil} and from @file{/dev/null} otherwise. The +process output gets inserted in buffer @var{buffer-or-name} before point, +if that argument names a buffer. If @var{buffer-or-name} is @code{t}, +output is sent to the current buffer; if @var{buffer-or-name} is +@code{nil}, output is discarded. + +If @var{buffer-or-name} is the integer 0, @code{call-process} returns +@code{nil} immediately and discards any output. In this case, the +process is not truly synchronous, since it can run in parallel with +Emacs; but you can think of it as synchronous in that Emacs is +essentially finished with the subprocess as soon as this function +returns. + +If @var{display} is non-@code{nil}, then @code{call-process} redisplays +the buffer as output is inserted. Otherwise the function does no +redisplay, and the results become visible on the screen only when Emacs +redisplays that buffer in the normal course of events. + +The remaining arguments, @var{args}, are strings that specify command +line arguments for the program. + +The value returned by @code{call-process} (unless you told it not to +wait) indicates the reason for process termination. A number gives the +exit status of the subprocess; 0 means success, and any other value +means failure. If the process terminated with a signal, +@code{call-process} returns a string describing the signal. + +In the examples below, the buffer @samp{foo} is current. + +@smallexample +@group +(call-process "pwd" nil t) + @result{} nil + +---------- Buffer: foo ---------- +/usr/user/lewis/manual +---------- Buffer: foo ---------- +@end group + +@group +(call-process "grep" nil "bar" nil "lewis" "/etc/passwd") + @result{} nil + +---------- Buffer: bar ---------- +lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh + +---------- Buffer: bar ---------- +@end group +@end smallexample + +The @code{insert-directory} function contains a good example of the use +of @code{call-process}: + +@smallexample +@group +(call-process insert-directory-program nil t nil switches + (if full-directory-p + (concat (file-name-as-directory file) ".") + file)) +@end group +@end smallexample +@end defun + +@defun call-process-region start end program &optional delete buffer-or-name display &rest args +This function sends the text between @var{start} to @var{end} as +standard input to a process running @var{program}. It deletes the text +sent if @var{delete} is non-@code{nil}; this is useful when @var{buffer} +is @code{t}, to insert the output in the current buffer. + +The arguments @var{buffer-or-name} and @var{display} control what to do +with the output from the subprocess, and whether to update the display +as it comes in. For details, see the description of +@code{call-process}, above. If @var{buffer-or-name} is the integer 0, +@code{call-process-region} discards the output and returns @code{nil} +immediately, without waiting for the subprocess to finish. + +The remaining arguments, @var{args}, are strings that specify command +line arguments for the program. + +The return value of @code{call-process-region} is just like that of +@code{call-process}: @code{nil} if you told it to return without +waiting; otherwise, a number or string which indicates how the +subprocess terminated. + +In the following example, we use @code{call-process-region} to run the +@code{cat} utility, with standard input being the first five characters +in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its +standard input into its standard output. Since the argument +@var{buffer-or-name} is @code{t}, this output is inserted in the current +buffer. + +@smallexample +@group +---------- Buffer: foo ---------- +input@point{} +---------- Buffer: foo ---------- +@end group + +@group +(call-process-region 1 6 "cat" nil t) + @result{} nil + +---------- Buffer: foo ---------- +inputinput@point{} +---------- Buffer: foo ---------- +@end group +@end smallexample + + The @code{shell-command-on-region} command uses +@code{call-process-region} like this: + +@smallexample +@group +(call-process-region + start end + shell-file-name ; @r{Name of program.} + nil ; @r{Do not delete region.} + buffer ; @r{Send output to @code{buffer}.} + nil ; @r{No redisplay during output.} + "-c" command) ; @r{Arguments for the shell.} +@end group +@end smallexample +@end defun + +@node Asynchronous Processes +@section Creating an Asynchronous Process +@cindex asynchronous subprocess + + After an @dfn{asynchronous process} is created, Emacs and the Lisp +program both continue running immediately. The process may thereafter +run in parallel with Emacs, and the two may communicate with each other +using the functions described in following sections. Here we describe +how to create an asynchronous process with @code{start-process}. + +@defun start-process name buffer-or-name program &rest args +This function creates a new asynchronous subprocess and starts the +program @var{program} running in it. It returns a process object that +stands for the new subprocess in Lisp. The argument @var{name} +specifies the name for the process object; if a process with this name +already exists, then @var{name} is modified (by adding @samp{<1>}, etc.) +to be unique. The buffer @var{buffer-or-name} is the buffer to +associate with the process. + +The remaining arguments, @var{args}, are strings that specify command +line arguments for the program. + +In the example below, the first process is started and runs (rather, +sleeps) for 100 seconds. Meanwhile, the second process is started, and +given the name @samp{my-process<1>} for the sake of uniqueness. It +inserts the directory listing at the end of the buffer @samp{foo}, +before the first process finishes. Then it finishes, and a message to +that effect is inserted in the buffer. Much later, the first process +finishes, and another message is inserted in the buffer for it. + +@smallexample +@group +(start-process "my-process" "foo" "sleep" "100") + @result{} #<process my-process> +@end group + +@group +(start-process "my-process" "foo" "ls" "-l" "/user/lewis/bin") + @result{} #<process my-process<1>> + +---------- Buffer: foo ---------- +total 2 +lrwxrwxrwx 1 lewis 14 Jul 22 10:12 gnuemacs --> /emacs +-rwxrwxrwx 1 lewis 19 Jul 30 21:02 lemon + +Process my-process<1> finished + +Process my-process finished +---------- Buffer: foo ---------- +@end group +@end smallexample +@end defun + +@defun start-process-shell-command name buffer-or-name command &rest command-args +This function is like @code{start-process} except that it uses a shell +to execute the specified command. The argument @var{command} is a shell +command name, and @var{command-args} are the arguments for the shell +command. +@end defun + +@defvar process-connection-type +@cindex pipes +@cindex @sc{pty}s +This variable controls the type of device used to communicate with +asynchronous subprocesses. If it is @code{nil}, then pipes are used. +If it is @code{t}, then @sc{pty}s are used (or pipes if @sc{pty}s are +not supported). + +@sc{pty}s are usually preferable for processes visible to the user, as +in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z}, +etc.) to work between the process and its children whereas pipes do not. +For subprocesses used for internal purposes by programs, it is often +better to use a pipe, because they are more efficient. In addition, the +total number of @sc{pty}s is limited on many systems and it is good not +to waste them. + +The value @code{process-connection-type} is used when +@code{start-process} is called. So you can specify how to communicate +with one subprocess by binding the variable around the call to +@code{start-process}. + +@smallexample +@group +(let ((process-connection-type nil)) ; @r{Use a pipe.} + (start-process @dots{})) +@end group +@end smallexample +@end defvar + +@node Deleting Processes +@section Deleting Processes +@cindex deleting processes + + @dfn{Deleting a process} disconnects Emacs immediately from the +subprocess, and removes it from the list of active processes. It sends +a signal to the subprocess to make the subprocess terminate, but this is +not guaranteed to happen immediately. The process object itself +continues to exist as long as other Lisp objects point to it. + + You can delete a process explicitly at any time. Processes are +deleted automatically after they terminate, but not necessarily right +away. If you delete a terminated process explicitly before it is +deleted automatically, no harm results. + +@defvar delete-exited-processes +This variable controls automatic deletion of processes that have +terminated (due to calling @code{exit} or to a signal). If it is +@code{nil}, then they continue to exist until the user runs +@code{list-processes}. Otherwise, they are deleted immediately after +they exit. +@end defvar + +@defun delete-process name +This function deletes the process associated with @var{name}, killing it +with a @code{SIGHUP} signal. The argument @var{name} may be a process, +the name of a process, a buffer, or the name of a buffer. + +@smallexample +@group +(delete-process "*shell*") + @result{} nil +@end group +@end smallexample +@end defun + +@defun process-kill-without-query process +This function declares that Emacs need not query the user if +@var{process} is still running when Emacs is exited. The process will +be deleted silently. The value is @code{t}. + +@smallexample +@group +(process-kill-without-query (get-process "shell")) + @result{} t +@end group +@end smallexample +@end defun + +@node Process Information +@section Process Information + + Several functions return information about processes. +@code{list-processes} is provided for interactive use. + +@deffn Command list-processes +This command displays a listing of all living processes. In addition, +it finally deletes any process whose status was @samp{Exited} or +@samp{Signaled}. It returns @code{nil}. +@end deffn + +@defun process-list +This function returns a list of all processes that have not been deleted. + +@smallexample +@group +(process-list) + @result{} (#<process display-time> #<process shell>) +@end group +@end smallexample +@end defun + +@defun get-process name +This function returns the process named @var{name}, or @code{nil} if +there is none. An error is signaled if @var{name} is not a string. + +@smallexample +@group +(get-process "shell") + @result{} #<process shell> +@end group +@end smallexample +@end defun + +@defun process-command process +This function returns the command that was executed to start +@var{process}. This is a list of strings, the first string being the +program executed and the rest of the strings being the arguments that +were given to the program. + +@smallexample +@group +(process-command (get-process "shell")) + @result{} ("/bin/csh" "-i") +@end group +@end smallexample +@end defun + +@defun process-id process +This function returns the @sc{pid} of @var{process}. This is an +integer which distinguishes the process @var{process} from all other +processes running on the same computer at the current time. The +@sc{pid} of a process is chosen by the operating system kernel when the +process is started and remains constant as long as the process exists. +@end defun + +@defun process-name process +This function returns the name of @var{process}. +@end defun + +@defun process-status process-name +This function returns the status of @var{process-name} as a symbol. +The argument @var{process-name} must be a process, a buffer, a +process name (string) or a buffer name (string). + +The possible values for an actual subprocess are: + +@table @code +@item run +for a process that is running. +@item stop +for a process that is stopped but continuable. +@item exit +for a process that has exited. +@item signal +for a process that has received a fatal signal. +@item open +for a network connection that is open. +@item closed +for a network connection that is closed. Once a connection +is closed, you cannot reopen it, though you might be able to open +a new connection to the same place. +@item nil +if @var{process-name} is not the name of an existing process. +@end table + +@smallexample +@group +(process-status "shell") + @result{} run +@end group +@group +(process-status (get-buffer "*shell*")) + @result{} run +@end group +@group +x + @result{} #<process xx<1>> +(process-status x) + @result{} exit +@end group +@end smallexample + +For a network connection, @code{process-status} returns one of the symbols +@code{open} or @code{closed}. The latter means that the other side +closed the connection, or Emacs did @code{delete-process}. + +In earlier Emacs versions (prior to version 19), the status of a network +connection was @code{run} if open, and @code{exit} if closed. +@end defun + +@defun process-exit-status process +This function returns the exit status of @var{process} or the signal +number that killed it. (Use the result of @code{process-status} to +determine which of those it is.) If @var{process} has not yet +terminated, the value is 0. +@end defun + +@node Input to Processes +@section Sending Input to Processes +@cindex process input + + Asynchronous subprocesses receive input when it is sent to them by +Emacs, which is done with the functions in this section. You must +specify the process to send input to, and the input data to send. The +data appears on the ``standard input'' of the subprocess. + + Some operating systems have limited space for buffered input in a +@sc{pty}. On these systems, Emacs sends an @sc{eof} periodically amidst +the other characters, to force them through. For most programs, +these @sc{eof}s do no harm. + +@defun process-send-string process-name string +This function sends @var{process-name} the contents of @var{string} as +standard input. The argument @var{process-name} must be a process or +the name of a process. If it is @code{nil}, the current buffer's +process is used. + + The function returns @code{nil}. + +@smallexample +@group +(process-send-string "shell<1>" "ls\n") + @result{} nil +@end group + + +@group +---------- Buffer: *shell* ---------- +... +introduction.texi syntax-tables.texi~ +introduction.texi~ text.texi +introduction.txt text.texi~ +... +---------- Buffer: *shell* ---------- +@end group +@end smallexample +@end defun + +@deffn Command process-send-region process-name start end +This function sends the text in the region defined by @var{start} and +@var{end} as standard input to @var{process-name}, which is a process or +a process name. (If it is @code{nil}, the current buffer's process is +used.) + +An error is signaled unless both @var{start} and @var{end} are +integers or markers that indicate positions in the current buffer. (It +is unimportant which number is larger.) +@end deffn + +@defun process-send-eof &optional process-name + This function makes @var{process-name} see an end-of-file in its +input. The @sc{eof} comes after any text already sent to it. + + If @var{process-name} is not supplied, or if it is @code{nil}, then +this function sends the @sc{eof} to the current buffer's process. An +error is signaled if the current buffer has no process. + + The function returns @var{process-name}. + +@smallexample +@group +(process-send-eof "shell") + @result{} "shell" +@end group +@end smallexample +@end defun + +@node Signals to Processes +@section Sending Signals to Processes +@cindex process signals +@cindex sending signals +@cindex signals + + @dfn{Sending a signal} to a subprocess is a way of interrupting its +activities. There are several different signals, each with its own +meaning. The set of signals and their names is defined by the operating +system. For example, the signal @code{SIGINT} means that the user has +typed @kbd{C-c}, or that some analogous thing has happened. + + Each signal has a standard effect on the subprocess. Most signals +kill the subprocess, but some stop or resume execution instead. Most +signals can optionally be handled by programs; if the program handles +the signal, then we can say nothing in general about its effects. + + You can send signals explicitly by calling the functions in this +section. Emacs also sends signals automatically at certain times: +killing a buffer sends a @code{SIGHUP} signal to all its associated +processes; killing Emacs sends a @code{SIGHUP} signal to all remaining +processes. (@code{SIGHUP} is a signal that usually indicates that the +user hung up the phone.) + + Each of the signal-sending functions takes two optional arguments: +@var{process-name} and @var{current-group}. + + The argument @var{process-name} must be either a process, the name of +one, or @code{nil}. If it is @code{nil}, the process defaults to the +process associated with the current buffer. An error is signaled if +@var{process-name} does not identify a process. + + The argument @var{current-group} is a flag that makes a difference +when you are running a job-control shell as an Emacs subprocess. If it +is non-@code{nil}, then the signal is sent to the current process-group +of the terminal which Emacs uses to communicate with the subprocess. If +the process is a job-control shell, this means the shell's current +subjob. If it is @code{nil}, the signal is sent to the process group of +the immediate subprocess of Emacs. If the subprocess is a job-control +shell, this is the shell itself. + + The flag @var{current-group} has no effect when a pipe is used to +communicate with the subprocess, because the operating system does not +support the distinction in the case of pipes. For the same reason, +job-control shells won't work when a pipe is used. See +@code{process-connection-type} in @ref{Asynchronous Processes}. + +@defun interrupt-process &optional process-name current-group +This function interrupts the process @var{process-name} by sending the +signal @code{SIGINT}. Outside of Emacs, typing the ``interrupt +character'' (normally @kbd{C-c} on some systems, and @code{DEL} on +others) sends this signal. When the argument @var{current-group} is +non-@code{nil}, you can think of this function as ``typing @kbd{C-c}'' +on the terminal by which Emacs talks to the subprocess. +@end defun + +@defun kill-process &optional process-name current-group +This function kills the process @var{process-name} by sending the +signal @code{SIGKILL}. This signal kills the subprocess immediately, +and cannot be handled by the subprocess. +@end defun + +@defun quit-process &optional process-name current-group +This function sends the signal @code{SIGQUIT} to the process +@var{process-name}. This signal is the one sent by the ``quit +character'' (usually @kbd{C-b} or @kbd{C-\}) when you are not inside +Emacs. +@end defun + +@defun stop-process &optional process-name current-group +This function stops the process @var{process-name} by sending the +signal @code{SIGTSTP}. Use @code{continue-process} to resume its +execution. + +On systems with job control, the ``stop character'' (usually @kbd{C-z}) +sends this signal (outside of Emacs). When @var{current-group} is +non-@code{nil}, you can think of this function as ``typing @kbd{C-z}'' +on the terminal Emacs uses to communicate with the subprocess. +@end defun + +@defun continue-process &optional process-name current-group +This function resumes execution of the process @var{process} by sending +it the signal @code{SIGCONT}. This presumes that @var{process-name} was +stopped previously. +@end defun + +@c Emacs 19 feature +@defun signal-process pid signal +This function sends a signal to process @var{pid}, which need not be +a child of Emacs. The argument @var{signal} specifies which signal +to send; it should be an integer. +@end defun + +@node Output from Processes +@section Receiving Output from Processes +@cindex process output +@cindex output from processes + + There are two ways to receive the output that a subprocess writes to +its standard output stream. The output can be inserted in a buffer, +which is called the associated buffer of the process, or a function +called the @dfn{filter function} can be called to act on the output. + +@menu +* Process Buffers:: If no filter, output is put in a buffer. +* Filter Functions:: Filter functions accept output from the process. +* Accepting Output:: Explicitly permitting subprocess output. + Waiting for subprocess output. +@end menu + +@node Process Buffers +@subsection Process Buffers + + A process can (and usually does) have an @dfn{associated buffer}, +which is an ordinary Emacs buffer that is used for two purposes: storing +the output from the process, and deciding when to kill the process. You +can also use the buffer to identify a process to operate on, since in +normal practice only one process is associated with any given buffer. +Many applications of processes also use the buffer for editing input to +be sent to the process, but this is not built into Emacs Lisp. + + Unless the process has a filter function (@pxref{Filter Functions}), +its output is inserted in the associated buffer. The position to insert +the output is determined by the @code{process-mark} (@pxref{Process +Information}), which is then updated to point to the end of the text +just inserted. Usually, but not always, the @code{process-mark} is at +the end of the buffer. If the process has no buffer and no filter +function, its output is discarded. + +@defun process-buffer process +This function returns the associated buffer of the process +@var{process}. + +@smallexample +@group +(process-buffer (get-process "shell")) + @result{} #<buffer *shell*> +@end group +@end smallexample +@end defun + +@defun process-mark process +This function returns the process marker for @var{process}, which is the +marker that says where to insert output from the process. + +If @var{process} does not have a buffer, @code{process-mark} returns a +marker that points nowhere. + +Insertion of process output in a buffer uses this marker to decide where +to insert, and updates it to point after the inserted text. That is why +successive batches of output are inserted consecutively. + +Filter functions normally should use this marker in the same fashion +as is done by direct insertion of output in the buffer. A good +example of a filter function that uses @code{process-mark} is found at +the end of the following section. + +When the user is expected to enter input in the process buffer for +transmission to the process, the process marker is useful for +distinguishing the new input from previous output. +@end defun + +@defun set-process-buffer process buffer +This function sets the buffer associated with @var{process} to +@var{buffer}. If @var{buffer} is @code{nil}, the process becomes +associated with no buffer. +@end defun + +@defun get-buffer-process buffer-or-name +This function returns the process associated with @var{buffer-or-name}. +If there are several processes associated with it, then one is chosen. +(Presently, the one chosen is the one most recently created.) It is +usually a bad idea to have more than one process associated with the +same buffer. + +@smallexample +@group +(get-buffer-process "*shell*") + @result{} #<process shell> +@end group +@end smallexample + +Killing the process's buffer deletes the process, which kills the +subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}). +@end defun + +@node Filter Functions +@subsection Process Filter Functions +@cindex filter function +@cindex process filter + + A process @dfn{filter function} is a function that receives the +standard output from the associated process. If a process has a filter, +then @emph{all} output from that process, that would otherwise have been +in a buffer, is passed to the filter. The process buffer is used +directly for output from the process only when there is no filter. + + A filter function must accept two arguments: the associated process and +a string, which is the output. The function is then free to do whatever it +chooses with the output. + + A filter function runs only while Emacs is waiting (e.g., for terminal +input, or for time to elapse, or for process output). This avoids the +timing errors that could result from running filters at random places in +the middle of other Lisp programs. You may explicitly cause Emacs to +wait, so that filter functions will run, by calling @code{sit-for}, +@code{sleep-for} or @code{accept-process-output} (@pxref{Accepting +Output}). Emacs is also waiting when the command loop is reading input. + + Quitting is normally inhibited within a filter function---otherwise, +the effect of typing @kbd{C-g} at command level or to quit a user +command would be unpredictable. If you want to permit quitting inside a +filter function, bind @code{inhibit-quit} to @code{nil}. +@xref{Quitting}. + + Many filter functions sometimes or always insert the text in the +process's buffer, mimicking the actions of Emacs when there is no +filter. Such filter functions need to use @code{set-buffer} in order to +be sure to insert in that buffer. To avoid setting the current buffer +semipermanently, these filter functions must use @code{unwind-protect} +to make sure to restore the previous current buffer. They should also +update the process marker, and in some cases update the value of point. +Here is how to do these things: + +@smallexample +@group +(defun ordinary-insertion-filter (proc string) + (let ((old-buffer (current-buffer))) + (unwind-protect + (let (moving) + (set-buffer (process-buffer proc)) + (setq moving (= (point) (process-mark proc))) +@end group +@group + (save-excursion + ;; @r{Insert the text, moving the process-marker.} + (goto-char (process-mark proc)) + (insert string) + (set-marker (process-mark proc) (point))) + (if moving (goto-char (process-mark proc)))) + (set-buffer old-buffer)))) +@end group +@end smallexample + +@noindent +The reason to use an explicit @code{unwind-protect} rather than letting +@code{save-excursion} restore the current buffer is so as to preserve +the change in point made by @code{goto-char}. + + To make the filter force the process buffer to be visible whenever new +text arrives, insert the following line just before the +@code{unwind-protect}: + +@smallexample +(display-buffer (process-buffer proc)) +@end smallexample + + To force point to move to the end of the new output no matter where +it was previously, eliminate the variable @code{moving} and call +@code{goto-char} unconditionally. + + All filter functions that do regexp searching or matching should save +and restore the match data. Otherwise, a filter function that runs +during a call to @code{sit-for} might clobber the match data of the +program that called @code{sit-for}. @xref{Match Data}. + + A filter function that writes the output into the buffer of the +process should check whether the process is still alive. If it tries to +insert into a dead buffer, it will get an error. If the buffer is dead, +@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. + + The output to the function may come in chunks of any size. A program +that produces the same output twice in a row may send it as one batch +of 200 characters one time, and five batches of 40 characters the next. + +@defun set-process-filter process filter +This function gives @var{process} the filter function @var{filter}. If +@var{filter} is @code{nil}, it gives the process no filter. +@end defun + +@defun process-filter process +This function returns the filter function of @var{process}, or @code{nil} +if it has none. +@end defun + + Here is an example of use of a filter function: + +@smallexample +@group +(defun keep-output (process output) + (setq kept (cons output kept))) + @result{} keep-output +@end group +@group +(setq kept nil) + @result{} nil +@end group +@group +(set-process-filter (get-process "shell") 'keep-output) + @result{} keep-output +@end group +@group +(process-send-string "shell" "ls ~/other\n") + @result{} nil +kept + @result{} ("lewis@@slug[8] % " +@end group +@group +"FINAL-W87-SHORT.MSS backup.otl kolstad.mss~ +address.txt backup.psf kolstad.psf +backup.bib~ david.mss resume-Dec-86.mss~ +backup.err david.psf resume-Dec.psf +backup.mss dland syllabus.mss +" +"#backups.mss# backup.mss~ kolstad.mss +") +@end group +@end smallexample + +@ignore @c The code in this example doesn't show the right way to do things. +Here is another, more realistic example, which demonstrates how to use +the process mark to do insertion in the same fashion as is done when +there is no filter function: + +@smallexample +@group +;; @r{Insert input in the buffer specified by @code{my-shell-buffer}} +;; @r{and make sure that buffer is shown in some window.} +(defun my-process-filter (proc str) + (let ((cur (selected-window)) + (pop-up-windows t)) + (pop-to-buffer my-shell-buffer) +@end group +@group + (goto-char (point-max)) + (insert str) + (set-marker (process-mark proc) (point-max)) + (select-window cur))) +@end group +@end smallexample +@end ignore + +@node Accepting Output +@subsection Accepting Output from Processes + + Output from asynchronous subprocesses normally arrives only while +Emacs is waiting for some sort of external event, such as elapsed time +or terminal input. Occasionally it is useful in a Lisp program to +explicitly permit output to arrive at a specific point, or even to wait +until output arrives from a process. + +@defun accept-process-output &optional process seconds millisec +This function allows Emacs to read pending output from processes. The +output is inserted in the associated buffers or given to their filter +functions. If @var{process} is non-@code{nil} then this function does +not return until some output has been received from @var{process}. + +@c Emacs 19 feature +The arguments @var{seconds} and @var{millisec} let you specify timeout +periods. The former specifies a period measured in seconds and the +latter specifies one measured in milliseconds. The two time periods +thus specified are added together, and @code{accept-process-output} +returns after that much time whether or not there has been any +subprocess output. + +Not all operating systems support waiting periods other than multiples +of a second; on those that do not, you get an error if you specify +nonzero @var{millisec}. + +The function @code{accept-process-output} returns non-@code{nil} if it +did get some output, or @code{nil} if the timeout expired before output +arrived. +@end defun + +@node Sentinels +@section Sentinels: Detecting Process Status Changes +@cindex process sentinel +@cindex sentinel + + A @dfn{process sentinel} is a function that is called whenever the +associated process changes status for any reason, including signals +(whether sent by Emacs or caused by the process's own actions) that +terminate, stop, or continue the process. The process sentinel is also +called if the process exits. The sentinel receives two arguments: the +process for which the event occurred, and a string describing the type +of event. + + The string describing the event looks like one of the following: + +@itemize @bullet +@item +@code{"finished\n"}. + +@item +@code{"exited abnormally with code @var{exitcode}\n"}. + +@item +@code{"@var{name-of-signal}\n"}. + +@item +@code{"@var{name-of-signal} (core dumped)\n"}. +@end itemize + + A sentinel runs only while Emacs is waiting (e.g., for terminal input, +or for time to elapse, or for process output). This avoids the timing +errors that could result from running them at random places in the +middle of other Lisp programs. A program can wait, so that sentinels +will run, by calling @code{sit-for}, @code{sleep-for} or +@code{accept-process-output} (@pxref{Accepting Output}). Emacs is also +waiting when the command loop is reading input. + + Quitting is normally inhibited within a sentinel---otherwise, the +effect of typing @kbd{C-g} at command level or to quit a user command +would be unpredictable. If you want to permit quitting inside a +sentinel, bind @code{inhibit-quit} to @code{nil}. @xref{Quitting}. + + A sentinel that writes the output into the buffer of the process +should check whether the process is still alive. If it tries to insert +into a dead buffer, it will get an error. If the buffer is dead, +@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}. + + All sentinels that do regexp searching or matching should save and +restore the match data. Otherwise, a sentinel that runs during a call +to @code{sit-for} might clobber the match data of the program that +called @code{sit-for}. @xref{Match Data}. + +@defun set-process-sentinel process sentinel +This function associates @var{sentinel} with @var{process}. If +@var{sentinel} is @code{nil}, then the process will have no sentinel. +The default behavior when there is no sentinel is to insert a message in +the process's buffer when the process status changes. + +@smallexample +@group +(defun msg-me (process event) + (princ + (format "Process: %s had the event `%s'" process event))) +(set-process-sentinel (get-process "shell") 'msg-me) + @result{} msg-me +@end group +@group +(kill-process (get-process "shell")) + @print{} Process: #<process shell> had the event `killed' + @result{} #<process shell> +@end group +@end smallexample +@end defun + +@defun process-sentinel process +This function returns the sentinel of @var{process}, or @code{nil} if it +has none. +@end defun + +@defun waiting-for-user-input-p +While a sentinel or filter function is running, this function returns +non-@code{nil} if Emacs was waiting for keyboard input from the user at +the time the sentinel or filter function was called, @code{nil} if it +was not. +@end defun + +@node Transaction Queues +@section Transaction Queues +@cindex transaction queue + +You can use a @dfn{transaction queue} for more convenient communication +with subprocesses using transactions. First use @code{tq-create} to +create a transaction queue communicating with a specified process. Then +you can call @code{tq-enqueue} to send a transaction. + +@defun tq-create process +This function creates and returns a transaction queue communicating with +@var{process}. The argument @var{process} should be a subprocess +capable of sending and receiving streams of bytes. It may be a child +process, or it may be a TCP connection to a server possibly on another +machine. +@end defun + +@defun tq-enqueue queue question regexp closure fn +This function sends a transaction to queue @var{queue}. Specifying the +queue has the effect of specifying the subprocess to talk to. + +The argument @var{question} is the outgoing message which starts the +transaction. The argument @var{fn} is the function to call when the +corresponding answer comes back; it is called with two arguments: +@var{closure}, and the answer received. + +The argument @var{regexp} is a regular expression that should match the +entire answer, but nothing less; that's how @code{tq-enqueue} determines +where the answer ends. + +The return value of @code{tq-enqueue} itself is not meaningful. +@end defun + +@defun tq-close queue +Shut down transaction queue @var{queue}, waiting for all pending transactions +to complete, and then terminate the connection or child process. +@end defun + +Transaction queues are implemented by means of a filter function. +@xref{Filter Functions}. + +@node TCP +@section TCP +@cindex TCP + + Emacs Lisp programs can open TCP connections to other processes on the +same machine or other machines. A network connection is handled by Lisp +much like a subprocess, and is represented by a process object. +However, the process you are communicating with is not a child of the +Emacs process, so you can't kill it or send it signals. All you can do +is send and receive data. @code{delete-process} closes the connection, +but does not kill the process at the other end; that process must decide +what to do about closure of the connection. + + You can distinguish process objects representing network connections +from those representing subprocesses with the @code{process-status} +function. @xref{Process Information}. + +@defun open-network-stream name buffer-or-name host service +This function opens a TCP connection for a service to a host. It +returns a process object to represent the connection. + +The @var{name} argument specifies the name for the process object. It +is modified as necessary to make it unique. + +The @var{buffer-or-name} argument is the buffer to associate with the +connection. Output from the connection is inserted in the buffer, +unless you specify a filter function to handle the output. If +@var{buffer-or-name} is @code{nil}, it means that the connection is not +associated with any buffer. + +The arguments @var{host} and @var{service} specify where to connect to; +@var{host} is the host name (a string), and @var{service} is the name of +a defined network service (a string) or a port number (an integer). +@end defun
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/text.texi Mon Mar 28 20:21:44 1994 +0000 @@ -0,0 +1,2658 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/text +@node Text, Searching and Matching, Markers, Top +@chapter Text +@cindex text + + This chapter describes the functions that deal with the text in a +buffer. Most examine, insert or delete text in the current buffer, +often in the vicinity of point. Many are interactive. All the +functions that change the text provide for undoing the changes +(@pxref{Undo}). + + Many text-related functions operate on a region of text defined by two +buffer positions passed in arguments named @var{start} and @var{end}. +These arguments should be either markers (@pxref{Markers}) or numeric +character positions (@pxref{Positions}). The order of these arguments +does not matter; it is all right for @var{start} to be the end of the +region and @var{end} the beginning. For example, @code{(delete-region 1 +10)} and @code{(delete-region 10 1)} are equivalent. An +@code{args-out-of-range} error is signaled if either @var{start} or +@var{end} is outside the accessible portion of the buffer. In an +interactive call, point and the mark are used for these arguments. + +@cindex buffer contents + Throughout this chapter, ``text'' refers to the characters in the +buffer. + +@menu +* Near Point:: Examining text in the vicinity of point. +* Buffer Contents:: Examining text in a general fashion. +* Comparing Text:: Comparing substrings of buffers. +* Insertion:: Adding new text to a buffer. +* Commands for Insertion:: User-level commands to insert text. +* Deletion:: Removing text from a buffer. +* User-Level Deletion:: User-level commands to delete text. +* The Kill Ring:: Where removed text sometimes is saved for later use. +* Undo:: Undoing changes to the text of a buffer. +* Maintaining Undo:: How to enable and disable undo information. + How to control how much information is kept. +* Filling:: Functions for explicit filling. +* Auto Filling:: How auto-fill mode is implemented to break lines. +* Sorting:: Functions for sorting parts of the buffer. +* Columns:: Computing horizontal positions, and using them. +* Indentation:: Functions to insert or adjust indentation. +* Case Changes:: Case conversion of parts of the buffer. +* Text Properties:: Assigning Lisp property lists to text characters. +* Substitution:: Replacing a given character wherever it appears. +* Registers:: How registers are implemented. Accessing the text or + position stored in a register. +* Change Hooks:: Supplying functions to be run when text is changed. +@end menu + +@node Near Point +@section Examining Text Near Point + + Many functions are provided to look at the characters around point. +Several simple functions are described here. See also @code{looking-at} +in @ref{Regexp Search}. + +@defun char-after position +This function returns the character in the current buffer at (i.e., +immediately after) position @var{position}. If @var{position} is out of +range for this purpose, either before the beginning of the buffer, or at +or beyond the end, then the value is @code{nil}. + +In the following example, assume that the first character in the +buffer is @samp{@@}: + +@example +@group +(char-to-string (char-after 1)) + @result{} "@@" +@end group +@end example +@end defun + +@defun following-char +This function returns the character following point in the current +buffer. This is similar to @code{(char-after (point))}. However, if +point is at the end of the buffer, then @code{following-char} returns 0. + +Remember that point is always between characters, and the terminal +cursor normally appears over the character following point. Therefore, +the character returned by @code{following-char} is the character the +cursor is over. + +In this example, point is between the @samp{a} and the @samp{c}. + +@example +@group +---------- Buffer: foo ---------- +Gentlemen may cry ``Pea@point{}ce! Peace!,'' +but there is no peace. +---------- Buffer: foo ---------- +@end group + +@group +(char-to-string (preceding-char)) + @result{} "a" +(char-to-string (following-char)) + @result{} "c" +@end group +@end example +@end defun + +@defun preceding-char +This function returns the character preceding point in the current +buffer. See above, under @code{following-char}, for an example. If +point is at the beginning of the buffer, @code{preceding-char} returns +0. +@end defun + +@defun bobp +This function returns @code{t} if point is at the beginning of the +buffer. If narrowing is in effect, this means the beginning of the +accessible portion of the text. See also @code{point-min} in +@ref{Point}. +@end defun + +@defun eobp +This function returns @code{t} if point is at the end of the buffer. +If narrowing is in effect, this means the end of accessible portion of +the text. See also @code{point-max} in @xref{Point}. +@end defun + +@defun bolp +This function returns @code{t} if point is at the beginning of a line. +@xref{Text Lines}. The beginning of the buffer (or its accessible +portion always counts as the beginning of a line. +@end defun + +@defun eolp +This function returns @code{t} if point is at the end of a line. The +end of the buffer (or of its accessible portion) is always considered +the end of a line. +@end defun + +@node Buffer Contents +@section Examining Buffer Contents + + This section describes two functions that allow a Lisp program to +convert any portion of the text in the buffer into a string. + +@defun buffer-substring start end +This function returns a string containing a copy of the text of the +region defined by positions @var{start} and @var{end} in the current +buffer. If the arguments are not positions in the accessible portion of +the buffer, @code{buffer-substring} signals an @code{args-out-of-range} +error. + +It is not necessary for @var{start} to be less than @var{end}; the +arguments can be given in either order. But most often the smaller +argument is written first. + +@example +@group +---------- Buffer: foo ---------- +This is the contents of buffer foo + +---------- Buffer: foo ---------- +@end group + +@group +(buffer-substring 1 10) +@result{} "This is t" +@end group +@group +(buffer-substring (point-max) 10) +@result{} "he contents of buffer foo +" +@end group +@end example +@end defun + +@defun buffer-string +This function returns the contents of the accessible portion of the +current buffer as a string. This is the portion between +@code{(point-min)} and @code{(point-max)} (@pxref{Narrowing}). + +@example +@group +---------- Buffer: foo ---------- +This is the contents of buffer foo + +---------- Buffer: foo ---------- + +(buffer-string) + @result{} "This is the contents of buffer foo +" +@end group +@end example +@end defun + +@node Comparing Text +@section Comparing Text +@cindex comparing buffer text + + This function lets you compare portions of the text in a buffer, without +copying them into strings first. + +@defun compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2 +This function lets you compare two substrings of the same buffer or two +different buffers. The first three arguments specify one substring, +giving a buffer and two positions within the buffer. The last three +arguments specify the other substring in the same way. You can use +@code{nil} for @var{buffer1}, @var{buffer2} or both to stand for the +current buffer. + +The value is negative if the first substring is less, positive if the +first is greater, and zero if they are equal. The absolute value of +the result is one plus the index of the first differing characters +within the substrings. + +This function ignores case when comparing characters +if @code{case-fold-search} is non-@code{nil}. + +Suppose the current buffer contains the text @samp{foobarbar +haha!rara!}; then in this example the two substrings are @samp{rbar } +and @samp{rara!}. The value is 2 because the first substring is greater +at the second character. + +@example +(compare-buffer-substring nil 6 11 nil 16 21) + @result{} 2 +@end example + +This function does not exist in Emacs version 18 and earlier. +@end defun + +@node Insertion +@section Insertion +@cindex insertion of text +@cindex text insertion + + @dfn{Insertion} means adding new text to a buffer. The inserted text +goes at point---between the character before point and the character +after point. + + Insertion relocates markers that point at positions after the +insertion point, so that they stay with the surrounding text +(@pxref{Markers}). When a marker points at the place of insertion, +insertion normally doesn't relocate the marker, so that it points to the +beginning of the inserted text; however, certain special functions such +as @code{insert-before-markers} relocate such markers to point after the +inserted text. + +@cindex insertion before point +@cindex before point, insertion + Some insertion functions leave point before the inserted text, while +other functions leave it after. We call the latter insertion +@dfn{before point}. + + Insertion functions signal an error if the current buffer is +read-only. + +@defun insert &rest args +This function inserts the strings and/or characters @var{args} into the +current buffer, at point, moving point forward. An error is signaled +unless all @var{args} are either strings or characters. The value is +@code{nil}. +@end defun + +@defun insert-before-markers &rest args +This function inserts the strings and/or characters @var{args} into the +current buffer, at point, moving point forward. An error is signaled +unless all @var{args} are either strings or characters. The value is +@code{nil}. + +This function is unlike the other insertion functions in that it +relocates markers initially pointing at the insertion point, to point +after the inserted text. +@end defun + +@defun insert-char character count +This function inserts @var{count} instances of @var{character} into the +current buffer before point. The argument @var{count} must be a number, +and @var{character} must be a character. The value is @code{nil}. +@c It's unfortunate that count comes second. Not like make-string, etc. +@end defun + +@defun insert-buffer-substring from-buffer-or-name &optional start end +This function inserts a portion of buffer @var{from-buffer-or-name} +(which must already exist) into the current buffer before point. The +text inserted is the region from @var{start} and @var{end}. (These +arguments default to the beginning and end of the accessible portion of +that buffer.) This function returns @code{nil}. + +In this example, the form is executed with buffer @samp{bar} as the +current buffer. We assume that buffer @samp{bar} is initially empty. + +@example +@group +---------- Buffer: foo ---------- +We hold these truths to be self-evident, that all +---------- Buffer: foo ---------- +@end group + +@group +(insert-buffer-substring "foo" 1 20) + @result{} nil + +---------- Buffer: bar ---------- +We hold these truth +---------- Buffer: bar ---------- +@end group +@end example +@end defun + + @xref{Sticky Properties}, for other insertion functions that inherit +text properties from the nearby text. + +@node Commands for Insertion +@section User-Level Insertion Commands + + This section describes higher-level commands for inserting text, +commands intended primarily for the user but useful also in Lisp +programs. + +@deffn Command insert-buffer from-buffer-or-name +This command inserts the entire contents of @var{from-buffer-or-name} +(which must exist) into the current buffer after point. It leaves +the mark after the inserted text. The value is @code{nil}. +@end deffn + +@deffn Command self-insert-command count +@cindex character insertion +@cindex self-insertion +This command inserts the last character typed @var{count} times and +returns @code{nil}. Most printing characters are bound to this command. +In routine use, @code{self-insert-command} is the most frequently called +function in Emacs, but programs rarely use it except to install it on a +keymap. + +In an interactive call, @var{count} is the numeric prefix argument. + +This function calls @code{auto-fill-function} if the current column number +is greater than the value of @code{fill-column} and the character +inserted is a space (@pxref{Auto Filling}). + +@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92 +This function performs abbrev expansion if Abbrev mode is enabled and +the inserted character does not have word-constituent +syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.) + +This function is also responsible for calling +@code{blink-paren-function} when the inserted character has close +parenthesis syntax (@pxref{Blinking}). +@end deffn + +@deffn Command newline &optional number-of-newlines +This command inserts newlines into the current buffer before point. +If @var{number-of-newlines} is supplied, that many newline characters +are inserted. + +@cindex newline and Auto Fill mode +In Auto Fill mode, @code{newline} can break the preceding line if +@var{number-of-newlines} is not supplied. When this happens, it +actually inserts two newlines at different places: one at point, and +another earlier in the line. @code{newline} does not auto-fill if +@var{number-of-newlines} is non-@code{nil}. + +The value returned is @code{nil}. In an interactive call, @var{count} +is the numeric prefix argument. +@end deffn + +@deffn Command split-line +This command splits the current line, moving the portion of the line +after point down vertically, so that it is on the next line directly +below where it was before. Whitespace is inserted as needed at the +beginning of the lower line, using the @code{indent-to} function. +@code{split-line} returns the position of point. + +Programs hardly ever use this function. +@end deffn + +@defvar overwrite-mode +This variable controls whether overwrite mode is in effect: a +non-@code{nil} value enables the mode. It is automatically made +buffer-local when set in any fashion. +@end defvar + +@node Deletion +@section Deletion of Text + +@cindex deletion vs killing + Deletion means removing part of the text in a buffer, without saving +it in the kill ring (@pxref{The Kill Ring}). Deleted text can't be +yanked, but can be reinserted using the undo mechanism (@pxref{Undo}). +Some deletion functions save text in the kill ring in some cases +but not in the usual case. + + All of the deletion functions operate on the current buffer, and all +return a value of @code{nil}. + +@defun erase-buffer +This function deletes the entire text of the current buffer, leaving it +empty. If the buffer is read-only, it signals a @code{buffer-read-only} +error. Otherwise, it deletes the text without asking for any +confirmation. It returns @code{nil}. + +Normally, deleting a large amount of text from a buffer inhibits further +auto-saving of that buffer ``because it has shrunk''. However, +@code{erase-buffer} does not do this, the idea being that the future +text is not really related to the former text, and its size should not +be compared with that of the former text. +@end defun + +@deffn Command delete-region start end +This command deletes the text in the current buffer in the region +defined by @var{start} and @var{end}. The value is @code{nil}. +@end deffn + +@deffn Command delete-char count &optional killp +This command deletes @var{count} characters directly after point, or +before point if @var{count} is negative. If @var{killp} is +non-@code{nil}, then it saves the deleted characters in the kill ring. + +In an interactive call, @var{count} is the numeric prefix argument, and +@var{killp} is the unprocessed prefix argument. Therefore, if a prefix +argument is supplied, the text is saved in the kill ring. If no prefix +argument is supplied, then one character is deleted, but not saved in +the kill ring. + +The value returned is always @code{nil}. +@end deffn + +@deffn Command delete-backward-char count &optional killp +@cindex delete previous char +This command deletes @var{count} characters directly before point, or +after point if @var{count} is negative. If @var{killp} is +non-@code{nil}, then it saves the deleted characters in the kill ring. + +In an interactive call, @var{count} is the numeric prefix argument, and +@var{killp} is the unprocessed prefix argument. Therefore, if a prefix +argument is supplied, the text is saved in the kill ring. If no prefix +argument is supplied, then one character is deleted, but not saved in +the kill ring. + +The value returned is always @code{nil}. +@end deffn + +@deffn Command backward-delete-char-untabify count &optional killp +@cindex tab deletion +This command deletes @var{count} characters backward, changing tabs +into spaces. When the next character to be deleted is a tab, it is +first replaced with the proper number of spaces to preserve alignment +and then one of those spaces is deleted instead of the tab. If +@var{killp} is non-@code{nil}, then the command saves the deleted +characters in the kill ring. + +Conversion of tabs to spaces happens only if @var{count} is positive. +If it is negative, exactly @minus{}@var{count} characters after point +are deleted. + +In an interactive call, @var{count} is the numeric prefix argument, and +@var{killp} is the unprocessed prefix argument. Therefore, if a prefix +argument is supplied, the text is saved in the kill ring. If no prefix +argument is supplied, then one character is deleted, but not saved in +the kill ring. + +The value returned is always @code{nil}. +@end deffn + +@node User-Level Deletion +@section User-Level Deletion Commands + + This section describes higher-level commands for deleting text, +commands intended primarily for the user but useful also in Lisp +programs. + +@deffn Command delete-horizontal-space +@cindex deleting whitespace +This function deletes all spaces and tabs around point. It returns +@code{nil}. + +In the following examples, we call @code{delete-horizontal-space} four +times, once on each line, with point between the second and third +characters on the successive line. + +@example +@group +---------- Buffer: foo ---------- +I @point{}thought +I @point{} thought +We@point{} thought +Yo@point{}u thought +---------- Buffer: foo ---------- +@end group + +@group +(delete-horizontal-space) ; @r{Four times.} + @result{} nil + +---------- Buffer: foo ---------- +Ithought +Ithought +Wethought +You thought +---------- Buffer: foo ---------- +@end group +@end example +@end deffn + +@deffn Command delete-indentation &optional join-following-p +This function joins the line point is on to the previous line, deleting +any whitespace at the join and in some cases replacing it with one +space. If @var{join-following-p} is non-@code{nil}, +@code{delete-indentation} joins this line to the following line +instead. The value is @code{nil}. + +If there is a fill prefix, and the second of the lines being joined +starts with the prefix, then @code{delete-indentation} deletes the +fill prefix before joining the lines. + +In the example below, point is located on the line starting +@samp{events}, and it makes no difference if there are trailing spaces +in the preceding line. + +@smallexample +---------- Buffer: foo ---------- +When in the course of human +@point{} events, it becomes necessary +---------- Buffer: foo ---------- + +(delete-indentation) + @result{} nil + +---------- Buffer: foo ---------- +When in the course of human@point{} events, it becomes necessary +---------- Buffer: foo ---------- +@end smallexample + +After the lines are joined, the function @code{fixup-whitespace} is +responsible for deciding whether to leave a space at the junction. +@end deffn + +@defun fixup-whitespace +This function replaces all the white space surrounding point with either +one space or no space, according to the context. It returns @code{nil}. + +At the beginning or end of a line, the appropriate amount of space is +none. Before a character with close parenthesis syntax, or after a +character with open parenthesis or expression-prefix syntax, no space is +also appropriate. Otherwise, one space is appropriate. @xref{Syntax +Class Table}. + +In the example below, @code{fixup-whitespace} is called the first time +with point before the word @samp{spaces} in the first line. for the +second invocation, Point is directly after the @samp{(}. + +@smallexample +@group +---------- Buffer: foo ---------- +This has too many @point{}spaces +This has too many spaces at the start of (@point{} this list) +---------- Buffer: foo ---------- +@end group + +@group +(fixup-whitespace) + @result{} nil +(fixup-whitespace) + @result{} nil +@end group + +@group +---------- Buffer: foo ---------- +This has too many spaces +This has too many spaces at the start of (this list) +---------- Buffer: foo ---------- +@end group +@end smallexample +@end defun + +@deffn Command just-one-space +@comment !!SourceFile simple.el +This command replaces any spaces and tabs around point with a single +space. It returns @code{nil}. +@end deffn + +@deffn Command delete-blank-lines +This function deletes blank lines surrounding point. If point is on a +blank line with one or more blank lines before or after it, then all but +one of them are deleted. If point is on an isolated blank line, then it +is deleted. If point is on a nonblank line, the command deletes all +blank lines following it. + +A blank line is defined as a line containing only tabs and spaces. + +@code{delete-blank-lines} returns @code{nil}. +@end deffn + +@node The Kill Ring +@section The Kill Ring +@cindex kill ring + + @dfn{Kill} functions delete text like the deletion functions, but save +it so that the user can reinsert it by @dfn{yanking}. Most of these +functions have @samp{kill-} in their name. By contrast, the functions +whose names start with @samp{delete-} normally do not save text for +yanking (though they can still be undone); these are ``deletion'' +functions. + + Most of the kill commands are primarily for interactive use, and are +not described here. What we do describe are the functions provided for +use in writing such commands. You can use these functions to write +commands for killing text. When you need to deleting text for internal +purposes within a Lisp function, you should normally use deletion +functions, so as not to disturb the kill ring contents. +@xref{Deletion}. + + Killed text is saved for later yanking in the @dfn{kill ring}. This +is a list which holds, not just the last text kill, but a number of +recent kills. We call this a ``ring'' because yanking treats it as a +cyclic order. The list is kept in the variable @code{kill-ring}, and +can be operated on with the usual functions for lists; there are also +specialized functions, described in this section, which treat it as a +ring. + + Some people think this use of the word ``kill'' is unfortunate, since +it refers to operations which specifically @emph{do not} destroy the +entities ``killed''. This is in sharp contrast to ordinary life, in +which death is permanent and ``killed'' entities do not come back to +life. Therefore, other metaphors have been proposed. For example, the +term ``cut ring'' makes sense to people who, in pre-computer days, used +scissors and paste to cut up and rearrange manuscripts. However, it +would be difficult to change the terminology now. + +@menu +* Kill Ring Concepts:: What text looks like in the kill ring. +* Kill Functions:: Functions that kill text. +* Yank Commands:: Commands that access the kill ring. +* Low Level Kill Ring:: Functions and variables for kill ring access. +* Internals of Kill Ring:: Variables that hold kill-ring data. +@end menu + +@node Kill Ring Concepts +@comment node-name, next, previous, up +@subsection Kill Ring Concepts + + The kill ring records killed text as strings in a list, most recent +first. A short kill ring, for example, might look like this: + +@example +("some text" "a different piece of text" "even older text") +@end example + +@noindent +When the list reaches @code{kill-ring-max} entries in length, adding a +new entry automatically deletes the last entry. + + When kill commands are interwoven with other commands, each kill +command makes a new entry in the kill ring. Multiple kill commands in +succession build up a single entry in the kill ring, which would be +yanked as a unit. The second and subsequent consecutive kill commands +add text to the entry made by the first one. + + For yanking, one entry in the kill ring is designated the ``front'' of +the ring. Some yank commands ``rotate'' the ring by designating a +different element as the ``front.'' But this virtual rotation doesn't +change the list itself---the most recent entry always comes first in the +list. + +@node Kill Functions +@comment node-name, next, previous, up +@subsection Functions for Killing + + @code{kill-region} is the usual subroutine for killing text. Any +command that calls this function is a ``kill command'' (and should +probably have @samp{kill} in its name). @code{kill-region} puts the +newly killed text in a new element at the beginning of the kill ring or +adds it to the most recent element. It uses the @code{last-command} +variable to determine whether the previous was a kill command, and if so +appends the killed text to the most recent entry. + +@deffn Command kill-region start end +This function kills the text in the region defined by @var{start} and +@var{end}. The text is deleted but saved in the kill ring. The value +is always @code{nil}. + +In an interactive call, @var{start} and @var{end} are point and +the mark. + +@c Emacs 19 feature +If the buffer is read-only, @code{kill-region} modifies the kill ring +just the same, then signals an error without modifying the buffer. This +is convenient because it lets the user use all the kill commands to copy +text into the kill ring from a read-only buffer. +@end deffn + +@deffn Command copy-region-as-kill start end +This command saves the region defined by @var{start} and @var{end} on +the kill ring, but does not delete the text from the buffer. It returns +@code{nil}. It also indicates the extent of the text copied by moving +the cursor momentarily, or by displaying a message in the echo area. + +Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to +support Emacs 18. For Emacs 19, it is better to use @code{kill-new} or +@code{kill-append} instead. @xref{Low Level Kill Ring}. +@end deffn + +@node Yank Commands +@comment node-name, next, previous, up +@subsection Functions for Yanking + + @dfn{Yanking} means reinserting an entry of previously killed text +from the kill ring. + +@deffn Command yank &optional arg +@cindex inserting killed text +This command inserts before point the text in the first entry in the +kill ring. It positions the mark at the beginning of that text, and +point at the end. + +If @var{arg} is a list (which occurs interactively when the user +types @kbd{C-u} with no digits), then @code{yank} inserts the text as +described above, but puts point before the yanked text and puts the mark +after it. + +If @var{arg} is a number, then @code{yank} inserts the @var{arg}th most +recently killed text---the @var{arg}th element of the kill ring list. + +@code{yank} does not alter the contents of the kill ring or rotate it. +It returns @code{nil}. +@end deffn + +@deffn Command yank-pop arg +This command replaces the just-yanked entry from the kill ring with a +different entry from the kill ring. + +This is allowed only immediately after a @code{yank} or another +@code{yank-pop}. At such a time, the region contains text that was just +inserted by yanking. @code{yank-pop} deletes that text and inserts in +its place a different piece of killed text. It does not add the deleted +text to the kill ring, since it is already in the kill ring somewhere. + +If @var{arg} is @code{nil}, then the replacement text is the previous +element of the kill ring. If @var{arg} is numeric, the replacement is +the @var{arg}th previous kill. If @var{arg} is negative, a more recent +kill is the replacement. + +The sequence of kills in the kill ring wraps around, so that after the +oldest one comes the newest one, and before the newest one goes the +oldest. + +The value is always @code{nil}. +@end deffn + +@node Low Level Kill Ring +@subsection Low Level Kill Ring + + These functions and variables provide access to the kill ring at a lower +level, but still convenient for use in Lisp programs. They take care of +interaction with X Window selections. They do not exist in Emacs +version 18. + +@defun current-kill n &optional do-not-move +The function @code{current-kill} rotates the yanking pointer in the +kill ring by @var{n} places, and returns the text at that place in the +ring. + +If the optional second argument @var{do-not-move} is non-@code{nil}, +then @code{current-kill} doesn't alter the yanking pointer; it just +returns the @var{n}th kill forward from the current yanking pointer. + +If @var{n} is zero, indicating a request for the latest kill, +@code{current-kill} calls the value of +@code{interprogram-paste-function} (documented below) before consulting +the kill ring. +@end defun + +@defun kill-new string +This function puts the text @var{string} into the kill ring as a new +entry at the front of the ring. It discards the oldest entry if +appropriate. It also invokes the value of +@code{interprogram-cut-function} (see below). +@end defun + +@defun kill-append string before-p +This function appends the text @var{string} to the first entry in the +kill ring. Normally @var{string} goes at the end of the entry, but if +@var{before-p} is non-@code{nil}, it goes at the beginning. This +function also invokes the value of @code{interprogram-cut-function} (see +below). +@end defun + +@defvar interprogram-paste-function +This variable provides a way of transferring killed text from other +programs, when you are using a window system. Its value should be +@code{nil} or a function of no arguments. + +If the value is a function, @code{current-kill} calls it to get the +``most recent kill''. If the function returns a non-@code{nil} value, +then that value is used as the ``most recent kill''. If it returns +@code{nil}, then the first element of @code{kill-ring} is used. + +The normal use of this hook is to get the X server's primary selection +as the most recent kill, even if the selection belongs to another X +client. @xref{X Selections}. +@end defvar + +@defvar interprogram-cut-function +This variable provides a way of communicating killed text to and from +other programs, when you are using a window system. Its value should be +@code{nil} or a function of one argument. + +If the value is a function, @code{kill-new} and @code{kill-append} call +it with the new first element of the kill ring as an argument. + +The normal use of this hook is to set the X server's primary selection +to the newly killed text. +@end defvar + +@node Internals of Kill Ring +@comment node-name, next, previous, up +@subsection Internals of the Kill Ring + + The variable @code{kill-ring} holds the kill ring contents, in the +form of a list of strings. The most recent kill is always at the front +of the list. + + The @code{kill-ring-yank-pointer} variable points to a link in the +kill ring list, whose @sc{car} is the text to yank next. Moving +@code{kill-ring-yank-pointer} to a different link is called +@dfn{rotating the kill ring}; we say it identifies the ``front'' of the +ring. We call the kill ring a ``ring'' because the functions that move +the yank pointer wrap around from the end of the list to the beginning, +or vice-versa. Rotation of the kill ring is virtual; it does not change +the value of @code{kill-ring}. + + Both @code{kill-ring} and @code{kill-ring-yank-pointer} are Lisp +variables whose values are normally lists. The word ``pointer'' in the +name of the @code{kill-ring-yank-pointer} indicates that the variable's +purpose is to identify one element of the list for use by the next yank +command. + + The value of @code{kill-ring-yank-pointer} is always @code{eq} to one +of the links in the kill ring list. The element it identifies is the +@sc{car} of that link. Kill commands, which change the kill ring, also +set this variable from @code{kill-ring}. The effect is to rotate the +ring so that the newly killed text is at front. + + Here is a diagram that shows the variable @code{kill-ring-yank-pointer} +pointing to the second entry in the kill ring @code{("some text" "a +different piece of text" "yet older text")}. + +@example +@group +kill-ring kill-ring-yank-pointer + | | + | ___ ___ ---> ___ ___ ___ ___ + --> |___|___|------> |___|___|--> |___|___|--> nil + | | | + | | | + | | -->"yet older text" + | | + | --> "a different piece of text" + | + --> "some text" +@end group +@end example + +@noindent +This state of affairs might occur after @kbd{C-y} (@code{yank}) +immediately followed by @kbd{M-y} (@code{yank-pop}). + +@defvar kill-ring +This variable holds list of killed text sequences, most recently killed +first. +@end defvar + +@defvar kill-ring-yank-pointer +This variable's value indicates which element of the kill ring is at the +``front'' of the ring for yanking. More precisely, the value is a tail +of the value of @code{kill-ring}, and its @sc{car} is the kill string +that @kbd{C-y} should yank. +@end defvar + +@defopt kill-ring-max +The value of this variable is the maximum length to which the kill +ring can grow, before elements are thrown away at the end. The default +value for @code{kill-ring-max} is 30. +@end defopt + +@node Undo +@comment node-name, next, previous, up +@section Undo +@cindex redo + + Most buffers have an @dfn{undo list} which records all changes made to +the buffer's text so that they can be undone. (The buffers which don't +have one are usually special-purpose buffers for which Emacs assumes +that undoing is not useful.) All the primitives which modify the text +in the buffer automatically add elements to the front of the undo list, +which is in the variable @code{buffer-undo-list}. + +@defvar buffer-undo-list +This variable's value is the undo list of the current buffer. +A value of @code{t} disables the recording of undo information. +@end defvar + +Here are the kinds of elements an undo list can have: + +@table @code +@item @var{integer} +This kind of element records a previous value of point. Ordinary cursor +motion does not get any sort of undo record, but deletion commands use +these entries to record where point was before the command. + +@item (@var{beg} . @var{end}) +This kind of element indicates how to delete text that was inserted. +Upon insertion, the text occupied the range @var{beg}--@var{end} in the +buffer. + +@item (@var{pos} . @var{deleted}) +This kind of element indicates how to reinsert text that was deleted. +The deleted text itself is the string @var{deleted}. The place to +reinsert it is @var{pos}. + +@item (t @var{high} . @var{low}) +This kind of element indicates that an unmodified buffer became +modified. The elements @var{high} and @var{low} are two integers, each +recording 16 bits of the visited file's modification time as of when it +was previously visited or saved. @code{primitive-undo} uses those +values to determine whether to mark the buffer as unmodified once again; +it does so only if the file's modification time matches those numbers. + +@item (nil @var{property} @var{value} @var{beg} . @var{end}) +This kind of element records a change in a text property. +Here's how you might undo the change: + +@example +(put-text-property @var{beg} @var{end} @var{property} @var{value}) +@end example + +@item nil +This element is a boundary. The elements between two boundaries are +called a @dfn{change group}; normally, each change group corresponds to +one keyboard command, and undo commands normally undo an entire group as +a unit. +@end table + +@defun undo-boundary +This function places a boundary element in the undo list. The undo +command stops at such a boundary, and successive undo commands undo +to earlier and earlier boundaries. This function returns @code{nil}. + +The editor command loop automatically creates an undo boundary between +keystroke commands. Thus, each undo normally undoes the effects of one +command. Calling this function explicitly is useful for splitting the +effects of a command into more than one unit. For example, +@code{query-replace} calls this function after each replacement so that +the user can undo individual replacements one by one. +@end defun + +@defun primitive-undo count list +This is the basic function for undoing elements of an undo list. +It undoes the first @var{count} elements of @var{list}, returning +the rest of @var{list}. You could write this function in Lisp, +but it is convenient to have it in C. + +@code{primitive-undo} adds elements to the buffer's undo list when it +changes the buffer. Undo commands avoid confusion by saving the undo +list value at the beginning of a sequence of undo operations. Then the +undo operations use and update the saved value. The new elements added +by undoing are not part of the saved value, so they don't interfere with +continuing to undo. +@end defun + +@node Maintaining Undo +@section Maintaining Undo Lists + + This section describes how to enable and disable undo information for +a given buffer. It also explains how the undo list is truncated +automatically so it doesn't get too big. + + Recording of undo information in a newly created buffer is normally +enabled to start with; but if the buffer name starts with a space, the +undo recording is initially disabled. You can explicitly enable or +disable undo recording with the following two functions, or by setting +@code{buffer-undo-list} yourself. + +@deffn Command buffer-enable-undo &optional buffer-or-name +This command enables recording undo information for buffer +@var{buffer-or-name}, so that subsequent changes can be undone. If no +argument is supplied, then the current buffer is used. This function +does nothing if undo recording is already enabled in the buffer. It +returns @code{nil}. + +In an interactive call, @var{buffer-or-name} is the current buffer. +You cannot specify any other buffer. +@end deffn + +@defun buffer-disable-undo &optional buffer +@defunx buffer-flush-undo &optional buffer +@cindex disable undo +This function discards the undo list of @var{buffer}, and disables +further recording of undo information. As a result, it is no longer +possible to undo either previous changes or any subsequent changes. If +the undo list of @var{buffer} is already disabled, this function +has no effect. + +This function returns @code{nil}. It cannot be called interactively. + +The name @code{buffer-flush-undo} is not considered obsolete, but the +preferred name @code{buffer-disable-undo} is new as of Emacs versions +19. +@end defun + + As editing continues, undo lists get longer and longer. To prevent +them from using up all available memory space, garbage collection trims +them back to size limits you can set. (For this purpose, the ``size'' +of an undo list measures the cons cells that make up the list, plus the +strings of deleted text.) Two variables control the range of acceptable +sizes: @code{undo-limit} and @code{undo-strong-limit}. + +@defvar undo-limit +This is the soft limit for the acceptable size of an undo list. The +change group at which this size is exceeded is the last one kept. +@end defvar + +@defvar undo-strong-limit +The upper limit for the acceptable size of an undo list. The change +group at which this size is exceeded is discarded itself (along with all +subsequent changes). There is one exception: garbage collection always +keeps the very latest change group no matter how big it is. +@end defvar + +@node Filling +@comment node-name, next, previous, up +@section Filling +@cindex filling, explicit + + @dfn{Filling} means adjusting the lengths of lines (by moving the line +breaks) so that they are nearly (but no greater than) a specified +maximum width. Additionally, lines can be @dfn{justified}, which means +that spaces are inserted between words to make the line exactly the +specified width. The width is controlled by the variable +@code{fill-column}. For ease of reading, lines should be no longer than +70 or so columns. + + You can use Auto Fill mode (@pxref{Auto Filling}) to fill text +automatically as you insert it, but changes to existing text may leave +it improperly filled. Then you must fill the text explicitly. + + Most of the functions in this section return values that are not +meaningful. + +@deffn Command fill-paragraph justify-flag +@cindex filling a paragraph +This command fills the paragraph at or after point. If +@var{justify-flag} is non-@code{nil}, each line is justified as well. +It uses the ordinary paragraph motion commands to find paragraph +boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}. +@end deffn + +@deffn Command fill-region start end &optional justify-flag +This command fills each of the paragraphs in the region from @var{start} +to @var{end}. It justifies as well if @var{justify-flag} is +non-@code{nil}. + +The variable @code{paragraph-separate} controls how to distinguish +paragraphs. @xref{Standard Regexps}. +@end deffn + +@deffn Command fill-individual-paragraphs start end &optional justify-flag mail-flag +This command fills each paragraph in the region according to its +individual fill prefix. Thus, if the lines of a paragraph were indented +with spaces, the filled paragraph will remain indented in the same +fashion. + +The first two arguments, @var{start} and @var{end}, are the beginning +and end of the region to be filled. The third and fourth arguments, +@var{justify-flag} and @var{mail-flag}, are optional. If +@var{justify-flag} is non-@code{nil}, the paragraphs are justified as +well as filled. If @var{mail-flag} is non-@code{nil}, it means the +function is operating on a mail message and therefore should not fill +the header lines. + +Ordinarily, @code{fill-individual-paragraphs} regards each change in +indentation as starting a new paragraph. If +@code{fill-individual-varying-indent} is non-@code{nil}, then only +separator lines separate paragraphs. That mode can handle paragraphs +with extra indentation on the first line. +@end deffn + +@defopt fill-individual-varying-indent +This variable alters the action of @code{fill-individual-paragraphs} as +described above. +@end defopt + +@deffn Command fill-region-as-paragraph start end &optional justify-flag +This command considers a region of text as a paragraph and fills it. If +the region was made up of many paragraphs, the blank lines between +paragraphs are removed. This function justifies as well as filling when +@var{justify-flag} is non-@code{nil}. In an interactive call, any +prefix argument requests justification. + +In Adaptive Fill mode, which is enabled by default, +@code{fill-region-as-paragraph} on an indented paragraph when there is +no fill prefix uses the indentation of the second line of the paragraph +as the fill prefix. +@end deffn + +@deffn Command justify-current-line +This command inserts spaces between the words of the current line so +that the line ends exactly at @code{fill-column}. It returns +@code{nil}. +@end deffn + +@defopt fill-column +This buffer-local variable specifies the maximum width of filled +lines. Its value should be an integer, which is a number of columns. +All the filling, justification and centering commands are affected by +this variable, including Auto Fill mode (@pxref{Auto Filling}). + +As a practical matter, if you are writing text for other people to +read, you should set @code{fill-column} to no more than 70. Otherwise +the line will be too long for people to read comfortably, and this can +make the text seem clumsy. +@end defopt + +@defvar default-fill-column +The value of this variable is the default value for @code{fill-column} in +buffers that do not override it. This is the same as +@code{(default-value 'fill-column)}. + +The default value for @code{default-fill-column} is 70. +@end defvar + +@node Auto Filling +@comment node-name, next, previous, up +@section Auto Filling +@cindex filling, automatic +@cindex Auto Fill mode + + Auto Fill mode is a minor mode which fills lines automatically as text +as inserted. This section describes the hook and the two variables used +by Auto Fill mode. For a description of functions that you can call +explicitly to fill and justify existing text, see @ref{Filling}. + +@defvar auto-fill-function +The value of this variable should be a function (of no arguments) to +be called after self-inserting a space at a column beyond +@code{fill-column}. It may be @code{nil}, in which case nothing +special is done. + +The value of @code{auto-fill-function} is @code{do-auto-fill} when +Auto-Fill mode is enabled. That is a function whose sole purpose is to +implement the usual strategy for breaking a line. + +@quotation +In older Emacs versions, this variable was named @code{auto-fill-hook}, +but since it is not called with the standard convention for hooks, it +was renamed to @code{auto-fill-function} in version 19. +@end quotation +@end defvar + +@node Sorting +@section Sorting Text +@cindex sorting text + + The sorting functions described in this section all rearrange text in +a buffer. This is in contrast to the function @code{sort}, which +rearranges the order of the elements of a list (@pxref{Rearrangement}). +The values returned by these functions are not meaningful. + +@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun +This function is the general text sorting routine that divides a buffer +into records and sorts them. Most of the commands in this section use +this function. + +To understand how @code{sort-subr} works, consider the whole accessible +portion of the buffer as being divided into disjoint pieces called +@dfn{sort records}. The records may or may not be contiguous; they may +not overlap. A portion of each sort record (perhaps all of it) is +designated as the sort key. Sorting rearranges the records in order by +their sort keys. + +Usually, the records are rearranged in order of ascending sort key. +If the first argument to the @code{sort-subr} function, @var{reverse}, +is non-@code{nil}, the sort records are rearranged in order of +descending sort key. + +The next four arguments to @code{sort-subr} are functions that are +called to move point across a sort record. They are called many times +from within @code{sort-subr}. + +@enumerate +@item +@var{nextrecfun} is called with point at the end of a record. This +function moves point to the start of the next record. The first record +is assumed to start at the position of point when @code{sort-subr} is +called. Therefore, you should usually move point to the beginning of +the buffer before calling @code{sort-subr}. + +This function can indicate there are no more sort records by leaving +point at the end of the buffer. + +@item +@var{endrecfun} is called with point within a record. It moves point to +the end of the record. + +@item +@var{startkeyfun} is called to move point from the start of a record to +the start of the sort key. This argument is optional; if it is omitted, +the whole record is the sort key. If supplied, the function should +either return a non-@code{nil} value to be used as the sort key, or +return @code{nil} to indicate that the sort key is in the buffer +starting at point. In the latter case, @var{endkeyfun} is called to +find the end of the sort key. + +@item +@var{endkeyfun} is called to move point from the start of the sort key +to the end of the sort key. This argument is optional. If +@var{startkeyfun} returns @code{nil} and this argument is omitted (or +@code{nil}), then the sort key extends to the end of the record. There +is no need for @var{endkeyfun} if @var{startkeyfun} returns a +non-@code{nil} value. +@end enumerate + +As an example of @code{sort-subr}, here is the complete function +definition for @code{sort-lines}: + +@example +@group +;; @r{Note that the first two lines of doc string} +;; @r{are effectively one line when viewed by a user.} +(defun sort-lines (reverse beg end) + "Sort lines in region alphabetically. +Called from a program, there are three arguments: +@end group +@group +REVERSE (non-nil means reverse order), +and BEG and END (the region to sort)." + (interactive "P\nr") + (save-restriction + (narrow-to-region beg end) + (goto-char (point-min)) + (sort-subr reverse + 'forward-line + 'end-of-line))) +@end group +@end example + +Here @code{forward-line} moves point to the start of the next record, +and @code{end-of-line} moves point to the end of record. We do not pass +the arguments @var{startkeyfun} and @var{endkeyfun}, because the entire +record is used as the sort key. + +The @code{sort-paragraphs} function is very much the same, except that +its @code{sort-subr} call looks like this: + +@example +@group +(sort-subr reverse + (function + (lambda () + (skip-chars-forward "\n \t\f"))) + 'forward-paragraph) +@end group +@end example +@end defun + +@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end +This command sorts the region between @var{start} and @var{end} +alphabetically as specified by @var{record-regexp} and @var{key-regexp}. +If @var{reverse} is a negative integer, then sorting is in reverse +order. + +Alphabetical sorting means that two sort keys are compared by +comparing the first characters of each, the second characters of each, +and so on. If a mismatch is found, it means that the sort keys are +unequal; the sort key whose character is less at the point of first +mismatch is the lesser sort key. The individual characters are compared +according to their numerical values. Since Emacs uses the @sc{ASCII} +character set, the ordering in that set determines alphabetical order. +@c version 19 change + +The value of the @var{record-regexp} argument specifies how to divide +the buffer into sort records. At the end of each record, a search is +done for this regular expression, and the text that matches it is the +next record. For example, the regular expression @samp{^.+$}, which +matches lines with at least one character besides a newline, would make +each such line into a sort record. @xref{Regular Expressions}, for a +description of the syntax and meaning of regular expressions. + +The value of the @var{key-regexp} argument specifies what part of each +record is the sort key. The @var{key-regexp} could match the whole +record, or only a part. In the latter case, the rest of the record has +no effect on the sorted order of records, but it is carried along when +the record moves to its new position. + +The @var{key-regexp} argument can refer to the text matched by a +subexpression of @var{record-regexp}, or it can be a regular expression +on its own. + +If @var{key-regexp} is: + +@table @asis +@item @samp{\@var{digit}} +then the text matched by the @var{digit}th @samp{\(...\)} parenthesis +grouping in @var{record-regexp} is the sort key. + +@item @samp{\&} +then the whole record is the sort key. + +@item a regular expression +then @code{sort-regexp-fields} searches for a match for the regular +expression within the record. If such a match is found, it is the sort +key. If there is no match for @var{key-regexp} within a record then +that record is ignored, which means its position in the buffer is not +changed. (The other records may move around it.) +@end table + +For example, if you plan to sort all the lines in the region by the +first word on each line starting with the letter @samp{f}, you should +set @var{record-regexp} to @samp{^.*$} and set @var{key-regexp} to +@samp{\<f\w*\>}. The resulting expression looks like this: + +@example +@group +(sort-regexp-fields nil "^.*$" "\\<f\\w*\\>" + (region-beginning) + (region-end)) +@end group +@end example + +If you call @code{sort-regexp-fields} interactively, it prompts for +@var{record-regexp} and @var{key-regexp} in the minibuffer. +@end deffn + +@deffn Command sort-lines reverse start end +This command alphabetically sorts lines in the region between +@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort +is in reverse order. +@end deffn + +@deffn Command sort-paragraphs reverse start end +This command alphabetically sorts paragraphs in the region between +@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort +is in reverse order. +@end deffn + +@deffn Command sort-pages reverse start end +This command alphabetically sorts pages in the region between +@var{start} and @var{end}. If @var{reverse} is non-@code{nil}, the sort +is in reverse order. +@end deffn + +@deffn Command sort-fields field start end +This command sorts lines in the region between @var{start} and +@var{end}, comparing them alphabetically by the @var{field}th field +of each line. Fields are separated by whitespace and numbered starting +from 1. If @var{field} is negative, sorting is by the +@w{@minus{}@var{field}th} field from the end of the line. This command +is useful for sorting tables. +@end deffn + +@deffn Command sort-numeric-fields field start end +This command sorts lines in the region between @var{start} and +@var{end}, comparing them numerically by the @var{field}th field of each +line. The specified field must contain a number in each line of the +region. Fields are separated by whitespace and numbered starting from +1. If @var{field} is negative, sorting is by the +@w{@minus{}@var{field}th} field from the end of the line. This command +is useful for sorting tables. +@end deffn + +@deffn Command sort-columns reverse &optional beg end +This command sorts the lines in the region between @var{beg} and +@var{end}, comparing them alphabetically by a certain range of columns. +The column positions of @var{beg} and @var{end} bound the range of +columns to sort on. + +If @var{reverse} is non-@code{nil}, the sort is in reverse order. + +One unusual thing about this command is that the entire line +containing position @var{beg}, and the entire line containing position +@var{end}, are included in the region sorted. + +Note that @code{sort-columns} uses the @code{sort} utility program, +and so cannot work properly on text containing tab characters. Use +@kbd{M-x @code{untabify}} to convert tabs to spaces before sorting. + +The @code{sort-columns} function did not work on VMS prior to Emacs 19. +@end deffn + +@node Columns +@comment node-name, next, previous, up +@section Counting Columns +@cindex columns +@cindex counting columns +@cindex horizontal position + + The column functions convert between a character position (counting +characters from the beginning of the buffer) and a column position +(counting screen characters from the beginning of a line). + + A character counts according to the number of columns it occupies on +the screen. This means control characters count as occupying 2 or 4 +columns, depending upon the value of @code{ctl-arrow}, and tabs count as +occupying a number of columns that depends on the value of +@code{tab-width} and on the column where the tab begins. @xref{Usual Display}. + + Column number computations ignore the width of the window and the +amount of horizontal scrolling. Consequently, a column value can be +arbitrarily high. The first (or leftmost) column is numbered 0. + +@defun current-column +This function returns the horizontal position of point, measured in +columns, counting from 0 at the left margin. The column position is the +sum of the widths of all the displayed representations of the characters +between the start of the current line and point. + +For an example of using @code{current-column}, see the description of +@code{count-lines} in @ref{Text Lines}. +@end defun + +@defun move-to-column column &optional force +This function moves point to @var{column} in the current line. The +calculation of @var{column} takes into account the widths of the +displayed representations of the characters between the start of the +line and point. + +If column @var{column} is beyond the end of the line, point moves to the +end of the line. If @var{column} is negative, point moves to the +beginning of the line. + +If it is impossible to move to column @var{column} because that is in +the middle of a multicolumn character such as a tab, point moves to the +end of that character. However, if @var{force} is non-@code{nil}, and +@var{column} is in the middle of a tab, then @code{move-to-column} +converts the tab into spaces so that it can move precisely to column +@var{column}. Other multicolumn characters can cause anomalies despite +@var{force}, since there is no way to split them. + +The argument @var{force} also has an effect if the line isn't long +enough to reach column @var{column}; in that case, it says to indent at +the end of the line to reach that column. + +If @var{column} is not an integer, an error is signaled. + +The return value is the column number actually moved to. +@end defun + +@node Indentation +@section Indentation +@cindex indentation + + The indentation functions are used to examine, move to, and change +whitespace that is at the beginning of a line. Some of the functions +can also change whitespace elsewhere on a line. Columns and indentation +count from zero at the left margin. + +@menu +* Primitive Indent:: Functions used to count and insert indentation. +* Mode-Specific Indent:: Customize indentation for different modes. +* Region Indent:: Indent all the lines in a region. +* Relative Indent:: Indent the current line based on previous lines. +* Indent Tabs:: Adjustable, typewriter-like tab stops. +* Motion by Indent:: Move to first non-blank character. +@end menu + +@node Primitive Indent +@subsection Indentation Primitives + + This section describes the primitive functions used to count and +insert indentation. The functions in the following sections use these +primitives. + +@defun current-indentation +@comment !!Type Primitive Function +@comment !!SourceFile indent.c +This function returns the indentation of the current line, which is +the horizontal position of the first nonblank character. If the +contents are entirely blank, then this is the horizontal position of the +end of the line. +@end defun + +@deffn Command indent-to column &optional minimum +@comment !!Type Primitive Function +@comment !!SourceFile indent.c +This function indents from point with tabs and spaces until +@var{column} is reached. If @var{minimum} is specified and +non-@code{nil}, then at least that many spaces are inserted even if this +requires going beyond @var{column}. The value is the column at which +the inserted indentation ends. +@end deffn + +@defopt indent-tabs-mode +@comment !!SourceFile indent.c +If this variable is non-@code{nil}, indentation functions can insert +tabs as well as spaces. Otherwise, they insert only spaces. Setting +this variable automatically makes it local to the current buffer. +@end defopt + +@node Mode-Specific Indent +@subsection Indentation Controlled by Major Mode + + An important function of each major mode is to customize the @key{TAB} +key to indent properly for the language being edited. This section +describes the mechanism of the @key{TAB} key and how to control it. +The functions in this section return unpredictable values. + +@defvar indent-line-function +This variable's value is the function to be used by @key{TAB} (and +various commands) to indent the current line. The command +@code{indent-according-to-mode} does no more than call this function. + +In Lisp mode, the value is the symbol @code{lisp-indent-line}; in C +mode, @code{c-indent-line}; in Fortran mode, @code{fortran-indent-line}. +In Fundamental mode, Text mode, and many other modes with no standard +for indentation, the value is @code{indent-to-left-margin} (which is the +default value). +@end defvar + +@deffn Command indent-according-to-mode +This command calls the function in @code{indent-line-function} to +indent the current line in a way appropriate for the current major mode. +@end deffn + +@deffn Command indent-for-tab-command +This command calls the function in @code{indent-line-function} to indent +the current line; except that if that function is +@code{indent-to-left-margin}, it calls @code{insert-tab} instead. (That +is a trivial command which inserts a tab character.) +@end deffn + +@defvar left-margin +This variable is the column to which the default +@code{indent-line-function} will indent. (That function is +@code{indent-to-left-margin}.) In Fundamental mode, @key{LFD} indents +to this column. This variable automatically becomes buffer-local when +set in any fashion. +@end defvar + +@defun indent-to-left-margin +This is the default @code{indent-line-function}, used in Fundamental +mode, Text mode, etc. Its effect is to adjust the indentation at the +beginning of the current line to the value specified by the variable +@code{left-margin}. This may involve either inserting or deleting +whitespace. +@end defun + +@deffn Command newline-and-indent +@comment !!SourceFile simple.el +This function inserts a newline, then indents the new line (the one +following the newline just inserted) according to the major mode. + +It does indentation by calling the current @code{indent-line-function}. +In programming language modes, this is the same thing @key{TAB} does, +but in some text modes, where @key{TAB} inserts a tab, +@code{newline-and-indent} indents to the column specified by +@code{left-margin}. +@end deffn + +@deffn Command reindent-then-newline-and-indent +@comment !!SourceFile simple.el +This command reindents the current line, inserts a newline at point, +and then reindents the new line (the one following the newline just +inserted). + +This command does indentation on both lines according to the current +major mode, by calling the current value of @code{indent-line-function}. +In programming language modes, this is the same thing @key{TAB} does, +but in some text modes, where @key{TAB} inserts a tab, +@code{reindent-then-newline-and-indent} indents to the column specified +by @code{left-margin}. +@end deffn + +@node Region Indent +@subsection Indenting an Entire Region + + This section describes commands which indent all the lines in the +region. They return unpredictable values. + +@deffn Command indent-region start end to-column +This command indents each nonblank line starting between @var{start} +(inclusive) and @var{end} (exclusive). If @var{to-column} is +@code{nil}, @code{indent-region} indents each nonblank line by calling +the current mode's indentation function, the value of +@code{indent-line-function}. + +If @var{to-column} is non-@code{nil}, it should be an integer +specifying the number of columns of indentation; then this function +gives each line exactly that much indentation, by either adding or +deleting whitespace. + +If there is a fill prefix, @code{indent-region} indents each line +by making it start with the fill prefix. +@end deffn + +@defvar indent-region-function +The value of this variable is a function that can be used by +@code{indent-region} as a short cut. You should design the function so +that it will produce the same results as indenting the lines of the +region one by one, but presumably faster. + +If the value is @code{nil}, there is no short cut, and +@code{indent-region} actually works line by line. + +A short cut function is useful in modes such as C mode and Lisp mode, +where the @code{indent-line-function} must scan from the beginning of +the function: applying it to each line would be quadratic in time. The +short cut can update the scan information as it moves through the lines +indenting them; this takes linear time. In a mode where indenting a +line individually is fast, there is no need for a short cut. + +@code{indent-region} with a non-@code{nil} argument has a different +meaning and does not use this variable. +@end defvar + +@deffn Command indent-rigidly start end count +@comment !!SourceFile indent.el +This command indents all lines starting between @var{start} +(inclusive) and @var{end} (exclusive) sideways by @var{count} columns. +This ``preserves the shape'' of the affected region, moving it as a +rigid unit. Consequently, this command is useful not only for indenting +regions of unindented text, but also for indenting regions of formatted +code. + +For example, if @var{count} is 3, this command adds 3 columns of +indentation to each of the lines beginning in the region specified. + +In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses +@code{indent-rigidly} to indent the text copied from the message being +replied to. +@end deffn + +@defun indent-code-rigidly start end columns &optional nochange-regexp +This is like @code{indent-rigidly}, except that it doesn't alter lines +that start within strings or comments. + +In addition, it doesn't alter a line if @var{nochange-regexp} matches at +the beginning of the line (if @var{nochange-regexp} is non-@code{nil}). +@end defun + +@node Relative Indent +@subsection Indentation Relative to Previous Lines + + This section describes two commands which indent the current line +based on the contents of previous lines. + +@deffn Command indent-relative &optional unindented-ok +This command inserts whitespace at point, extending to the same +column as the next @dfn{indent point} of the previous nonblank line. An +indent point is a non-whitespace character following whitespace. The +next indent point is the first one at a column greater than the current +column of point. For example, if point is underneath and to the left of +the first non-blank character of a line of text, it moves to that column +by inserting whitespace. + +If the previous nonblank line has no next indent point (i.e., none at a +great enough column position), @code{indent-relative} either does +nothing (if @var{unindented-ok} is non-@code{nil}) or calls +@code{tab-to-tab-stop}. Thus, if point is underneath and to the right +of the last column of a short line of text, this command ordinarily +moves point to the next tab stop by inserting whitespace. + +The return value of @code{indent-relative} is unpredictable. + +In the following example, point is at the beginning of the second +line: + +@example +@group + This line is indented twelve spaces. +@point{}The quick brown fox jumped. +@end group +@end example + +@noindent +Evaluation of the expression @code{(indent-relative nil)} produces the +following: + +@example +@group + This line is indented twelve spaces. + @point{}The quick brown fox jumped. +@end group +@end example + + In this example, point is between the @samp{m} and @samp{p} of +@samp{jumped}: + +@example +@group + This line is indented twelve spaces. +The quick brown fox jum@point{}ped. +@end group +@end example + +@noindent +Evaluation of the expression @code{(indent-relative nil)} produces the +following: + +@example +@group + This line is indented twelve spaces. +The quick brown fox jum @point{}ped. +@end group +@end example +@end deffn + +@deffn Command indent-relative-maybe +@comment !!SourceFile indent.el +This command indents the current line like the previous nonblank line. +It calls @code{indent-relative} with @code{t} as the @var{unindented-ok} +argument. The return value is unpredictable. + +If the previous nonblank line has no indent points beyond the current +column, this command does nothing. +@end deffn + +@node Indent Tabs +@comment node-name, next, previous, up +@subsection Adjustable ``Tab Stops'' +@cindex tabs stops for indentation + + This section explains the mechanism for user-specified ``tab stops'' +and the mechanisms which use and set them. The name ``tab stops'' is +used because the feature is similar to that of the tab stops on a +typewriter. The feature works by inserting an appropriate number of +spaces and tab characters to reach the next tab stop column; it does not +affect the display of tab characters in the buffer (@pxref{Usual +Display}). Note that the @key{TAB} character as input uses this tab +stop feature only in a few major modes, such as Text mode. + +@deffn Command tab-to-tab-stop +This command inserts spaces or tabs up to the next tab stop column +defined by @code{tab-stop-list}. It searches the list for an element +greater than the current column number, and uses that element as the +column to indent to. It does nothing if no such element is found. +@end deffn + +@defopt tab-stop-list +This variable is the list of tab stop columns used by +@code{tab-to-tab-stops}. The elements should be integers in increasing +order. The tab stop columns need not be evenly spaced. + +Use @kbd{M-x edit-tab-stops} to edit the location of tab stops +interactively. +@end defopt + +@node Motion by Indent +@subsection Indentation-Based Motion Commands + + These commands, primarily for interactive use, act based on the +indentation in the text. + +@deffn Command back-to-indentation +@comment !!SourceFile simple.el +This command moves point to the first non-whitespace character in the +current line (which is the line in which point is located). It returns +@code{nil}. +@end deffn + +@deffn Command backward-to-indentation arg +@comment !!SourceFile simple.el +This command moves point backward @var{arg} lines and then to the +first nonblank character on that line. It returns @code{nil}. +@end deffn + +@deffn Command forward-to-indentation arg +@comment !!SourceFile simple.el +This command moves point forward @var{arg} lines and then to the first +nonblank character on that line. It returns @code{nil}. +@end deffn + +@node Case Changes +@comment node-name, next, previous, up +@section Case Changes +@cindex case changes + + The case change commands described here work on text in the current +buffer. @xref{Character Case}, for case conversion commands that work +on strings and characters. @xref{Case Table}, for how to customize +which characters are upper or lower case and how to convert them. + +@deffn Command capitalize-region start end +This function capitalizes all words in the region defined by +@var{start} and @var{end}. To capitalize means to convert each word's +first character to upper case and convert the rest of each word to lower +case. The function returns @code{nil}. + +If one end of the region is in the middle of a word, the part of the +word within the region is treated as an entire word. + +When @code{capitalize-region} is called interactively, @var{start} and +@var{end} are point and the mark, with the smallest first. + +@example +@group +---------- Buffer: foo ---------- +This is the contents of the 5th foo. +---------- Buffer: foo ---------- +@end group + +@group +(capitalize-region 1 44) +@result{} nil + +---------- Buffer: foo ---------- +This Is The Contents Of The 5th Foo. +---------- Buffer: foo ---------- +@end group +@end example +@end deffn + +@deffn Command downcase-region start end +This function converts all of the letters in the region defined by +@var{start} and @var{end} to lower case. The function returns +@code{nil}. + +When @code{downcase-region} is called interactively, @var{start} and +@var{end} are point and the mark, with the smallest first. +@end deffn + +@deffn Command upcase-region start end +This function converts all of the letters in the region defined by +@var{start} and @var{end} to upper case. The function returns +@code{nil}. + +When @code{upcase-region} is called interactively, @var{start} and +@var{end} are point and the mark, with the smallest first. +@end deffn + +@deffn Command capitalize-word count +This function capitalizes @var{count} words after point, moving point +over as it does. To capitalize means to convert each word's first +character to upper case and convert the rest of each word to lower case. +If @var{count} is negative, the function capitalizes the +@minus{}@var{count} previous words but does not move point. The value +is @code{nil}. + +If point is in the middle of a word, the part of word the before point +(if moving forward) or after point (if operating backward) is ignored. +The rest is treated as an entire word. + +When @code{capitalize-word} is called interactively, @var{count} is +set to the numeric prefix argument. +@end deffn + +@deffn Command downcase-word count +This function converts the @var{count} words after point to all lower +case, moving point over as it does. If @var{count} is negative, it +converts the @minus{}@var{count} previous words but does not move point. +The value is @code{nil}. + +When @code{downcase-word} is called interactively, @var{count} is set +to the numeric prefix argument. +@end deffn + +@deffn Command upcase-word count +This function converts the @var{count} words after point to all upper +case, moving point over as it does. If @var{count} is negative, it +converts the @minus{}@var{count} previous words but does not move point. +The value is @code{nil}. + +When @code{upcase-word} is called interactively, @var{count} is set to +the numeric prefix argument. +@end deffn + +@node Text Properties +@section Text Properties +@cindex text properties +@cindex attributes of text +@cindex properties of text + + Each character position in a buffer or a string can have a @dfn{text +property list}, much like the property list of a symbol (@pxref{Property +Lists}). The properties belong to a particular character at a +particular place, such as, the letter @samp{T} at the beginning of this +sentence or the first @samp{o} in @samp{foo}---if the same character +occurs in two different places, the two occurrences generally have +different properties. + + Each property has a name and a value. Both of these can be any Lisp +object, but the name is normally a symbol. The usual way to access the +property list is to specify a name and ask what value corresponds to it. + + If a character has a @code{category} property, we call it the +@dfn{category} of the character. It should be a symbol. The properties +of the symbol serve as defaults for the properties of the character. + + Copying text between strings and buffers preserves the properties +along with the characters; this includes such diverse functions as +@code{substring}, @code{insert}, and @code{buffer-substring}. + +@menu +* Examining Properties:: Looking at the properties of one character. +* Changing Properties:: Setting the properties of a range of text. +* Property Search:: Searching for where a property changes value. +* Special Properties:: Particular properties with special meanings. +* Sticky Properties:: How inserted text gets properties from + neighboring text. +* Saving Properties:: Saving text properties in files, and reading + them back. +* Not Intervals:: Why text properties do not use + Lisp-visible text intervals. +@end menu + +@node Examining Properties +@subsection Examining Text Properties + + The simplest way to examine text properties is to ask for the value of +a particular property of a particular character. For that, use +@code{get-text-property}. Use @code{text-properties-at} to get the +entire property list of a character. @xref{Property Search}, for +functions to examine the properties of a number of characters at once. + + These functions handle both strings and buffers. Keep in mind that +positions in a string start from 0, whereas positions in a buffer start +from 1. + +@defun get-text-property pos prop &optional object +This function returns the value of the @var{prop} property of the +character after position @var{pos} in @var{object} (a buffer or +string). The argument @var{object} is optional and defaults to the +current buffer. + +If there is no @var{prop} property strictly speaking, but the character +has a category which is a symbol, then @code{get-text-property} returns +the @var{prop} property of that symbol. +@end defun + +@defun get-char-property pos prop &optional object +This function is like @code{get-text-property}, except that it checks +overlays first and then text properties. @xref{Overlays}. + +The argument @var{object} may be a string, a buffer, or a window. If it +is a window, then the buffer displayed in that window is used for text +properties and overlays, but only the overlays active for that window +are considered. If @var{object} is a buffer, then all overlays in that +buffer are considered, as well as text properties. If @var{object} is a +string, only text properties are considered, since strings never have +overlays. +@end defun + +@defun text-properties-at position &optional object +This function returns the entire property list of the character at +@var{position} in the string or buffer @var{object}. If @var{object} is +@code{nil}, it defaults to the current buffer. +@end defun + +@node Changing Properties +@subsection Changing Text Properties + + The primitives for changing properties apply to a specified range of +text. The function @code{set-text-properties} (see end of section) sets +the entire property list of the text in that range; more often, it is +useful to add, change, or delete just certain properties specified by +name. + + Since text properties are considered part of the buffer's contents, and +can affect how the buffer looks on the screen, any change in the text +properties is considered a buffer modification. Buffer text property +changes are undoable (@pxref{Undo}). + +@defun add-text-properties start end props &optional object +This function modifies the text properties for the text between +@var{start} and @var{end} in the string or buffer @var{object}. If +@var{object} is @code{nil}, it defaults to the current buffer. + +The argument @var{props} specifies which properties to change. It +should have the form of a property list (@pxref{Property Lists}): a list +whose elements include the property names followed alternately by the +corresponding values. + +The return value is @code{t} if the function actually changed some +property's value; @code{nil} otherwise (if @var{props} is @code{nil} or +its values agree with those in the text). + +For example, here is how to set the @code{comment} and @code{face} +properties of a range of text: + +@example +(add-text-properties @var{start} @var{end} + '(comment t face highlight)) +@end example +@end defun + +@defun put-text-property start end prop value &optional object +This function sets the @var{prop} property to @var{value} for the text +between @var{start} and @var{end} in the string or buffer @var{object}. +If @var{object} is @code{nil}, it defaults to the current buffer. +@end defun + +@defun remove-text-properties start end props &optional object +This function deletes specified text properties from the text between +@var{start} and @var{end} in the string or buffer @var{object}. If +@var{object} is @code{nil}, it defaults to the current buffer. + +The argument @var{props} specifies which properties to delete. It +should have the form of a property list (@pxref{Property Lists}): a list +whose elements are property names alternating with corresponding values. +But only the names matter---the values that accompany them are ignored. +For example, here's how to remove the @code{face} property. + +@example +(remove-text-properties @var{start} @var{end} '(face nil)) +@end example + +The return value is @code{t} if the function actually changed some +property's value; @code{nil} otherwise (if @var{props} is @code{nil} or +if no character in the specified text had any of those properties). +@end defun + +@defun set-text-properties start end props &optional object +This function completely replaces the text property list for the text +between @var{start} and @var{end} in the string or buffer @var{object}. +If @var{object} is @code{nil}, it defaults to the current buffer. + +The argument @var{props} is the new property list. It should be a list +whose elements are property names alternating with corresponding values. + +After @code{set-text-properties} returns, all the characters in the +specified range have identical properties. + +If @var{props} is @code{nil}, the effect is to get rid of all properties +from the specified range of text. Here's an example: + +@example +(set-text-properties @var{start} @var{end} nil) +@end example +@end defun + +@node Property Search +@subsection Property Search Functions + +In typical use of text properties, most of the time several or many +consecutive characters have the same value for a property. Rather than +writing your programs to examine characters one by one, it is much +faster to process chunks of text that have the same property value. + +Here are functions you can use to do this. In all cases, @var{object} +defaults to the current buffer. + +For high performance, it's very important to use the @var{limit} +argument to these functions, especially the ones that search for a +single property---otherwise, they may spend a long time considering +changes in other properties while scanning to the end of the buffer. + +@defun next-property-change pos &optional object limit +The function scans the text forward from position @var{pos} in the +string or buffer @var{object} till it finds a change in some text +property, then returns the position of the change. In other words, it +returns the position of the first character beyond @var{pos} whose +properties are not identical to those of the character just after +@var{pos}. + +If @var{limit} is non-@code{nil}, then the scan ends at position +@var{limit}. If there is no property change before that point, +@code{next-property-change} returns @var{limit}. + +The value is @code{nil} if the properties remain unchanged all the way +to the end of @var{object} and @var{limit} is @code{nil}. + +If the value is non-@code{nil}, it is a position greater than or equal +to @var{pos}. The value equals @var{pos} only when @var{limit} equals +@var{pos}. + +Here is an example of how to scan the buffer by chunks of text within +which all properties are constant: + +@smallexample +(while (not (eobp)) + (let ((plist (text-properties-at (point))) + (next-change + (or (next-property-change (point) (current-buffer)) + (point-max)))) + @r{Process text from point to @var{next-change}@dots{}} + (goto-char next-change))) +@end smallexample +@end defun + +@defun next-single-property-change pos prop &optional object limit +The function scans the text forward from position @var{pos} in the +string or buffer @var{object} till it finds a change in the @var{prop} +property, then returns the position of the change. In other words, it +returns the position of the first character beyond @var{pos} whose +@var{prop} property differs from that of the character just after +@var{pos}. + +If @var{limit} is non-@code{nil}, then the scan ends at position +@var{limit}. If there is no property change before that point, +@code{next-single-property-change} returns @var{limit}. + +The value is @code{nil} if the property remains unchanged all the way to +the end of @var{object} and @var{limit} is @code{nil}. If the value is +non-@code{nil}, it is a position greater than or equal to @var{pos}; it +equals @var{pos} only if @var{limit} equals @var{pos}. +@end defun + +@defun previous-property-change pos &optional object limit +This is like @code{next-property-change}, but scans back from @var{pos} +instead of forward. If the value is non-@code{nil}, it is a position +less than or equal to @var{pos}; it equals @var{pos} only if @var{limit} +equals @var{pos}. + +Remember that a position is always between two characters; the position +returned by this function is between two characters with different +properties. +@end defun + +@defun previous-single-property-change pos prop &optional object limit +This is like @code{next-property-change}, but scans back from @var{pos} +instead of forward. If the value is non-@code{nil}, it is a position +less than or equal to @var{pos}; it equals @var{pos} only if @var{limit} +equals @var{pos}. +@end defun + +@defun text-property-any start end prop value &optional object +This function returns non-@code{nil} if at least one character between +@var{start} and @var{end} has a property @var{prop} whose value is +@var{value}. More precisely, it returns the position of the first such +character. Otherwise, it returns @code{nil}. + +The optional fifth argument, @var{object}, specifies the string or +buffer to scan. Positions are relative to @var{object}. The default +for @var{object} is the current buffer. +@end defun + +@defun text-property-not-all start end prop value &optional object +This function returns non-@code{nil} if at least one character between +@var{start} and @var{end} has a property @var{prop} whose value differs +from @var{value}. More precisely, it returns the position of the +first such character. Otherwise, it returns @code{nil}. + +The optional fifth argument, @var{object}, specifies the string or +buffer to scan. Positions are relative to @var{object}. The default +for @var{object} is the current buffer. +@end defun + +@node Special Properties +@subsection Properties with Special Meanings + +@table @code +@cindex category of text character +@kindex category @r{(text property)} +@item category +If a character has a @code{category} property, we call it the +@dfn{category} of the character. It should be a symbol. The properties +of the symbol serve as defaults for the properties of the character. + +@item face +@cindex face codes of text +@kindex face @r{(text property)} +You can use the property @code{face} to control the font and color of +text. @xref{Faces}, for more information. This feature is temporary; +in the future, we may replace it with other ways of specifying how to +display text. + +@item mouse-face +@kindex mouse-face @r{(text property)} +The property @code{mouse-face} is used instead of @code{face} when the +mouse is on or near the character. For this purpose, ``near'' means +that all text between the character and where the mouse is have the same +@code{mouse-face} property value. + +@item local-map +@cindex keymap of character +@kindex local-map @r{(text property)} +You can specify a different keymap for a portion of the text by means +of a @code{local-map} property. The property's value, for the character +after point, replaces the buffer's local map. @xref{Active Keymaps}. + +@item read-only +@cindex read-only character +@kindex read-only @r{(text property)} +If a character has the property @code{read-only}, then modifying that +character is not allowed. Any command that would do so gets an error. + +Insertion next to a read-only character is an error if inserting +ordinary text there would inherit the @code{read-only} property due to +stickiness. Thus, you can control permission to insert next to +read-only text by controlling the stickiness. @xref{Sticky Properties}. + +Since changing properties counts as modifying the buffer, it is not +possible to remove a @code{read-only} property unless you know the +special trick: bind @code{inhibit-read-only} to a non-@code{nil} value +and then remove the property. @xref{Read Only Buffers}. + +@item invisible +@kindex invisible @r{(text property)} +A non-@code{nil} @code{invisible} property means a character does not +appear on the screen. This works much like selective display. Details +of this feature are likely to change in future versions, so check the +@file{etc/NEWS} file in the version you are using. + +@item modification-hooks +@cindex change hooks for a character +@cindex hooks for changing a character +@kindex modification-hooks @r{(text property)} +If a character has the property @code{modification-hooks}, then its +value should be a list of functions; modifying that character calls all +of those functions. Each function receives two arguments: the beginning +and end of the part of the buffer being modified. Note that if a +particular modification hook function appears on several characters +being modified by a single primitive, you can't predict how many times +the function will be called. + +@item insert-in-front-hooks +@itemx insert-behind-hooks +@kindex insert-in-front-hooks @r{(text property)} +@kindex insert-behind-hooks @r{(text property)} +Assuming insertion is allowed, it then calls the functions +listed in the @code{insert-in-front-hooks} property of the following +character and in the @code{insert-behind-hooks} property of the +preceding character. These functions receive two arguments, the +beginning and end of the inserted text. + +See also @ref{Change Hooks}, for other hooks that are called +when you change text in a buffer. + +@item point-entered +@itemx point-left +@cindex hooks for motion of point +@kindex point-entered @r{(text property)} +@kindex point-left @r{(text property)} +The special properties @code{point-entered} and @code{point-left} +record hook functions that report motion of point. Each time point +moves, Emacs compares these two property values: + +@itemize @bullet +@item +the @code{point-left} property of the character after the old location, +and +@item +the @code{point-entered} property of the character after the new +location. +@end itemize + +@noindent +If these two values differ, each of them is called (if not @code{nil}) +with two arguments: the old value of point, and the new one. + +The same comparison is made for the characters before the old and new +locations. The result may be to execute two @code{point-left} functions +(which may be the same function) and/or two @code{point-entered} +functions (which may be the same function). The @code{point-left} +functions are always called before the @code{point-entered} functions. + +A primitive function may examine characters at various positions +without moving point to those positions. Only an actual change in the +value of point runs these hook functions. +@end table + +@defvar inhibit-point-motion-hooks +When this variable is non-@code{nil}, @code{point-left} and +@code{point-entered} hooks are not run. +@end defvar + +@node Sticky Properties +@subsection Stickiness of Text Properties +@cindex sticky text properties +@cindex inheritance of text properties + + Self-inserting characters normally take on the same properties as the +preceding character. This is called @dfn{inheritance} of properties. + + In a Lisp program, you can do insertion with inheritance or without, +depending on your choice of insertion primitive. The ordinary text +insertion functions such as @code{insert} do not inherit any properties. +They insert text with precisely the properties of the string being +inserted, and no others. This is correct for programs that copy text +from one context to another---for example, into or out of the kill +ring. To insert with inheritance, use the special primatives described +in this section. + + When you do insertion with inheritance, @emph{which} properties are +inherited depends on two specific properties: @code{front-sticky} and +@code{rear-nonsticky}. + + Insertion after a character inherits those of its properties that are +@dfn{rear-sticky}. Insertion before a character inherits those of its +properties that are @dfn{front-sticky}. By default, a text property is +rear-sticky but not front-sticky. Thus, the default is to inherit all +the properties of the preceding character, and nothing from the +following character. You can request different behavior by specifying +the stickiness of certain properties. + + If a character's @code{front-sticky} property is @code{t}, then all +its properties are front-sticky. If the @code{front-sticky} property is +a list, then the sticky properties of the character are those whose +names are in the list. For example, if a character has a +@code{front-sticky} property whose value is @code{(face read-only)}, +then insertion before the character can inherit its @code{face} property +and its @code{read-only} property, but no others. + + The @code{rear-nonsticky} works the opposite way. Every property is +rear-sticky by default, so the @code{rear-nonsticky} property says which +properties are @emph{not} rear-sticky. If a character's +@code{rear-nonsticky} property is @code{t}, then none of its properties +are rear-sticky. If the @code{rear-nonsticky} property is a list, +properties are rear-sticky @emph{unless} their names are in the list. + + When you insert text with inheritance, it inherits all the rear-sticky +properties of the preceding character, and all the front-sticky +properties of the following character. The previous character's +properties take precedence when both sides offer different sticky values +for the same property. + + Here are the functions that insert text with inheritance of properties: + +@defun insert-and-inherit &rest strings +Insert the strings @var{strings}, just like the function @code{insert}, +but inherit any sticky properties from the adjoining text. +@end defun + +@defun insert-before-markers-and-inherit &rest strings +Insert the strings @var{strings}, just like the function +@code{insert-before-markers}, but inherit any sticky properties from the +adjoining text. +@end defun + +@node Saving Properties +@subsection Saving Text Properites in Files +@cindex text properties in files +@cindex saving text properties + + You can save text properties in files, and restore text properties +when inserting the files, using these two hooks: + +@defvar write-region-annotation-functions +This variable's value is a list of functions for @code{write-region} to +run to encode text properties in some fashion as annotations to the text +being written in the file. @xref{Writing to Files}. + +Each function in the list is called with two arguments: the start and +end of the region to be written. These functions should not alter the +contents of the buffer. Instead, they should return lists indicating +annotations to write in the file in addition to the text in the +buffer. + +Each function should return a list of elements of the form +@code{(@var{position} . @var{string})}, where @var{position} is an +integer specifying the relative position in the text to be written, and +@var{string} is the annotation to add there. + +Each list returned by one of these functions must be already sorted in +increasing order by @var{position}. If there is more than one function, +@code{write-region} merges the lists destructively into one sorted list. + +When @code{write-region} actually writes the text from the buffer to the +file, it intermixes the specified annotations at the corresponding +positions. All this takes place without modifying the buffer. +@end defvar + +@defvar after-insert-file-functions +This variable holds a list of functions for @code{insert-file-contents} +to call after inserting a file's contents. These functions should scan +the inserted text for annotations, and convert them to the text +properties they stand for. + +Each function receives one argument, the length of the inserted text; +point indicates the start of that text. The function should scan that +text for annotations, delete them, and create the text properties that +the annotations specify. The function should return the updated length +of the inserted text, as it stands after those changes. The value +returned by one function becomes the argument to the next function. + +These functions should always return with point at the beginning of +the inserted text. + +The intended use of @code{after-insert-file-functions} is for converting +some sort of textual annotations into actual text properties. But other +uses may be possible. +@end defvar + +We invite users to write Lisp programs to store and retrieve text +properties in files, using these hooks, and thus to experiment with +various data formats and find good ones. Eventually we hope users +will produce good, general extensions we can install in Emacs. + +We suggest not trying to handle arbitrary Lisp objects as property +names or property values---because a program that general is probably +difficult to write, and slow. Instead, choose a set of possible data +types that are reasonably flexible, and not too hard to encode. + +@node Not Intervals +@subsection Why Text Properties are not Intervals +@cindex intervals + + Some editors that support adding attributes to text in the buffer do +so by letting the user specify ``intervals'' within the text, and adding +the properties to the intervals. Those editors permit the user or the +programmer to determine where individual intervals start and end. We +deliberately provided a different sort of interface in Emacs Lisp to +avoid certain paradoxical behavior associated with text modification. + + If the actual subdivision into intervals is meaningful, that means you +can distinguish between a buffer that is just one interval with a +certain property, and a buffer containing the same text subdivided into +two intervals, both of which have that property. + + Suppose you take the buffer with just one interval and kill part of +the text. The text remaining in the buffer is one interval, and the +copy in the kill ring (and the undo list) becomes a separate interval. +Then if you yank back the killed text, you get two intervals with the +same properties. Thus, editing does not preserve the distinction +between one interval and two. + + Suppose we ``fix'' this problem by coalescing the two intervals when +the text is inserted. That works fine if the buffer originally was a +single interval. But suppose instead that we have two adjacent +intervals with the same properties, and we kill the text of one interval +and yank it back. The same interval-coalescence feature that rescues +the other case causes trouble in this one: after yanking, we have just +one interval. One again, editing does not preserve the distinction +between one interval and two. + + Insertion of text at the border between intervals also raises +questions that have no satisfactory answer. + + However, it is easy to arrange for editing to behave consistently for +questions of the form, ``What are the properties of this character?'' +So we have decided these are the only questions that make sense; we have +not implemented asking questions about where intervals start or end. + + In practice, you can usually use the property search functions in +place of explicit interval boundaries. You can think of them as finding +the boundaries of intervals, assuming that intervals are always +coalesced whenever possible. @xref{Property Search}. + + Emacs also provides explicit intervals as a presentation feature; see +@ref{Overlays}. + +@node Substitution +@section Substituting for a Character Code + + The following functions replace characters within a specified region +based on their character codes. + +@defun subst-char-in-region start end old-char new-char &optional noundo +@cindex replace characters +This function replaces all occurrences of the character @var{old-char} +with the character @var{new-char} in the region of the current buffer +defined by @var{start} and @var{end}. + +@cindex Outline mode +@cindex undo avoidance +If @var{noundo} is non-@code{nil}, then @code{subst-char-in-region} +does not record the change for undo and does not mark the buffer as +modified. This feature is useful for changes which are not considered +significant, such as when Outline mode changes visible lines to +invisible lines and vice versa. + +@code{subst-char-in-region} does not move point and returns +@code{nil}. + +@example +@group +---------- Buffer: foo ---------- +This is the contents of the buffer before. +---------- Buffer: foo ---------- +@end group + +@group +(subst-char-in-region 1 20 ?i ?X) + @result{} nil + +---------- Buffer: foo ---------- +ThXs Xs the contents of the buffer before. +---------- Buffer: foo ---------- +@end group +@end example +@end defun + +@defun translate-region start end table +This function applies a translation table to the characters in the +buffer between positions @var{start} and @var{end}. + +The translation table @var{table} is a string; @code{(aref @var{table} +@var{ochar})} gives the translated character corresponding to +@var{ochar}. If the length of @var{table} is less than 256, any +characters with codes larger than the length of @var{table} are not +altered by the translation. + +The return value of @code{translate-region} is the number of +characters which were actually changed by the translation. This does +not count characters which were mapped into themselves in the +translation table. + +This function is available in Emacs versions 19 and later. +@end defun + +@node Registers +@section Registers +@cindex registers + + A register is a sort of variable used in Emacs editing that can hold a +marker, a string, a rectangle, a window configuration (of one frame), or +a frame configuration (of all frames). Each register is named by a +single character. All characters, including control and meta characters +(but with the exception of @kbd{C-g}), can be used to name registers. +Thus, there are 255 possible registers. A register is designated in +Emacs Lisp by a character which is its name. + + The functions in this section return unpredictable values unless +otherwise stated. +@c Will change in version 19 + +@defvar register-alist +This variable is an alist of elements of the form @code{(@var{name} . +@var{contents})}. Normally, there is one element for each Emacs +register that has been used. + +The object @var{name} is a character (an integer) identifying the +register. The object @var{contents} is a string, marker, or list +representing the register contents. A string represents text stored in +the register. A marker represents a position. A list represents a +rectangle; its elements are strings, one per line of the rectangle. +@end defvar + +@defun get-register reg +This function returns the contents of the register +@var{reg}, or @code{nil} if it has no contents. +@end defun + +@defun set-register reg value +This function sets the contents of register @var{reg} to @var{value}. +A register can be set to any value, but the other register functions +expect only certain data types. The return value is @var{value}. +@end defun + +@deffn Command view-register reg +This command displays what is contained in register @var{reg}. +@end deffn + +@ignore +@deffn Command point-to-register reg +This command stores both the current location of point and the current +buffer in register @var{reg} as a marker. +@end deffn + +@deffn Command jump-to-register reg +@deffnx Command register-to-point reg +@comment !!SourceFile register.el +This command restores the status recorded in register @var{reg}. + +If @var{reg} contains a marker, it moves point to the position stored in +the marker. Since both the buffer and the location within the buffer +are stored by the @code{point-to-register} function, this command can +switch you to another buffer. + +If @var{reg} contains a window configuration or a frame configuration. +@code{jump-to-register} restores that configuration. +@end deffn +@end ignore + +@deffn Command insert-register reg &optional beforep +This command inserts contents of register @var{reg} into the current +buffer. + +Normally, this command puts point before the inserted text, and the +mark after it. However, if the optional second argument @var{beforep} +is non-@code{nil}, it puts the mark before and point after. +You can pass a non-@code{nil} second argument @var{beforep} to this +function interactively by supplying any prefix argument. + +If the register contains a rectangle, then the rectangle is inserted +with its upper left corner at point. This means that text is inserted +in the current line and underneath it on successive lines. + +If the register contains something other than saved text (a string) or +a rectangle (a list), currently useless things happen. This may be +changed in the future. +@end deffn + +@ignore +@deffn Command copy-to-register reg start end &optional delete-flag +This command copies the region from @var{start} to @var{end} into +register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes +the region from the buffer after copying it into the register. +@end deffn + +@deffn Command prepend-to-register reg start end &optional delete-flag +This command prepends the region from @var{start} to @var{end} into +register @var{reg}. If @var{delete-flag} is non-@code{nil}, it deletes +the region from the buffer after copying it to the register. +@end deffn + +@deffn Command append-to-register reg start end &optional delete-flag +This command appends the region from @var{start} to @var{end} to the +text already in register @var{reg}. If @var{delete-flag} is +non-@code{nil}, it deletes the region from the buffer after copying it +to the register. +@end deffn + +@deffn Command copy-rectangle-to-register reg start end &optional delete-flag +This command copies a rectangular region from @var{start} to @var{end} +into register @var{reg}. If @var{delete-flag} is non-@code{nil}, it +deletes the region from the buffer after copying it to the register. +@end deffn + +@deffn Command window-configuration-to-register reg +This function stores the window configuration of the selected frame in +register @var{reg}. +@end deffn + +@deffn Command frame-configuration-to-register reg +This function stores the current frame configuration in register +@var{reg}. +@end deffn +@end ignore + +@node Change Hooks +@section Change Hooks +@cindex change hooks +@cindex hooks for text changes + + These hook variables let you arrange to take notice of all changes in +all buffers (or in a particular buffer, if you make them buffer-local). +See also @ref{Special Properties}, for how to detect changes to specific +parts of the text. + + The functions you use in these hooks should save and restore the match +data if they do anything that uses regular expressions; otherwise, they +will interfere in bizarre ways with the editing operations that call +them. + +@defvar before-change-function +If this variable is non-@code{nil}, then it should be a function; the +function is called before any buffer modification. Its arguments are +the beginning and end of the region that is about to change, +represented as integers. The buffer that is about to change is always +the current buffer. +@end defvar + +@defvar after-change-function +If this variable is non-@code{nil}, then it should be a function; the +function is called after any buffer modification. It receives three +arguments: the beginning and end of the region just changed, and the +length of the text that existed before the change. (To get the +current length, subtract the region beginning from the region end.) +All three arguments are integers. The buffer that's about to change +is always the current buffer. +@end defvar + +Both of these variables are temporarily bound to @code{nil} during the +time that either of these hooks is running. This means that if one of +these functions changes the buffer, that change won't run these +functions. If you do want the hook function to run recursively, +design your hook functions to bind these variables back to their usual +values. + +@defvar first-change-hook +This variable is a normal hook that is run whenever a buffer is changed +that was previously in the unmodified state. +@end defvar + + The variables described in this section are meaningful only starting +with Emacs version 19.