diff options
Diffstat (limited to 'lispref')
53 files changed, 0 insertions, 49699 deletions
diff --git a/lispref/=buffer-local.texi b/lispref/=buffer-local.texi deleted file mode 100644 index 4c4e0ca4362..00000000000 --- a/lispref/=buffer-local.texi +++ /dev/null @@ -1,94 +0,0 @@ -@c -*-texinfo-*- -@setfilename ../info/locals -@node Standard Buffer-Local Variables, Standard Keymaps, Standard Errors, Top -@appendix Standard Buffer-Local Variables - - The table below shows all of the variables that are automatically -local (when set) in each buffer in Emacs Version 18 with the common -packages loaded. - -@table @code -@item abbrev-mode -@xref{Abbrevs}. - -@item auto-fill-function -@xref{Auto Filling}. - -@item buffer-auto-save-file-name -@xref{Auto-Saving}. - -@item buffer-backed-up -@xref{Backup Files}. - -@item buffer-display-table -@xref{Active Display Table}. - -@item buffer-file-name -@xref{Buffer File Name}. - -@item buffer-file-truename -@xref{Buffer File Name}. - -@item buffer-read-only -@xref{Read Only Buffers}. - -@item buffer-saved-size -@xref{Point}. - -@item case-fold-search -@xref{Searching and Case}. - -@item ctl-arrow -@xref{Control Char Display}. - -@item default-directory -@xref{System Environment}. - -@item fill-column -@xref{Auto Filling}. - -@item left-margin -@xref{Indentation}. - -@item list-buffers-directory -@xref{Buffer File Name}. - -@item local-abbrev-table -@xref{Abbrevs}. - -@item major-mode -@xref{Mode Help}. - -@item mark-ring -@xref{The Mark}. - -@item minor-modes -@xref{Minor Modes}. - -@item mode-name -@xref{Mode Line Variables}. - -@item overwrite-mode -@xref{Insertion}. - -@item paragraph-separate -@xref{Standard Regexps}. - -@item paragraph-start -@xref{Standard Regexps}. - -@item require-final-newline -@xref{Insertion}. - -@item selective-display -@xref{Selective Display}. - -@item selective-display-ellipses -@xref{Selective Display}. - -@item tab-width -@xref{Control Char Display}. - -@item truncate-lines -@xref{Truncation}. -@end table diff --git a/lispref/Makefile.in b/lispref/Makefile.in deleted file mode 100644 index f00ad600f6f..00000000000 --- a/lispref/Makefile.in +++ /dev/null @@ -1,129 +0,0 @@ -# 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 -MAKE=make - -# 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.4.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 - -# The info file is named `elisp'. -# We depend on makeinfo.c rather than makeinfo -- there's no need to rebuild -# everything just because makeinfo isn't part of the distribution. - -elisp: $(srcs) index.texi makeinfo.c - $(MAKE) makeinfo - rm -f elisp-* - ./makeinfo elisp.texi - -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 - -install: elisp - ./mkinstalldirs $(infodir) - cp 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 - -maintainer-clean: clean - rm -f elisp elisp-* - -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) - -(cd temp/$(manual); rm -f texindex.c makeinfo.c mkinstalldirs) - cp texindex.c makeinfo.c mkinstalldirs 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 diff --git a/lispref/README b/lispref/README deleted file mode 100644 index ba603cfc0b5..00000000000 --- a/lispref/README +++ /dev/null @@ -1,50 +0,0 @@ -README for Edition 2.4 of the Emacs Lisp Reference Manual. - -* This directory contains the texinfo source files for the Reference -Manual, make-permuted-index, and the latest version of texinfo.tex, -which handles forms that cannot be handled by the older versions of -texinfo.tex. Also, it contains makeinfo.c. - -* Report Lisp Manual bugs to bug-lisp-manual@prep.ai.mit.edu. We -don't read these bug reports until it's time for a new edition. To -report other Emacs bugs, use bug-gnu-emacs@prep.ai.mit.edu. -To ask questions, use the newsgroup gnu.emacs.help. - -* The Emacs Lisp Reference Manual is quite large. It totals around -700 pages in smallbook format; the info files total almost two -megabytes. - -* You can format this manual either for Info or for printing hardcopy -using TeX. - -* You can buy nicely printed copies from the Free Software Foundation. -For info, send mail to gnu@prep.ai.mit.edu or phone 617-542-5942. -Buying a manual from the Free Software Foundation helps support our -GNU development work. - -** This distribution contains a Makefile that you can use with GNU Make. -Otherwise, here are detailed instructions: - -** HARDCOPY: A copy of the version of `texinfo.tex' that formats this -manual is included in this distribution. - -The master file for formatting this manual for Tex is called -`elisp.texi'. It contains @include commands to include all the -chapters that make up the manual. In addition, `elisp.texi' has -the title page in a new format designed by Karl Berry, using the -@titlespec command. - -To create a DVI file with a sorted index, execute the following -commands in the shell: - -% make index.texi -% make elisp.dvi - -*** To create a DVI file with a permuted index, you may experiment -with `make-permuted-index'. - -** INFO: A copy of makeinfo.c that will format this manual for Info is -included in this distribution. This program is written in C and can -be used separately from Emacs. `makeinfo' produces much better error -messages than the old `texinfo-format-buffer'. You can run `makeinfo' -it on the `elisp.texi' file. diff --git a/lispref/abbrevs.texi b/lispref/abbrevs.texi deleted file mode 100644 index 914e2659450..00000000000 --- a/lispref/abbrevs.texi +++ /dev/null @@ -1,344 +0,0 @@ -@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/abbrevs -@node Abbrevs, Processes, Syntax Tables, Top -@chapter Abbrevs And Abbrev Expansion -@cindex abbrev -@cindex abbrev table - - An abbreviation or @dfn{abbrev} is a string of characters that may be -expanded to a longer string. The user can insert the abbrev string and -find it replaced automatically with the expansion of the abbrev. This -saves typing. - - The set of abbrevs currently in effect is recorded in an @dfn{abbrev -table}. Each buffer has a local abbrev table, but normally all buffers -in the same major mode share one abbrev table. There is also a global -abbrev table. Normally both are used. - - An abbrev table is represented as an obarray containing a symbol for -each abbreviation. The symbol's name is the abbreviation; its value is -the expansion; its function definition is the hook function to do the -expansion (@pxref{Defining Abbrevs}); its property list cell contains -the use count, the number of times the abbreviation has been expanded. -Because these symbols are not interned in the usual obarray, they will -never appear as the result of reading a Lisp expression; in fact, -normally they are never used except by the code that handles abbrevs. -Therefore, it is safe to use them in an extremely nonstandard way. -@xref{Creating Symbols}. - - For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev -Mode, emacs, The GNU Emacs Manual}. - -@menu -* Abbrev Mode:: Setting up Emacs for abbreviation. -* Tables: Abbrev Tables. Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Files: Abbrev Files. Saving abbrevs in files. -* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. -@end menu - -@node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs -@comment node-name, next, previous, up -@section Setting Up Abbrev Mode - - Abbrev mode is a minor mode controlled by the value of the variable -@code{abbrev-mode}. - -@defvar abbrev-mode -A non-@code{nil} value of this variable turns on the automatic expansion -of abbrevs when their abbreviations are inserted into a buffer. -If the value is @code{nil}, abbrevs may be defined, but they are not -expanded automatically. - -This variable automatically becomes local when set in any fashion. -@end defvar - -@defvar default-abbrev-mode -This is the value of @code{abbrev-mode} for buffers that do not override it. -This is the same as @code{(default-value 'abbrev-mode)}. -@end defvar - -@node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs -@section Abbrev Tables - - This section describes how to create and manipulate abbrev tables. - -@defun make-abbrev-table -This function creates and returns a new, empty abbrev table---an obarray -containing no symbols. It is a vector filled with zeros. -@end defun - -@defun clear-abbrev-table table -This function undefines all the abbrevs in abbrev table @var{table}, -leaving it empty. The function returns @code{nil}. -@end defun - -@defun define-abbrev-table tabname definitions -This function defines @var{tabname} (a symbol) as an abbrev table name, -i.e., as a variable whose value is an abbrev table. It defines abbrevs -in the table according to @var{definitions}, a list of elements of the -form @code{(@var{abbrevname} @var{expansion} @var{hook} -@var{usecount})}. The value is always @code{nil}. -@end defun - -@defvar abbrev-table-name-list -This is a list of symbols whose values are abbrev tables. -@code{define-abbrev-table} adds the new abbrev table name to this list. -@end defvar - -@defun insert-abbrev-table-description name &optional human -This function inserts before point a description of the abbrev table -named @var{name}. The argument @var{name} is a symbol whose value is an -abbrev table. The value is always @code{nil}. - -If @var{human} is non-@code{nil}, the description is human-oriented. -Otherwise the description is a Lisp expression---a call to -@code{define-abbrev-table} that would define @var{name} exactly as it -is currently defined. -@end defun - -@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs -@comment node-name, next, previous, up -@section Defining Abbrevs - - These functions define an abbrev in a specified abbrev table. -@code{define-abbrev} is the low-level basic function, while -@code{add-abbrev} is used by commands that ask for information from the -user. - -@defun add-abbrev table type arg -This function adds an abbreviation to abbrev table @var{table} based on -information from the user. The argument @var{type} is a string -describing in English the kind of abbrev this will be (typically, -@code{"global"} or @code{"mode-specific"}); this is used in prompting -the user. The argument @var{arg} is the number of words in the -expansion. - -The return value is the symbol that internally represents the new -abbrev, or @code{nil} if the user declines to confirm redefining an -existing abbrev. -@end defun - -@defun define-abbrev table name expansion hook -This function defines an abbrev in @var{table} named @var{name}, to -expand to @var{expansion}, and call @var{hook}. The return value is an -uninterned symbol that represents the abbrev inside Emacs; its name is -@var{name}. - -The argument @var{name} should be a string. The argument -@var{expansion} should be a string, or @code{nil} to undefine the -abbrev. - -The argument @var{hook} is a function or @code{nil}. If @var{hook} is -non-@code{nil}, then it is called with no arguments after the abbrev is -replaced with @var{expansion}; point is located at the end of -@var{expansion} when @var{hook} is called. - -The use count of the abbrev is initialized to zero. -@end defun - -@defopt only-global-abbrevs -If this variable is non-@code{nil}, it means that the user plans to use -global abbrevs only. This tells the commands that define mode-specific -abbrevs to define global ones instead. This variable does not alter the -behavior of the functions in this section; it is examined by their -callers. -@end defopt - -@node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs -@section Saving Abbrevs in Files - - A file of saved abbrev definitions is actually a file of Lisp code. -The abbrevs are saved in the form of a Lisp program to define the same -abbrev tables with the same contents. Therefore, you can load the file -with @code{load} (@pxref{How Programs Do Loading}). However, the -function @code{quietly-read-abbrev-file} is provided as a more -convenient interface. - - User-level facilities such as @code{save-some-buffers} can save -abbrevs in a file automatically, under the control of variables -described here. - -@defopt abbrev-file-name -This is the default file name for reading and saving abbrevs. -@end defopt - -@defun quietly-read-abbrev-file filename -This function reads abbrev definitions from a file named @var{filename}, -previously written with @code{write-abbrev-file}. If @var{filename} is -@code{nil}, the file specified in @code{abbrev-file-name} is used. -@code{save-abbrevs} is set to @code{t} so that changes will be saved. - -This function does not display any messages. It returns @code{nil}. -@end defun - -@defopt save-abbrevs -A non-@code{nil} value for @code{save-abbrev} means that Emacs should -save abbrevs when files are saved. @code{abbrev-file-name} specifies -the file to save the abbrevs in. -@end defopt - -@defvar abbrevs-changed -This variable is set non-@code{nil} by defining or altering any -abbrevs. This serves as a flag for various Emacs commands to offer to -save your abbrevs. -@end defvar - -@deffn Command write-abbrev-file filename -Save all abbrev definitions, in all abbrev tables, in the file -@var{filename}, in the form of a Lisp program that when loaded will -define the same abbrevs. This function returns @code{nil}. -@end deffn - -@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs -@comment node-name, next, previous, up -@section Looking Up and Expanding Abbreviations - - Abbrevs are usually expanded by commands for interactive use, -including @code{self-insert-command}. This section describes the -subroutines used in writing such functions, as well as the variables -they use for communication. - -@defun abbrev-symbol abbrev &optional table -This function returns the symbol representing the abbrev named -@var{abbrev}. The value returned is @code{nil} if that abbrev is not -defined. The optional second argument @var{table} is the abbrev table -to look it up in. If @var{table} is @code{nil}, this function tries -first the current buffer's local abbrev table, and second the global -abbrev table. -@end defun - -@defun abbrev-expansion abbrev &optional table -This function returns the string that @var{abbrev} would expand into (as -defined by the abbrev tables used for the current buffer). The optional -argument @var{table} specifies the abbrev table to use, as in -@code{abbrev-symbol}. -@end defun - -@deffn Command expand-abbrev -This command expands the abbrev before point, if any. -If point does not follow an abbrev, this command does nothing. -The command returns @code{t} if it did expansion, @code{nil} otherwise. -@end deffn - -@deffn Command abbrev-prefix-mark &optional arg -Mark current point as the beginning of an abbrev. The next call to -@code{expand-abbrev} will use the text from here to point (where it is -then) as the abbrev to expand, rather than using the previous word as -usual. -@end deffn - -@defopt abbrev-all-caps -When this is set non-@code{nil}, an abbrev entered entirely in upper -case is expanded using all upper case. Otherwise, an abbrev entered -entirely in upper case is expanded by capitalizing each word of the -expansion. -@end defopt - -@defvar abbrev-start-location -This is the buffer position for @code{expand-abbrev} to use as the start -of the next abbrev to be expanded. (@code{nil} means use the word -before point instead.) @code{abbrev-start-location} is set to -@code{nil} each time @code{expand-abbrev} is called. This variable is -also set by @code{abbrev-prefix-mark}. -@end defvar - -@defvar abbrev-start-location-buffer -The value of this variable is the buffer for which -@code{abbrev-start-location} has been set. Trying to expand an abbrev -in any other buffer clears @code{abbrev-start-location}. This variable -is set by @code{abbrev-prefix-mark}. -@end defvar - -@defvar last-abbrev -This is the @code{abbrev-symbol} of the last abbrev expanded. This -information is left by @code{expand-abbrev} for the sake of the -@code{unexpand-abbrev} command. -@end defvar - -@defvar last-abbrev-location -This is the location of the last abbrev expanded. This contains -information left by @code{expand-abbrev} for the sake of the -@code{unexpand-abbrev} command. -@end defvar - -@defvar last-abbrev-text -This is the exact expansion text of the last abbrev expanded, after case -conversion (if any). Its value is @code{nil} if the abbrev has already -been unexpanded. This contains information left by @code{expand-abbrev} -for the sake of the @code{unexpand-abbrev} command. -@end defvar - -@c Emacs 19 feature -@defvar pre-abbrev-expand-hook -This is a normal hook whose functions are executed, in sequence, just -before any expansion of an abbrev. @xref{Hooks}. Since it is a normal -hook, the hook functions receive no arguments. However, they can find -the abbrev to be expanded by looking in the buffer before point. -@end defvar - - The following sample code shows a simple use of -@code{pre-abbrev-expand-hook}. If the user terminates an abbrev with a -punctuation character, the hook function asks for confirmation. Thus, -this hook allows the user to decide whether to expand the abbrev, and -aborts expansion if it is not confirmed. - -@smallexample -(add-hook 'pre-abbrev-expand-hook 'query-if-not-space) - -;; @r{This is the function invoked by @code{pre-abbrev-expand-hook}.} - -;; @r{If the user terminated the abbrev with a space, the function does} -;; @r{nothing (that is, it returns so that the abbrev can expand). If the} -;; @r{user entered some other character, this function asks whether} -;; @r{expansion should continue.} - -;; @r{If the user answers the prompt with @kbd{y}, the function returns} -;; @r{@code{nil} (because of the @code{not} function), but that is} -;; @r{acceptable; the return value has no effect on expansion.} - -(defun query-if-not-space () - (if (/= ?\ (preceding-char)) - (if (not (y-or-n-p "Do you want to expand this abbrev? ")) - (error "Not expanding this abbrev")))) -@end smallexample - -@node Standard Abbrev Tables, , Abbrev Expansion, Abbrevs -@comment node-name, next, previous, up -@section Standard Abbrev Tables - - Here we list the variables that hold the abbrev tables for the -preloaded major modes of Emacs. - -@defvar global-abbrev-table -This is the abbrev table for mode-independent abbrevs. The abbrevs -defined in it apply to all buffers. Each buffer may also have a local -abbrev table, whose abbrev definitions take precedence over those in the -global table. -@end defvar - -@defvar local-abbrev-table -The value of this buffer-local variable is the (mode-specific) -abbreviation table of the current buffer. -@end defvar - -@defvar fundamental-mode-abbrev-table -This is the local abbrev table used in Fundamental mode; in other words, -it is the local abbrev table in all buffers in Fundamental mode. -@end defvar - -@defvar text-mode-abbrev-table -This is the local abbrev table used in Text mode. -@end defvar - -@defvar c-mode-abbrev-table -This is the local abbrev table used in C mode. -@end defvar - -@defvar lisp-mode-abbrev-table -This is the local abbrev table used in Lisp mode and Emacs Lisp mode. -@end defvar diff --git a/lispref/anti.texi b/lispref/anti.texi deleted file mode 100644 index ca94cf3d196..00000000000 --- a/lispref/anti.texi +++ /dev/null @@ -1,619 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1993 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Antinews, Index, Standard Hooks, Top -@appendix Emacs 18 Antinews - -For those users who live backwards in time, here is information about -downgrading to Emacs version 18. We hope you will enjoy the greater -simplicity that results from the absence of many Emacs 19 features. - -@section Old Features in the Lisp Language - -The following functions are missing or different in Emacs version 18. - -@itemize @bullet -@item -The functions @code{delete}, @code{member}, @code{indirect-function}, -@code{map-y-or-n-p}, and @code{invocation-name} have been removed. - -@item -The function @code{read} now skips a terminator character that -terminates a symbol when reading from a buffer. Thus, if you use -@code{read} on a buffer containing @samp{foo(bar)} following point, it -returns @code{foo} and leaves point after the open-parenthesis. This -means there's no way you can properly read the list @samp{(bar)}, but -that's the way the cookie crumbles. - -Because of this simplification, it's no longer necessary for an input -stream function to accept an optional argument. In Emacs 18, an input -stream is always called with no arguments, and should always return -the next character of input. - -@item -The function @code{documentation} takes just one argument; -@code{documentation-property} takes just two. - -@item -@code{random} no longer has the optional argument @var{n}. - -@item -You can no longer arrange to run a hook if a particular Lisp library is -loaded. The variable @code{after-load-alist} and the function -@code{eval-after-load} have been removed. - -@item -The function @code{autoload} no longer supports autoloading a keymap. - -@item -``Magic'' comments of the form @samp{;;;###autoload} are now just -comments. They don't do anything in particular except look pretty. -If you want a function to be autoloaded by default, edit @file{loaddefs.h} -by hand. What do you think editors are for? - -@item -We took out the @samp{%S} from the @code{format} function, and the -optional argument @var{noescap} from @code{prin1-to-string}. We removed -the @code{print-level} variable. -@end itemize - -@section Compilation Features - -@itemize @bullet -@item -Inline functions are nonexistent in Emacs 18. We find they make the -calling function unnecessarily large. (Small size is one of the -features of Emacs 18.) - -@item -We eliminated the two special forms, @code{eval-when-compile} and -@code{eval-and-compile}, as well as the @code{compile-defun} command. - -@item -When you load a Lisp file or library, you will no longer receive a -warning if the directory contains both a @samp{.elc} file and a new -@samp{.el} file that is newer. So be on your toes. - -@item -We removed the special data type for byte-code functions. Compiled -functions now work by means of an interpreted function which calls -the function @code{bytecode}. That function runs the byte code -interpreter. -@end itemize - -@section Floating Point Numbers - -Emacs 18 doesn't have or need floating point arithmetic built in. -It has a handy Lisp program that allows you to emulate floating point. -You'll have to write programs specially to use it, though. - -As a result, certain macros, functions, and predicates no longer handle -specifications for floating point numbers. - -@itemize @bullet -@item -The function @code{string-to-number}, the predicate @code{floatp}, and -the variable @code{float-output-format} have all been eliminated. - -@item -The functions @code{float}, @code{truncate}, @code{floor}, @code{ceil}, -@code{round}, and @code{logb} do not exist; neither do the functions -@code{abs}, @code{cos}, @code{sin}, @code{tan}, @code{acos}, -@code{asin}, @code{atan}, @code{exp}, @code{expt}, @code{log10}, -@code{log}, or @code{sqrt}. - -@item -The @code{format} function no longer handles the specifications -@samp{%e}, @samp{%f} and @samp{%g} for printing floating point numbers; -likewise for @code{message}. -@end itemize - -@section Changes in Basic Editing Functions - -@itemize @bullet -@item -@code{kill-new} and @code{kill-append}, the primitives for putting text -in the kill ring, have been eliminated. -@c @code{kill-append} seems to exist as a non-documented (no doc string) -@c primitive in emacs 18. but news.texi said it was new for 19. - -@item -The variables @code{interprogram-paste-function} and -@code{interprogram-cut-function} have been removed in Emacs 18. - -In addition, there's no need for @code{mark-active} and -@code{deactivate-mark} because there is no Transient Mark mode. We also -removed the hooks @code{activate-mark-hook} and -@code{deactivate-mark-hook}. - -@item -The @code{kill-region} function can no longer be used in read-only -buffers. The @code{compare-buffer-substrings} and @code{current-kill} -functions have been removed. - -@item -The variable @code{overwrite-mode-binary} has been removed. - -@item -The function @code{move-to-column} allows just one argument, -@var{column}. - -@item -The search functions now just return @code{t} when successful. This -affects the functions @code{search-forward}, @code{search-backward}, -@code{word-search-forward}, @code{word-search-backward}, -@code{re-search-forward}, and @code{re-search-backward}. - -@item -When you do regular expression searching or matching, there is a fixed -limit of ten @samp{\(@dots{}\)} pairs that you can get information about -with @code{match-beginning} and @code{match-end}. Moreover, -@code{save-match-data} does not exist; you must use an explicit -@code{unwind-protect} to save the match data. - -@item -@code{translate-region} is gone. - -@item -The variables @code{before-change-function}, -@code{after-change-function}, and @code{first-change-hook} have been -eliminated. - -@item -The second argument to @code{insert-abbrev-table-description} is no -longer optional. -@end itemize - -@section Text Properties - -We eliminated text properties. - -@section Features for Files - -Many file-related functions have been eliminated or simplified. Here is -a basic listing of these functions. - -@itemize @bullet -@item -The functions @code{file-accessible-directory-p}, @code{file-truename}, -@code{make-directory}, @code{delete-directory}, -@code{set-visited-file-modtime}, @code{directory-abbrev-alist}, -@code{abbreviate-file-name}, @code{write-region}, -@code{write-contents-hooks}, @code{after-save-hook}, -@code{set-default-file-modes}, @code{default-file-modes}, and -@code{unix-sync} have been eliminated. - -@item -We got rid of the ``initial file name'' argument to -@code{read-file-name}. - -@item -Additionally, we removed the 12th element from the list returned by -@code{file-attributes}. - -@item -@code{directory-files} always sorts the list of files. It's not user -friendly to process the files in any haphazard order. - -@item -We eliminated the variables @code{write-contents-hooks} and -@code{local-write-file-hooks}. -@end itemize - -@section Making Certain File Names ``Magic'' - -There are no more magic filenames. Sorry, but all the mana has been -used up. - -@section Frames - -There is only one frame in Emacs 18, so all of the frame functions have -been eliminated. - -@section X Window System Features - -We have simplified the way Emacs and X interact by removing a great deal -of creeping featurism. - -@itemize @bullet -@item -The functions @code{mouse-position} and @code{set-mouse-position}, and -the special form @code{track-mouse}, have been eliminated. - -@item -Likewise, the functions @code{x-set-selection}, @code{x-set-cut-buffer}, -@code{x-close-current-connection}, and @code{x-open-connection} have all -been removed from Emacs Lisp 18. - -@item -We removed a series of functions that gave information about the X -server and the screen you were using; after all, the whole point of X is -that all servers are equivalent. The names of the removed functions -are: @code{x-display-screens}, @code{x-server-version}, -@code{x-server-vendor}, @code{x-display-pixel-height}, -@code{x-display-mm-height}, @code{x-display-pixel-width}, -@code{x-display-mm-width}, @code{x-display-backing-store}, -@code{x-display-save-under}, @code{x-display-planes}, -@code{x-display-visual-class}, @code{x-display-color-p}, and -@code{x-display-color-cells}. - -@item -Additionally, we removed the variable @code{x-no-window-manager} and the -functions @code{x-synchronize} and @code{x-get-resource}. - -@item -We didn't abolish @code{x-display-color-p}, but we renamed it to -@code{x-color-display-p}. We did abolish @code{x-color-defined-p}. - -@item -@code{x-popup-menu} no longer accepts a keymap for its first argument. - -@item -We removed both the function @code{x-rebind-key} and the related -function @code{x-rebind-keys}. - -@item -We abolished @code{x-parse-geometry}. -@end itemize - -@section Window Actions that Were No Longer Useful - -Various behaviors of windows in Emacs 19 were obsolete by the time Emacs -18 was due to come out. We have removed them. These changes are listed -below. - -@itemize @bullet -@item -We removed the functions @code{window-at}, @code{window-minibuffer-p}, -@code{set-window-dedicated-p}, @code{coordinates-in-window-p}, -@code{walk-windows}, @code{window-dedicated-p}, and @code{window-end}. - -@item -We removed the variables @code{pop-up-frames}, -@code{pop-up-frame-function}, @code{display-buffer-function}, and -@code{other-window-scroll-buffer}. - -@item -The function @code{minibuffer-window} no longer accepts a frame as -argument, since frames as objects do not exist in Emacs version 18. It -returns the window used for minibuffers. - -@item -The functions @code{next-window} and @code{previous-window} no longer -accept the @var{all-frames} argument since there is just one frame. - -@item -The functions @code{get-lru-window}, @code{get-largest-window}, -@code{get-buffer-window}, and @code{get-buffer-window} also no longer -take the optional argument @var{all-frames} because there is just one -frame to search. -@end itemize - -@section Display Features - -@itemize @bullet -@item -There are no overlays, and no faces. - -@item -We eliminated the mode line spec @samp{%l} that in later versions used -to display the current line number. We removed the variables -@code{line-number-mode} and @code{line-number-display-limit}. - -@item -@code{baud-rate} is now a function rather than a variable. - -@item -You can no longer call @code{message} with @code{nil} as the only -argument; therefore, you can not reliably make the contents of the -minibuffer visible. - -@item -The variable @code{temp-buffer-show-function} has been renamed -@code{temp-buffer-show-hook}. - -@item -We removed the function @code{force-mode-line-update}. Use -the following idiom instead: - -@example -(set-buffer-modified-p (buffer-modified-p)) -@end example - -@item -Display tables no longer exist. We know what the @sc{ASCII} characters -should look like, and we made them look that way. -@end itemize - -@section Working with Input Events - -The big news about input events is that we got rid of function key -and mouse events. Now the only input events are characters. -What's more, these characters now have to be in the range of 0 to 127, -optionally with a meta bit. This makes for big simplifications. - -@itemize @bullet -@item -Functions like @code{define-key}, @code{global-set-key}, -@code{read-key-sequence}, and @code{local-set-key} used to accept -strings or vectors in Emacs 19; now they only accept strings. - -@item -The documentation functions (@code{single-key-description}, -@code{key-description}, etc.) also no longer accept vectors, but they do -accept strings. - -@item -We removed the @code{read-event}, @code{event-start}, -@code{posn-window}, @code{posn-point}, @code{posn-col-row}, -@code{posn-timestamp}, @code{scroll-bar-scale}, and @code{event-end} -functions, since they were useful only for non-character events. - -@item -We removed the @code{unread-command-events} and @code{last-event-frame} -variables. - -@item -The functions @code{this-command-keys} and @code{recent-keys} now always -return a string. Likewise, a keyboard macro's definition can only be a -string, not a vector. - -@item -We eliminated @samp{e} as an interactive specification since it -was useful only with non-character events. - -@item -In Emacs 18, we represent Meta characters as character objects with the -same encoding used in strings: 128 plus the corresponding non-Meta -@sc{ASCII} character. -@end itemize - -@section Menus - -@itemize @bullet -@item -You can no longer define menus as keymaps; good system design requires -crafting a special-purpose interface for each facility, so it can -precisely fit the requirements of that facility. We decided that -unifying keymaps and menus was simply too much of a strain. - -@item -In Emacs 18, you can activate menus only with the mouse. Using them -with a keyboard was too confusing for too many users. - -@item -Emacs 18 has no menu bars. All functions and variables related to the -menu bar have been eliminated. -@end itemize - -@section Changes in Minibuffer Features - -@itemize @bullet -@item -The minibuffer history feature has been eliminated. Thus, we removed -the optional argument @var{hist} from the minibuffer input functions -@code{read-from-minibuffer} and @code{completing-read}. - -@item -The @var{initial} argument to @code{read-from-minibuffer} and other -minibuffer input functions can no longer be a cons cell -@code{(@var{string} . @var{position})}. - -@item -In the function @code{read-no-blanks-input}, the @var{initial} argument -is no longer optional. -@end itemize - -@section New Features for Defining Commands - -@itemize @bullet -@item -The special meaning of @samp{@@} in an interactive specification has -been eliminated. - -@item -Emacs 18 does not support use of format-style @samp{%}-sequences in the -prompt strings in interactive specifications. - -@item -The property @code{enable-recursive-minibuffers} no longer has any -special meaning. -@end itemize - -@section Removed Features for Reading Input - -@itemize @bullet -@item -We removed the third argument (@var{meta}) from the function -@code{set-input-mode}. Consequently, we added the variable -@code{meta-flag}; set it to @code{t} to enable use of a Meta key, and -to @code{nil} to disable it. (Those are the only two alternatives.) - -@item -We also removed the variable @code{extra-keyboard-modifiers}. - -@item -We removed the function @code{keyboard-translate} and the variables -@code{num-input-keys} and @code{function-key-map}. -@end itemize - -@section Removed Syntax Table Features - -@itemize @bullet -@item -We eliminated the functions @code{skip-syntax-forward}, -@code{skip-syntax-backward}, @code{forward-comment}. - -@item -We removed the syntax flag for ``prefix syntax'' and the flag for the -alternate comment style. Emacs 18 supports only one style of comment -in any given syntax table. - -@item -We abolished the variable @code{words-include-escapes}. -@end itemize - -@section The Case Table - -@itemize @bullet -@item -Case tables do not exist in Emacs 18. Due to this change, we have -removed the associated functions @code{set-standard-case-table}, -@code{standard-case-table}, @code{current-case-table}, -@code{set-case-table}, and @code{set-case-syntax-pair}. -@end itemize - -@section Features for Dealing with Buffers - -@itemize @bullet -@item -We eliminated several functions for dealing with buffers: -@code{buffer-modified-tick} and @code{generate-new-buffer-name}. - -@item -We renamed @code{buffer-disable-undo} to @code{buffer-flush-undo}---a -more picturesque name, you will agree. - -@item -The function @code{other-buffer} takes just one argument in Emacs 18. - -@item -The function @code{rename-buffer} now requires you to specify precisely -the new name you want. - -@item -We removed the local variable @code{list-buffers-directory}. - -@item -We got rid of the hook @code{kill-buffer-hook}. -@end itemize - -@section Local Variables Features - -@itemize @bullet -@item -The function @code{kill-all-local-variables} always eliminates all -buffer-local variables of the current buffer. No more exceptions. - -@item -Making a variable buffer-local when it is void now sets it to -@code{nil}. - -@item -We eliminated the functions @code{default-boundp}, because it is no -longer possible for the default binding of a variable to be void. - -@item -The special forms @code{defconst} and @code{defvar} now set the -variable's local value rather than its default value when the variable -is local in the current buffer. -@end itemize - -@section Features for Subprocesses - -@itemize @bullet -@item -@code{call-process} and @code{call-process-region} no longer indicate -the termination status of the subprocess. We call on users to have faith -that the subprocess executed properly. - -@item -The standard asynchronous subprocess features do not work on VMS; -instead, special VMS asynchronous subprocess functions have been added. -Since they are only for VMS, we can't be bothered documenting them; -sorry. Use the source, Luke! - -@item -The function @code{signal-process} has been removed. - -@item -We eliminated the transaction queue feature, and the associated -functions @code{tq-create}, @code{tq-enqueue}, and @code{tq-close}. -@end itemize - -@section Dealing with Times And Time Delays - -@itemize @bullet -@item -We removed the functions @code{current-time}, @code{current-time-zone}, -@code{run-at-time}, and @code{cancel-timer}. - -@item -The function @code{current-time-string} no longer accepts any optional -arguments. - -@item -The functions @code{sit-for} and @code{sleep-for} no longer allow an -optional argument to let you specify the time period in milliseconds; -just in seconds. Additionally, we took out the optional third argument -@var{nodisp} from @code{sit-for}. - -@item -We removed the optional second and third arguments from the -@code{accept-process-output} function. It accepts just one argument, -the process. -@end itemize - -@need 3000 - -@section Features not Available for Lisp Debuggers - -@itemize @bullet -@item -In Emacs 18, you can no longer specify to invoke the Lisp debugger only -upon encountering certain types of errors. Any non-@code{nil} value for -the variable @code{debug-on-error} says to invoke the debugger for any -error whatever. - -@item -We removed the variable @code{command-debug-status} and the function -@code{backtrace-frame}. -@end itemize - -@section Memory Allocation Changes - -@itemize @bullet -@item -We removed the function @code{memory-limit}. - -@item -The list returned by @code{garbage-collect} no longer contains an -element to describe floating point numbers, since there aren't any -floating point numbers in Emacs 18. -@end itemize - -@section Hook Changes - -@itemize @bullet -@item -We removed the hooks @code{pre-abbrev-expand-hook}, -@code{pre-command-hook}, @code{post-command-hook}, and -@code{auto-save-hook}. - -@item -We removed the variable -@code{revert-buffer-insert-file-contents-function}. - -@item -We also removed the new function @code{add-hook}; you will have to set -your hooks by hand. If you want to get really into the swing of things, -set your hook variables the archaic way: store just one function rather -than a list of functions. But that is optional. - -@item -The variable @code{lisp-indent-hook} has been renamed to -@code{lisp-indent-function}. - -@item -The variable @code{auto-fill-function} has been renamed to -@code{auto-fill-hook}. - -@item -The @code{blink-paren-function} has been renamed to -@code{blink-paren-hook}. - -@item -The variable @code{temp-buffer-show-function} has been renamed to -@code{temp-buffer-show-hook}. -@end itemize diff --git a/lispref/backups.texi b/lispref/backups.texi deleted file mode 100644 index d25908fe57c..00000000000 --- a/lispref/backups.texi +++ /dev/null @@ -1,648 +0,0 @@ -@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/backups -@node Backups and Auto-Saving, Buffers, Files, Top -@chapter Backups and Auto-Saving - - Backup files and auto-save files are two methods by which Emacs tries -to protect the user from the consequences of crashes or of the user's -own errors. Auto-saving preserves the text from earlier in the current -editing session; backup files preserve file contents prior to the -current session. - -@menu -* Backup Files:: How backup files are made; how their names are chosen. -* Auto-Saving:: How auto-save files are made; how their names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize what it does. -@end menu - -@node Backup Files -@section Backup Files -@cindex backup file - - A @dfn{backup file} is a copy of the old contents of a file you are -editing. Emacs makes a backup file the first time you save a buffer -into its visited file. Normally, this means that the backup file -contains the contents of the file as it was before the current editing -session. The contents of the backup file normally remain unchanged once -it exists. - - Backups are usually made by renaming the visited file to a new name. -Optionally, you can specify that backup files should be made by copying -the visited file. This choice makes a difference for files with -multiple names; it also can affect whether the edited file remains owned -by the original owner or becomes owned by the user editing it. - - By default, Emacs makes a single backup file for each file edited. -You can alternatively request numbered backups; then each new backup -file gets a new name. You can delete old numbered backups when you -don't want them any more, or Emacs can delete them automatically. - -@menu -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. -@end menu - -@node Making Backups -@subsection Making Backup Files - -@defun backup-buffer - This function makes a backup of the file visited by the current -buffer, if appropriate. It is called by @code{save-buffer} before -saving the buffer the first time. -@end defun - -@defvar buffer-backed-up - This buffer-local variable indicates whether this buffer's file has -been backed up on account of this buffer. If it is non-@code{nil}, then -the backup file has been written. Otherwise, the file should be backed -up when it is next saved (if backups are enabled). This is a -permanent local; @code{kill-local-variables} does not alter it. -@end defvar - -@defopt make-backup-files -This variable determines whether or not to make backup files. If it -is non-@code{nil}, then Emacs creates a backup of each file when it is -saved for the first time---provided that @code{backup-inhibited} -is @code{nil} (see below). - -The following example shows how to change the @code{make-backup-files} -variable only in the @file{RMAIL} buffer and not elsewhere. Setting it -@code{nil} stops Emacs from making backups of the @file{RMAIL} file, -which may save disk space. (You would put this code in your -@file{.emacs} file.) - -@smallexample -@group -(add-hook 'rmail-mode-hook - (function (lambda () - (make-local-variable - 'make-backup-files) - (setq make-backup-files nil)))) -@end group -@end smallexample -@end defopt - -@defvar backup-enable-predicate -This variable's value is a function to be called on certain occasions to -decide whether a file should have backup files. The function receives -one argument, a file name to consider. If the function returns -@code{nil}, backups are disabled for that file. Otherwise, the other -variables in this section say whether and how to make backups. - -The default value is this: - -@example -(lambda (name) - (or (< (length name) 5) - (not (string-equal "/tmp/" - (substring name 0 5))))) -@end example -@end defvar - -@defvar backup-inhibited -If this variable is non-@code{nil}, backups are inhibited. It records -the result of testing @code{backup-enable-predicate} on the visited file -name. It can also coherently be used by other mechanisms that inhibit -backups based on which file is visited. For example, VC sets this -variable non-@code{nil} to prevent making backups for files managed -with a version control system. - -This is a permanent local, so that changing the major mode does not lose -its value. Major modes should not set this variable---they should set -@code{make-backup-files} instead. -@end defvar - -@node Rename or Copy -@subsection Backup by Renaming or by Copying? -@cindex backup files, how to make them - - There are two ways that Emacs can make a backup file: - -@itemize @bullet -@item -Emacs can rename the original file so that it becomes a backup file, and -then write the buffer being saved into a new file. After this -procedure, any other names (i.e., hard links) of the original file now -refer to the backup file. The new file is owned by the user doing the -editing, and its group is the default for new files written by the user -in that directory. - -@item -Emacs can copy the original file into a backup file, and then overwrite -the original file with new contents. After this procedure, any other -names (i.e., hard links) of the original file still refer to the current -version of the file. The file's owner and group will be unchanged. -@end itemize - - The first method, renaming, is the default. - - The variable @code{backup-by-copying}, if non-@code{nil}, says to use -the second method, which is to copy the original file and overwrite it -with the new buffer contents. The variable @code{file-precious-flag}, -if non-@code{nil}, also has this effect (as a sideline of its main -significance). @xref{Saving Buffers}. - -@defvar backup-by-copying -If this variable is non-@code{nil}, Emacs always makes backup files by -copying. -@end defvar - - The following two variables, when non-@code{nil}, cause the second -method to be used in certain special cases. They have no effect on the -treatment of files that don't fall into the special cases. - -@defvar backup-by-copying-when-linked -If this variable is non-@code{nil}, Emacs makes backups by copying for -files with multiple names (hard links). - -This variable is significant only if @code{backup-by-copying} is -@code{nil}, since copying is always used when that variable is -non-@code{nil}. -@end defvar - -@defvar backup-by-copying-when-mismatch -If this variable is non-@code{nil}, Emacs makes backups by copying in cases -where renaming would change either the owner or the group of the file. - -The value has no effect when renaming would not alter the owner or -group of the file; that is, for files which are owned by the user and -whose group matches the default for a new file created there by the -user. - -This variable is significant only if @code{backup-by-copying} is -@code{nil}, since copying is always used when that variable is -non-@code{nil}. -@end defvar - -@node Numbered Backups -@subsection Making and Deleting Numbered Backup Files - - If a file's name is @file{foo}, the names of its numbered backup -versions are @file{foo.~@var{v}~}, for various integers @var{v}, like -this: @file{foo.~1~}, @file{foo.~2~}, @file{foo.~3~}, @dots{}, -@file{foo.~259~}, and so on. - -@defopt version-control -This variable controls whether to make a single non-numbered backup -file or multiple numbered backups. - -@table @asis -@item @code{nil} -Make numbered backups if the visited file already has numbered backups; -otherwise, do not. - -@item @code{never} -Do not make numbered backups. - -@item @var{anything else} -Make numbered backups. -@end table -@end defopt - - The use of numbered backups ultimately leads to a large number of -backup versions, which must then be deleted. Emacs can do this -automatically or it can ask the user whether to delete them. - -@defopt kept-new-versions -The value of this variable is the number of newest versions to keep -when a new numbered backup is made. The newly made backup is included -in the count. The default value is 2. -@end defopt - -@defopt kept-old-versions -The value of this variable is the number of oldest versions to keep -when a new numbered backup is made. The default value is 2. -@end defopt - - If there are backups numbered 1, 2, 3, 5, and 7, and both of these -variables have the value 2, then the backups numbered 1 and 2 are kept -as old versions and those numbered 5 and 7 are kept as new versions; -backup version 3 is excess. The function @code{find-backup-file-name} -(@pxref{Backup Names}) is responsible for determining which backup -versions to delete, but does not delete them itself. - -@defopt trim-versions-without-asking -If this variable is non-@code{nil}, then saving a file deletes excess -backup versions silently. Otherwise, it asks the user whether to delete -them. -@end defopt - -@defopt dired-kept-versions -This variable specifies how many of the newest backup versions to keep -in the Dired command @kbd{.} (@code{dired-clean-directory}). That's the -same thing @code{kept-new-versions} specifies when you make a new backup -file. The default value is 2. -@end defopt - -@node Backup Names -@subsection Naming Backup Files - - The functions in this section are documented mainly because you can -customize the naming conventions for backup files by redefining them. -If you change one, you probably need to change the rest. - -@defun backup-file-name-p filename -This function returns a non-@code{nil} value if @var{filename} is a -possible name for a backup file. A file with the name @var{filename} -need not exist; the function just checks the name. - -@smallexample -@group -(backup-file-name-p "foo") - @result{} nil -@end group -@group -(backup-file-name-p "foo~") - @result{} 3 -@end group -@end smallexample - -The standard definition of this function is as follows: - -@smallexample -@group -(defun backup-file-name-p (file) - "Return non-nil if FILE is a backup file \ -name (numeric or not)..." - (string-match "~$" file)) -@end group -@end smallexample - -@noindent -Thus, the function returns a non-@code{nil} value if the file name ends -with a @samp{~}. (We use a backslash to split the documentation -string's first line into two lines in the text, but produce just one -line in the string itself.) - -This simple expression is placed in a separate function to make it easy -to redefine for customization. -@end defun - -@defun make-backup-file-name filename -This function returns a string that is the name to use for a -non-numbered backup file for file @var{filename}. On Unix, this is just -@var{filename} with a tilde appended. - -The standard definition of this function is as follows: - -@smallexample -@group -(defun make-backup-file-name (file) - "Create the non-numeric backup file name for FILE. -@dots{}" - (concat file "~")) -@end group -@end smallexample - -You can change the backup-file naming convention by redefining this -function. The following example redefines @code{make-backup-file-name} -to prepend a @samp{.} in addition to appending a tilde: - -@smallexample -@group -(defun make-backup-file-name (filename) - (concat "." filename "~")) -@end group - -@group -(make-backup-file-name "backups.texi") - @result{} ".backups.texi~" -@end group -@end smallexample -@end defun - -@defun find-backup-file-name filename -This function computes the file name for a new backup file for -@var{filename}. It may also propose certain existing backup files for -deletion. @code{find-backup-file-name} returns a list whose @sc{car} is -the name for the new backup file and whose @sc{cdr} is a list of backup -files whose deletion is proposed. - -Two variables, @code{kept-old-versions} and @code{kept-new-versions}, -determine which backup versions should be kept. This function keeps -those versions by excluding them from the @sc{cdr} of the value. -@xref{Numbered Backups}. - -In this example, the value says that @file{~rms/foo.~5~} is the name -to use for the new backup file, and @file{~rms/foo.~3~} is an ``excess'' -version that the caller should consider deleting now. - -@smallexample -@group -(find-backup-file-name "~rms/foo") - @result{} ("~rms/foo.~5~" "~rms/foo.~3~") -@end group -@end smallexample -@end defun - -@c Emacs 19 feature -@defun file-newest-backup filename -This function returns the name of the most recent backup file for -@var{filename}, or @code{nil} if that file has no backup files. - -Some file comparison commands use this function so that they can -automatically compare a file with its most recent backup. -@end defun - -@node Auto-Saving -@section Auto-Saving -@cindex auto-saving - - Emacs periodically saves all files that you are visiting; this is -called @dfn{auto-saving}. Auto-saving prevents you from losing more -than a limited amount of work if the system crashes. By default, -auto-saves happen every 300 keystrokes, or after around 30 seconds of -idle time. @xref{Auto-Save, Auto-Save, Auto-Saving: Protection Against -Disasters, emacs, The GNU Emacs Manual}, for information on auto-save -for users. Here we describe the functions used to implement auto-saving -and the variables that control them. - -@defvar buffer-auto-save-file-name -This buffer-local variable is the name of the file used for -auto-saving the current buffer. It is @code{nil} if the buffer -should not be auto-saved. - -@example -@group -buffer-auto-save-file-name -=> "/xcssun/users/rms/lewis/#files.texi#" -@end group -@end example -@end defvar - -@deffn Command auto-save-mode arg -When used interactively without an argument, this command is a toggle -switch: it turns on auto-saving of the current buffer if it is off, and -vice-versa. With an argument @var{arg}, the command turns auto-saving -on if the value of @var{arg} is @code{t}, a nonempty list, or a positive -integer. Otherwise, it turns auto-saving off. -@end deffn - -@defun auto-save-file-name-p filename -This function returns a non-@code{nil} value if @var{filename} is a -string that could be the name of an auto-save file. It works based on -knowledge of the naming convention for auto-save files: a name that -begins and ends with hash marks (@samp{#}) is a possible auto-save file -name. The argument @var{filename} should not contain a directory part. - -@example -@group -(make-auto-save-file-name) - @result{} "/xcssun/users/rms/lewis/#files.texi#" -@end group -@group -(auto-save-file-name-p "#files.texi#") - @result{} 0 -@end group -@group -(auto-save-file-name-p "files.texi") - @result{} nil -@end group -@end example - -The standard definition of this function is as follows: - -@example -@group -(defun auto-save-file-name-p (filename) - "Return non-nil if FILENAME can be yielded by..." - (string-match "^#.*#$" filename)) -@end group -@end example - -This function exists so that you can customize it if you wish to -change the naming convention for auto-save files. If you redefine it, -be sure to redefine the function @code{make-auto-save-file-name} -correspondingly. -@end defun - -@defun make-auto-save-file-name -This function returns the file name to use for auto-saving the current -buffer. This is just the file name with hash marks (@samp{#}) appended -and prepended to it. This function does not look at the variable -@code{auto-save-visited-file-name} (described below); you should check -that before calling this function. - -@example -@group -(make-auto-save-file-name) - @result{} "/xcssun/users/rms/lewis/#backup.texi#" -@end group -@end example - -The standard definition of this function is as follows: - -@example -@group -(defun make-auto-save-file-name () - "Return file name to use for auto-saves \ -of current buffer. -@dots{}" - (if buffer-file-name -@end group -@group - (concat - (file-name-directory buffer-file-name) - "#" - (file-name-nondirectory buffer-file-name) - "#") - (expand-file-name - (concat "#%" (buffer-name) "#")))) -@end group -@end example - -This exists as a separate function so that you can redefine it to -customize the naming convention for auto-save files. Be sure to -change @code{auto-save-file-name-p} in a corresponding way. -@end defun - -@defvar auto-save-visited-file-name -If this variable is non-@code{nil}, Emacs auto-saves buffers in -the files they are visiting. That is, the auto-save is done in the same -file that you are editing. Normally, this variable is @code{nil}, so -auto-save files have distinct names that are created by -@code{make-auto-save-file-name}. - -When you change the value of this variable, the value does not take -effect until the next time auto-save mode is reenabled in any given -buffer. If auto-save mode is already enabled, auto-saves continue to go -in the same file name until @code{auto-save-mode} is called again. -@end defvar - -@defun recent-auto-save-p -This function returns @code{t} if the current buffer has been -auto-saved since the last time it was read in or saved. -@end defun - -@defun set-buffer-auto-saved -This function marks the current buffer as auto-saved. The buffer will -not be auto-saved again until the buffer text is changed again. The -function returns @code{nil}. -@end defun - -@defopt auto-save-interval -The value of this variable is the number of characters that Emacs -reads from the keyboard between auto-saves. Each time this many more -characters are read, auto-saving is done for all buffers in which it is -enabled. -@end defopt - -@defopt auto-save-timeout -The value of this variable is the number of seconds of idle time that -should cause auto-saving. Each time the user pauses for this long, -Emacs auto-saves any buffers that need it. (Actually, the specified -timeout is multiplied by a factor depending on the size of the current -buffer.) -@end defopt - -@defvar auto-save-hook -This normal hook is run whenever an auto-save is about to happen. -@end defvar - -@defopt auto-save-default -If this variable is non-@code{nil}, buffers that are visiting files -have auto-saving enabled by default. Otherwise, they do not. -@end defopt - -@deffn Command do-auto-save &optional no-message current-only -This function auto-saves all buffers that need to be auto-saved. It -saves all buffers for which auto-saving is enabled and that have been -changed since the previous auto-save. - -Normally, if any buffers are auto-saved, a message that says -@samp{Auto-saving...} is displayed in the echo area while auto-saving is -going on. However, if @var{no-message} is non-@code{nil}, the message -is inhibited. - -If @var{current-only} is non-@code{nil}, only the current buffer -is auto-saved. -@end deffn - -@defun delete-auto-save-file-if-necessary -This function deletes the current buffer's auto-save file if -@code{delete-auto-save-files} is non-@code{nil}. It is called every -time a buffer is saved. -@end defun - -@defvar delete-auto-save-files -This variable is used by the function -@code{delete-auto-save-file-if-necessary}. If it is non-@code{nil}, -Emacs deletes auto-save files when a true save is done (in the visited -file). This saves disk space and unclutters your directory. -@end defvar - -@defun rename-auto-save-file -This function adjusts the current buffer's auto-save file name if the -visited file name has changed. It also renames an existing auto-save -file. If the visited file name has not changed, this function does -nothing. -@end defun - -@defvar buffer-saved-size -The value of this buffer-local variable is the length of the current -buffer as of the last time it was read in, saved, or auto-saved. This is -used to detect a substantial decrease in size, and turn off auto-saving -in response. - -If it is -1, that means auto-saving is temporarily shut off in this -buffer due to a substantial deletion. Explicitly saving the buffer -stores a positive value in this variable, thus reenabling auto-saving. -Turning auto-save mode off or on also alters this variable. -@end defvar - -@defvar auto-save-list-file-name -This variable (if non-@code{nil}) specifies a file for recording the -names of all the auto-save files. Each time Emacs does auto-saving, it -writes two lines into this file for each buffer that has auto-saving -enabled. The first line gives the name of the visited file (it's empty -if the buffer has none), and the second gives the name of the auto-save -file. - -If Emacs exits normally, it deletes this file. If Emacs crashes, you -can look in the file to find all the auto-save files that might contain -work that was otherwise lost. The @code{recover-session} command uses -these files. - -The default name for this file is in your home directory and starts with -@samp{.saves-}. It also contains the Emacs process @sc{id} and the host -name. -@end defvar - -@node Reverting -@section Reverting - - If you have made extensive changes to a file and then change your mind -about them, you can get rid of them by reading in the previous version -of the file with the @code{revert-buffer} command. @xref{Reverting, , -Reverting a Buffer, emacs, The GNU Emacs Manual}. - -@deffn Command revert-buffer &optional check-auto-save noconfirm -This command replaces the buffer text with the text of the visited -file on disk. This action undoes all changes since the file was visited -or saved. - -If the argument @var{check-auto-save} is non-@code{nil}, and the -latest auto-save file is more recent than the visited file, -@code{revert-buffer} asks the user whether to use that instead. -Otherwise, it always uses the text of the visited file itself. -Interactively, @var{check-auto-save} is set if there is a numeric prefix -argument. - -Normally, @code{revert-buffer} asks for confirmation before it changes -the buffer; but if the argument @var{noconfirm} is non-@code{nil}, -@code{revert-buffer} does not ask for confirmation. - -Reverting tries to preserve marker positions in the buffer by using the -replacement feature of @code{insert-file-contents}. If the buffer -contents and the file contents are identical before the revert -operation, reverting preserves all the markers. If they are not -identical, reverting does change the buffer; then it preserves the -markers in the unchanged text (if any) at the beginning and end of the -buffer. Preserving any additional markers would be problematical. -@end deffn - -You can customize how @code{revert-buffer} does its work by setting -these variables---typically, as buffer-local variables. - -@defvar revert-buffer-function -The value of this variable is the function to use to revert this buffer. -If non-@code{nil}, it is called as a function with no arguments to do -the work of reverting. If the value is @code{nil}, reverting works the -usual way. - -Modes such as Dired mode, in which the text being edited does not -consist of a file's contents but can be regenerated in some other -fashion, give this variable a buffer-local value that is a function to -regenerate the contents. -@end defvar - -@defvar revert-buffer-insert-file-contents-function -The value of this variable, if non-@code{nil}, is the function to use to -insert the updated contents when reverting this buffer. The function -receives two arguments: first the file name to use; second, @code{t} if -the user has asked to read the auto-save file. -@end defvar - -@defvar before-revert-hook -This normal hook is run by @code{revert-buffer} before actually -inserting the modified contents---but only if -@code{revert-buffer-function} is @code{nil}. - -Font Lock mode uses this hook to record that the buffer contents are no -longer fontified. -@end defvar - -@defvar after-revert-hook -This normal hook is run by @code{revert-buffer} after actually inserting -the modified contents---but only if @code{revert-buffer-function} is -@code{nil}. - -Font Lock mode uses this hook to recompute the fonts for the updated -buffer contents. -@end defvar - diff --git a/lispref/book-spine.texinfo b/lispref/book-spine.texinfo deleted file mode 100644 index 8633d477aca..00000000000 --- a/lispref/book-spine.texinfo +++ /dev/null @@ -1,25 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename book-spine -@settitle book-spine -@c %**end of header - -@c need dot in text so first space command works! -. -@sp 7 - -@center @titlefont{GNU Emacs Lisp Reference Manual} -@sp 5 -@center GNU -@center Emacs Version 19.25 -@center for Unix Users -@sp 5 - -@center by -@center Bil Lewis, -@center Dan LaLiberte, -@center and the -@center GNU Manual Group -@sp 5 -@center Free Software Foundation -@bye diff --git a/lispref/buffers.texi b/lispref/buffers.texi deleted file mode 100644 index de2d43052d9..00000000000 --- a/lispref/buffers.texi +++ /dev/null @@ -1,911 +0,0 @@ -@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/buffers -@node Buffers, Windows, Backups and Auto-Saving, Top -@chapter Buffers -@cindex buffer - - A @dfn{buffer} is a Lisp object containing text to be edited. Buffers -are used to hold the contents of files that are being visited; there may -also be buffers that are not visiting files. While several buffers may -exist at one time, exactly one buffer is designated the @dfn{current -buffer} at any time. Most editing commands act on the contents of the -current buffer. Each buffer, including the current buffer, may or may -not be displayed in any windows. - -@menu -* Buffer Basics:: What is a buffer? -* Current Buffer:: Designating a buffer as current - so primitives will access its contents. -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. -* Read Only Buffers:: Modifying text is not allowed in a read-only buffer. -* The Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Indirect Buffers:: An indirect buffer shares text with some other buffer. -@end menu - -@node Buffer Basics -@comment node-name, next, previous, up -@section Buffer Basics - -@ifinfo - A @dfn{buffer} is a Lisp object containing text to be edited. Buffers -are used to hold the contents of files that are being visited; there may -also be buffers that are not visiting files. While several buffers may -exist at one time, exactly one buffer is designated the @dfn{current -buffer} at any time. Most editing commands act on the contents of the -current buffer. Each buffer, including the current buffer, may or may -not be displayed in any windows. -@end ifinfo - - Buffers in Emacs editing are objects that have distinct names and hold -text that can be edited. Buffers appear to Lisp programs as a special -data type. You can think of the contents of a buffer as an extendable -string; insertions and deletions may occur in any part of the buffer. -@xref{Text}. - - A Lisp buffer object contains numerous pieces of information. Some of -this information is directly accessible to the programmer through -variables, while other information is accessible only through -special-purpose functions. For example, the visited file name is -directly accessible through a variable, while the value of point is -accessible only through a primitive function. - - Buffer-specific information that is directly accessible is stored in -@dfn{buffer-local} variable bindings, which are variable values that are -effective only in a particular buffer. This feature allows each buffer -to override the values of certain variables. Most major modes override -variables such as @code{fill-column} or @code{comment-column} in this -way. For more information about buffer-local variables and functions -related to them, see @ref{Buffer-Local Variables}. - - For functions and variables related to visiting files in buffers, see -@ref{Visiting Files} and @ref{Saving Buffers}. For functions and -variables related to the display of buffers in windows, see -@ref{Buffers and Windows}. - -@defun bufferp object -This function returns @code{t} if @var{object} is a buffer, -@code{nil} otherwise. -@end defun - -@node Current Buffer -@section The Current Buffer -@cindex selecting a buffer -@cindex changing to another buffer -@cindex current buffer - - There are, in general, many buffers in an Emacs session. At any time, -one of them is designated as the @dfn{current buffer}. This is the -buffer in which most editing takes place, because most of the primitives -for examining or changing text in a buffer operate implicitly on the -current buffer (@pxref{Text}). Normally the buffer that is displayed on -the screen in the selected window is the current buffer, but this is not -always so: a Lisp program can designate any buffer as current -temporarily in order to operate on its contents, without changing what -is displayed on the screen. - - The way to designate a current buffer in a Lisp program is by calling -@code{set-buffer}. The specified buffer remains current until a new one -is designated. - - When an editing command returns to the editor command loop, the -command loop designates the buffer displayed in the selected window as -current, to prevent confusion: the buffer that the cursor is in when -Emacs reads a command is the buffer that the command will apply to. -(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to -switch visibly to a different buffer so that the user can edit it. For -this, you must use the functions described in @ref{Displaying Buffers}. - - However, Lisp functions that change to a different current buffer -should not depend on the command loop to set it back afterwards. -Editing commands written in Emacs Lisp can be called from other programs -as well as from the command loop. It is convenient for the caller if -the subroutine does not change which buffer is current (unless, of -course, that is the subroutine's purpose). Therefore, you should -normally use @code{set-buffer} within a @code{save-excursion} that will -restore the current buffer when your function is done -(@pxref{Excursions}). Here is an example, the code for the command -@code{append-to-buffer} (with the documentation string abridged): - -@example -@group -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -@dots{}" - (interactive "BAppend to buffer: \nr") - (let ((oldbuf (current-buffer))) - (save-excursion - (set-buffer (get-buffer-create buffer)) - (insert-buffer-substring oldbuf start end)))) -@end group -@end example - -@noindent -This function binds a local variable to the current buffer, and then -@code{save-excursion} records the values of point, the mark, and the -original buffer. Next, @code{set-buffer} makes another buffer current. -Finally, @code{insert-buffer-substring} copies the string from the -original current buffer to the new current buffer. - - If the buffer appended to happens to be displayed in some window, -the next redisplay will show how its text has changed. Otherwise, you -will not see the change immediately on the screen. The buffer becomes -current temporarily during the execution of the command, but this does -not cause it to be displayed. - - If you make local bindings (with @code{let} or function arguments) for -a variable that may also have buffer-local bindings, make sure that the -same buffer is current at the beginning and at the end of the local -binding's scope. Otherwise you might bind it in one buffer and unbind -it in another! There are two ways to do this. In simple cases, you may -see that nothing ever changes the current buffer within the scope of the -binding. Otherwise, use @code{save-excursion} to make sure that the -buffer current at the beginning is current again whenever the variable -is unbound. - - It is not reliable to change the current buffer back with -@code{set-buffer}, because that won't do the job if a quit happens while -the wrong buffer is current. Here is what @emph{not} to do: - -@example -@group -(let (buffer-read-only - (obuf (current-buffer))) - (set-buffer @dots{}) - @dots{} - (set-buffer obuf)) -@end group -@end example - -@noindent -Using @code{save-excursion}, as shown below, handles quitting, errors, -and @code{throw}, as well as ordinary evaluation. - -@example -@group -(let (buffer-read-only) - (save-excursion - (set-buffer @dots{}) - @dots{})) -@end group -@end example - -@defun current-buffer -This function returns the current buffer. - -@example -@group -(current-buffer) - @result{} #<buffer buffers.texi> -@end group -@end example -@end defun - -@defun set-buffer buffer-or-name -This function makes @var{buffer-or-name} the current buffer. It does -not display the buffer in the currently selected window or in any other -window, so the user cannot necessarily see the buffer. But Lisp -programs can in any case work on it. - -This function returns the buffer identified by @var{buffer-or-name}. -An error is signaled if @var{buffer-or-name} does not identify an -existing buffer. -@end defun - -@node Buffer Names -@section Buffer Names -@cindex buffer names - - Each buffer has a unique name, which is a string. Many of the -functions that work on buffers accept either a buffer or a buffer name -as an argument. Any argument called @var{buffer-or-name} is of this -sort, and an error is signaled if it is neither a string nor a buffer. -Any argument called @var{buffer} must be an actual buffer -object, not a name. - - Buffers that are ephemeral and generally uninteresting to the user -have names starting with a space, so that the @code{list-buffers} and -@code{buffer-menu} commands don't mention them. A name starting with -space also initially disables recording undo information; see -@ref{Undo}. - -@defun buffer-name &optional buffer -This function returns the name of @var{buffer} as a string. If -@var{buffer} is not supplied, it defaults to the current buffer. - -If @code{buffer-name} returns @code{nil}, it means that @var{buffer} -has been killed. @xref{Killing Buffers}. - -@example -@group -(buffer-name) - @result{} "buffers.texi" -@end group - -@group -(setq foo (get-buffer "temp")) - @result{} #<buffer temp> -@end group -@group -(kill-buffer foo) - @result{} nil -@end group -@group -(buffer-name foo) - @result{} nil -@end group -@group -foo - @result{} #<killed buffer> -@end group -@end example -@end defun - -@deffn Command rename-buffer newname &optional unique -This function renames the current buffer to @var{newname}. An error -is signaled if @var{newname} is not a string, or if there is already a -buffer with that name. The function returns @var{newname}. - -@c Emacs 19 feature -Ordinarily, @code{rename-buffer} signals an error if @var{newname} is -already in use. However, if @var{unique} is non-@code{nil}, it modifies -@var{newname} to make a name that is not in use. Interactively, you can -make @var{unique} non-@code{nil} with a numeric prefix argument. - -One application of this command is to rename the @samp{*shell*} buffer -to some other name, thus making it possible to create a second shell -buffer under the name @samp{*shell*}. -@end deffn - -@defun get-buffer buffer-or-name -This function returns the buffer specified by @var{buffer-or-name}. -If @var{buffer-or-name} is a string and there is no buffer with that -name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it -is returned as given. (That is not very useful, so the argument is usually -a name.) For example: - -@example -@group -(setq b (get-buffer "lewis")) - @result{} #<buffer lewis> -@end group -@group -(get-buffer b) - @result{} #<buffer lewis> -@end group -@group -(get-buffer "Frazzle-nots") - @result{} nil -@end group -@end example - -See also the function @code{get-buffer-create} in @ref{Creating Buffers}. -@end defun - -@c Emacs 19 feature -@defun generate-new-buffer-name starting-name -This function returns a name that would be unique for a new buffer---but -does not create the buffer. It starts with @var{starting-name}, and -produces a name not currently in use for any buffer by appending a -number inside of @samp{<@dots{}>}. - -See the related function @code{generate-new-buffer} in @ref{Creating -Buffers}. -@end defun - -@node Buffer File Name -@section Buffer File Name -@cindex visited file -@cindex buffer file name -@cindex file name of buffer - - The @dfn{buffer file name} is the name of the file that is visited in -that buffer. When a buffer is not visiting a file, its buffer file name -is @code{nil}. Most of the time, the buffer name is the same as the -nondirectory part of the buffer file name, but the buffer file name and -the buffer name are distinct and can be set independently. -@xref{Visiting Files}. - -@defun buffer-file-name &optional buffer -This function returns the absolute file name of the file that -@var{buffer} is visiting. If @var{buffer} is not visiting any file, -@code{buffer-file-name} returns @code{nil}. If @var{buffer} is not -supplied, it defaults to the current buffer. - -@example -@group -(buffer-file-name (other-buffer)) - @result{} "/usr/user/lewis/manual/files.texi" -@end group -@end example -@end defun - -@defvar buffer-file-name -This buffer-local variable contains the name of the file being visited -in the current buffer, or @code{nil} if it is not visiting a file. It -is a permanent local, unaffected by @code{kill-local-variables}. - -@example -@group -buffer-file-name - @result{} "/usr/user/lewis/manual/buffers.texi" -@end group -@end example - -It is risky to change this variable's value without doing various other -things. See the definition of @code{set-visited-file-name} in -@file{files.el}; some of the things done there, such as changing the -buffer name, are not strictly necessary, but others are essential to -avoid confusing Emacs. -@end defvar - -@defvar buffer-file-truename -This buffer-local variable holds the truename of the file visited in the -current buffer, or @code{nil} if no file is visited. It is a permanent -local, unaffected by @code{kill-local-variables}. @xref{Truenames}. -@end defvar - -@defvar buffer-file-number -This buffer-local variable holds the file number and directory device -number of the file visited in the current buffer, or @code{nil} if no -file or a nonexistent file is visited. It is a permanent local, -unaffected by @code{kill-local-variables}. @xref{Truenames}. - -The value is normally a list of the form @code{(@var{filenum} -@var{devnum})}. This pair of numbers uniquely identifies the file among -all files accessible on the system. See the function -@code{file-attributes}, in @ref{File Attributes}, for more information -about them. -@end defvar - -@defun get-file-buffer filename -This function returns the buffer visiting file @var{filename}. If -there is no such buffer, it returns @code{nil}. The argument -@var{filename}, which must be a string, is expanded (@pxref{File Name -Expansion}), then compared against the visited file names of all live -buffers. - -@example -@group -(get-file-buffer "buffers.texi") - @result{} #<buffer buffers.texi> -@end group -@end example - -In unusual circumstances, there can be more than one buffer visiting -the same file name. In such cases, this function returns the first -such buffer in the buffer list. -@end defun - -@deffn Command set-visited-file-name filename -If @var{filename} is a non-empty string, this function changes the -name of the file visited in current buffer to @var{filename}. (If the -buffer had no visited file, this gives it one.) The @emph{next time} -the buffer is saved it will go in the newly-specified file. This -command marks the buffer as modified, since it does not (as far as Emacs -knows) match the contents of @var{filename}, even if it matched the -former visited file. - -If @var{filename} is @code{nil} or the empty string, that stands for -``no visited file''. In this case, @code{set-visited-file-name} marks -the buffer as having no visited file. - -@c Wordy to avoid overfull hbox. --rjc 16mar92 -When the function @code{set-visited-file-name} is called interactively, it -prompts for @var{filename} in the minibuffer. - -See also @code{clear-visited-file-modtime} and -@code{verify-visited-file-modtime} in @ref{Buffer Modification}. -@end deffn - -@defvar list-buffers-directory -This buffer-local variable records a string to display in a buffer -listing in place of the visited file name, for buffers that don't have a -visited file name. Dired buffers use this variable. -@end defvar - -@node Buffer Modification -@section Buffer Modification -@cindex buffer modification -@cindex modification flag (of buffer) - - Emacs keeps a flag called the @dfn{modified flag} for each buffer, to -record whether you have changed the text of the buffer. This flag is -set to @code{t} whenever you alter the contents of the buffer, and -cleared to @code{nil} when you save it. Thus, the flag shows whether -there are unsaved changes. The flag value is normally shown in the mode -line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving -Buffers}) and auto-saving (@pxref{Auto-Saving}). - - Some Lisp programs set the flag explicitly. For example, the function -@code{set-visited-file-name} sets the flag to @code{t}, because the text -does not match the newly-visited file, even if it is unchanged from the -file formerly visited. - - The functions that modify the contents of buffers are described in -@ref{Text}. - -@defun buffer-modified-p &optional buffer -This function returns @code{t} if the buffer @var{buffer} has been modified -since it was last read in from a file or saved, or @code{nil} -otherwise. If @var{buffer} is not supplied, the current buffer -is tested. -@end defun - -@defun set-buffer-modified-p flag -This function marks the current buffer as modified if @var{flag} is -non-@code{nil}, or as unmodified if the flag is @code{nil}. - -Another effect of calling this function is to cause unconditional -redisplay of the mode line for the current buffer. In fact, the -function @code{force-mode-line-update} works by doing this: - -@example -@group -(set-buffer-modified-p (buffer-modified-p)) -@end group -@end example -@end defun - -@deffn Command not-modified -This command marks the current buffer as unmodified, and not needing to -be saved. With prefix arg, it marks the buffer as modified, so that it -will be saved at the next suitable occasion. - -Don't use this function in programs, since it prints a message in the -echo area; use @code{set-buffer-modified-p} (above) instead. -@end deffn - -@c Emacs 19 feature -@defun buffer-modified-tick &optional buffer -This function returns @var{buffer}'s modification-count. This is a -counter that increments every time the buffer is modified. If -@var{buffer} is @code{nil} (or omitted), the current buffer is used. -@end defun - -@node Modification Time -@comment node-name, next, previous, up -@section Comparison of Modification Time -@cindex comparison of modification time -@cindex modification time, comparison of - - Suppose that you visit a file and make changes in its buffer, and -meanwhile the file itself is changed on disk. At this point, saving the -buffer would overwrite the changes in the file. Occasionally this may -be what you want, but usually it would lose valuable information. Emacs -therefore checks the file's modification time using the functions -described below before saving the file. - -@defun verify-visited-file-modtime buffer -This function compares what @var{buffer} has recorded for the -modification time of its visited file against the actual modification -time of the file as recorded by the operating system. The two should be -the same unless some other process has written the file since Emacs -visited or saved it. - -The function returns @code{t} if the last actual modification time and -Emacs's recorded modification time are the same, @code{nil} otherwise. -@end defun - -@defun clear-visited-file-modtime -This function clears out the record of the last modification time of -the file being visited by the current buffer. As a result, the next -attempt to save this buffer will not complain of a discrepancy in -file modification times. - -This function is called in @code{set-visited-file-name} and other -exceptional places where the usual test to avoid overwriting a changed -file should not be done. -@end defun - -@c Emacs 19 feature -@defun visited-file-modtime -This function returns the buffer's recorded last file modification time, -as a list of the form @code{(@var{high} . @var{low})}. (This is the -same format that @code{file-attributes} uses to return time values; see -@ref{File Attributes}.) -@end defun - -@c Emacs 19 feature -@defun set-visited-file-modtime &optional time -This function updates the buffer's record of the last modification time -of the visited file, to the value specified by @var{time} if @var{time} -is not @code{nil}, and otherwise to the last modification time of the -visited file. - -If @var{time} is not @code{nil}, it should have the form -@code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in -either case containing two integers, each of which holds 16 bits of the -time. - -This function is useful if the buffer was not read from the file -normally, or if the file itself has been changed for some known benign -reason. -@end defun - -@defun ask-user-about-supersession-threat filename -@cindex obsolete buffer -This function is used to ask a user how to proceed after an attempt to -modify an obsolete buffer visiting file @var{filename}. An -@dfn{obsolete buffer} is an unmodified buffer for which the associated -file on disk is newer than the last save-time of the buffer. This means -some other program has probably altered the file. - -@kindex file-supersession -Depending on the user's answer, the function may return normally, in -which case the modification of the buffer proceeds, or it may signal a -@code{file-supersession} error with data @code{(@var{filename})}, in which -case the proposed buffer modification is not allowed. - -This function is called automatically by Emacs on the proper -occasions. It exists so you can customize Emacs by redefining it. -See the file @file{userlock.el} for the standard definition. - -See also the file locking mechanism in @ref{File Locks}. -@end defun - -@node Read Only Buffers -@section Read-Only Buffers -@cindex read-only buffer -@cindex buffer, read-only - - If a buffer is @dfn{read-only}, then you cannot change its contents, -although you may change your view of the contents by scrolling and -narrowing. - - Read-only buffers are used in two kinds of situations: - -@itemize @bullet -@item -A buffer visiting a write-protected file is normally read-only. - -Here, the purpose is to show the user that editing the buffer with the -aim of saving it in the file may be futile or undesirable. The user who -wants to change the buffer text despite this can do so after clearing -the read-only flag with @kbd{C-x C-q}. - -@item -Modes such as Dired and Rmail make buffers read-only when altering the -contents with the usual editing commands is probably a mistake. - -The special commands of these modes bind @code{buffer-read-only} to -@code{nil} (with @code{let}) or bind @code{inhibit-read-only} to -@code{t} around the places where they change the text. -@end itemize - -@defvar buffer-read-only -This buffer-local variable specifies whether the buffer is read-only. -The buffer is read-only if this variable is non-@code{nil}. -@end defvar - -@defvar inhibit-read-only -If this variable is non-@code{nil}, then read-only buffers and read-only -characters may be modified. Read-only characters in a buffer are those -that have non-@code{nil} @code{read-only} properties (either text -properties or overlay properties). @xref{Special Properties}, for more -information about text properties. @xref{Overlays}, for more -information about overlays and their properties. - -If @code{inhibit-read-only} is @code{t}, all @code{read-only} character -properties have no effect. If @code{inhibit-read-only} is a list, then -@code{read-only} character properties have no effect if they are members -of the list (comparison is done with @code{eq}). -@end defvar - -@deffn Command toggle-read-only -This command changes whether the current buffer is read-only. It is -intended for interactive use; don't use it in programs. At any given -point in a program, you should know whether you want the read-only flag -on or off; so you can set @code{buffer-read-only} explicitly to the -proper value, @code{t} or @code{nil}. -@end deffn - -@defun barf-if-buffer-read-only -This function signals a @code{buffer-read-only} error if the current -buffer is read-only. @xref{Interactive Call}, for another way to -signal an error if the current buffer is read-only. -@end defun - -@node The Buffer List -@section The Buffer List -@cindex buffer list - - The @dfn{buffer list} is a list of all live buffers. Creating a -buffer adds it to this list, and killing a buffer deletes it. The order -of the buffers in the list is based primarily on how recently each -buffer has been displayed in the selected window. Buffers move to the -front of the list when they are selected and to the end when they are -buried. Several functions, notably @code{other-buffer}, use this -ordering. A buffer list displayed for the user also follows this order. - -@defun buffer-list -This function returns a list of all buffers, including those whose names -begin with a space. The elements are actual buffers, not their names. - -@example -@group -(buffer-list) - @result{} (#<buffer buffers.texi> - #<buffer *Minibuf-1*> #<buffer buffer.c> - #<buffer *Help*> #<buffer TAGS>) -@end group - -@group -;; @r{Note that the name of the minibuffer} -;; @r{begins with a space!} -(mapcar (function buffer-name) (buffer-list)) - @result{} ("buffers.texi" " *Minibuf-1*" - "buffer.c" "*Help*" "TAGS") -@end group -@end example -@end defun - - The list that @code{buffer-list} returns is constructed specifically -by @code{buffer-list}; it is not an internal Emacs data structure, and -modifying it has no effect on the order of buffers. If you want to -change the order of buffers in the list, here is an easy way: - -@example -(defun reorder-buffer-list (new-list) - (while new-list - (bury-buffer (car new-list)) - (setq new-list (cdr new-list)))) -@end example - - With this method, you can specify any order for the list, but there is -no danger of losing a buffer or adding something that is not a valid -live buffer. - -@defun other-buffer &optional buffer visible-ok -This function returns the first buffer in the buffer list other than -@var{buffer}. Usually this is the buffer most recently shown in -the selected window, aside from @var{buffer}. Buffers whose -names start with a space are not considered. - -If @var{buffer} is not supplied (or if it is not a buffer), then -@code{other-buffer} returns the first buffer on the buffer list that is -not visible in any window in a visible frame. - -If the selected frame has a non-@code{nil} @code{buffer-predicate} -parameter, then @code{other-buffer} uses that predicate to decide which -buffers to consider. It calls the predicate once for each buffer, and -if the value is @code{nil}, that buffer is ignored. @xref{X Frame -Parameters}. - -@c Emacs 19 feature -If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning -a buffer visible in any window on any visible frame, except as a last -resort. If @var{visible-ok} is non-@code{nil}, then it does not matter -whether a buffer is displayed somewhere or not. - -If no suitable buffer exists, the buffer @samp{*scratch*} is returned -(and created, if necessary). -@end defun - -@deffn Command bury-buffer &optional buffer-or-name -This function puts @var{buffer-or-name} at the end of the buffer list -without changing the order of any of the other buffers on the list. -This buffer therefore becomes the least desirable candidate for -@code{other-buffer} to return. - -If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the -current buffer. In addition, if the buffer is displayed in the selected -window, this switches to some other buffer (obtained using -@code{other-buffer}) in the selected window. But if the buffer is -displayed in some other window, it remains displayed there. - -If you wish to replace a buffer in all the windows that display it, use -@code{replace-buffer-in-windows}. @xref{Buffers and Windows}. -@end deffn - -@node Creating Buffers -@section Creating Buffers -@cindex creating buffers -@cindex buffers, creating - - This section describes the two primitives for creating buffers. -@code{get-buffer-create} creates a buffer if it finds no existing buffer -with the specified name; @code{generate-new-buffer} always creates a new -buffer and gives it a unique name. - - Other functions you can use to create buffers include -@code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and -@code{create-file-buffer} (@pxref{Visiting Files}). Starting a -subprocess can also create a buffer (@pxref{Processes}). - -@defun get-buffer-create name -This function returns a buffer named @var{name}. It returns an existing -buffer with that name, if one exists; otherwise, it creates a new -buffer. The buffer does not become the current buffer---this function -does not change which buffer is current. - -An error is signaled if @var{name} is not a string. - -@example -@group -(get-buffer-create "foo") - @result{} #<buffer foo> -@end group -@end example - -The major mode for the new buffer is set to Fundamental mode. The -variable @code{default-major-mode} is handled at a higher level. -@xref{Auto Major Mode}. -@end defun - -@defun generate-new-buffer name -This function returns a newly created, empty buffer, but does not make -it current. If there is no buffer named @var{name}, then that is the -name of the new buffer. If that name is in use, this function adds -suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an -integer. It tries successive integers starting with 2 until it finds an -available name. - -An error is signaled if @var{name} is not a string. - -@example -@group -(generate-new-buffer "bar") - @result{} #<buffer bar> -@end group -@group -(generate-new-buffer "bar") - @result{} #<buffer bar<2>> -@end group -@group -(generate-new-buffer "bar") - @result{} #<buffer bar<3>> -@end group -@end example - -The major mode for the new buffer is set to Fundamental mode. The -variable @code{default-major-mode} is handled at a higher level. -@xref{Auto Major Mode}. - -See the related function @code{generate-new-buffer-name} in @ref{Buffer -Names}. -@end defun - -@node Killing Buffers -@section Killing Buffers -@cindex killing buffers -@cindex buffers, killing - - @dfn{Killing a buffer} makes its name unknown to Emacs and makes its -text space available for other use. - - The buffer object for the buffer that has been killed remains in -existence as long as anything refers to it, but it is specially marked -so that you cannot make it current or display it. Killed buffers retain -their identity, however; two distinct buffers, when killed, remain -distinct according to @code{eq}. - - If you kill a buffer that is current or displayed in a window, Emacs -automatically selects or displays some other buffer instead. This means -that killing a buffer can in general change the current buffer. -Therefore, when you kill a buffer, you should also take the precautions -associated with changing the current buffer (unless you happen to know -that the buffer being killed isn't current). @xref{Current Buffer}. - - If you kill a buffer that is the base buffer of one or more indirect -buffers, the indirect buffers are automatically killed as well. - - The @code{buffer-name} of a killed buffer is @code{nil}. You can use -this feature to test whether a buffer has been killed: - -@example -@group -(defun buffer-killed-p (buffer) - "Return t if BUFFER is killed." - (not (buffer-name buffer))) -@end group -@end example - -@deffn Command kill-buffer buffer-or-name -This function kills the buffer @var{buffer-or-name}, freeing all its -memory for other uses or to be returned to the operating system. It -returns @code{nil}. - -Any processes that have this buffer as the @code{process-buffer} are -sent the @code{SIGHUP} signal, which normally causes them to terminate. -(The basic meaning of @code{SIGHUP} is that a dialup line has been -disconnected.) @xref{Deleting Processes}. - -If the buffer is visiting a file and contains unsaved changes, -@code{kill-buffer} asks the user to confirm before the buffer is killed. -It does this even if not called interactively. To prevent the request -for confirmation, clear the modified flag before calling -@code{kill-buffer}. @xref{Buffer Modification}. - -Killing a buffer that is already dead has no effect. - -@smallexample -(kill-buffer "foo.unchanged") - @result{} nil -(kill-buffer "foo.changed") - ----------- Buffer: Minibuffer ---------- -Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} ----------- Buffer: Minibuffer ---------- - - @result{} nil -@end smallexample -@end deffn - -@defvar kill-buffer-query-functions -After confirming unsaved changes, @code{kill-buffer} calls the functions -in the list @code{kill-buffer-query-functions}, in order of appearance, -with no arguments. The buffer being killed is the current buffer when -they are called. The idea is that these functions ask for confirmation -from the user for various nonstandard reasons. If any of them returns -@code{nil}, @code{kill-buffer} spares the buffer's life. -@end defvar - -@defvar kill-buffer-hook -This is a normal hook run by @code{kill-buffer} after asking all the -questions it is going to ask, just before actually killing the buffer. -The buffer to be killed is current when the hook functions run. -@xref{Hooks}. -@end defvar - -@defvar buffer-offer-save -This variable, if non-@code{nil} in a particular buffer, tells -@code{save-buffers-kill-emacs} and @code{save-some-buffers} to offer to -save that buffer, just as they offer to save file-visiting buffers. The -variable @code{buffer-offer-save} automatically becomes buffer-local -when set for any reason. @xref{Buffer-Local Variables}. -@end defvar - -@node Indirect Buffers -@section Indirect Buffers -@cindex indirect buffers -@cindex base buffer - - An @dfn{indirect buffer} shares the text of some other buffer, which -is called the @dfn{base buffer} of the indirect buffer. In some ways it -is the analogue, for buffers, of a symbolic link among files. The base -buffer may not itself be an indirect buffer. - - The text of the indirect buffer is always identical to the text of its -base buffer; changes made by editing either one are visible immediately -in the other. This includes the text properties as well as the characters -themselves. - - But in all other respects, the indirect buffer and its base buffer are -completely separate. They have different names, different values of -point, different narrowing, different markers and overlays (though -inserting or deleting text in either buffer relocates the markers and -overlays for both), different major modes, and different local -variables. - - An indirect buffer cannot visit a file, but its base buffer can. If -you try to save the indirect buffer, that actually works by saving the -base buffer. - - Killing an indirect buffer has no effect on its base buffer. Killing -the base buffer effectively kills the indirect buffer in that it cannot -ever again be the current buffer. - -@deffn Command make-indirect-buffer base-buffer name -This creates an indirect buffer named @var{name} whose base buffer -is @var{base-buffer}. The argument @var{base-buffer} may be a buffer -or a string. - -If @var{base-buffer} is an indirect buffer, its base buffer is used as -the base for the new buffer. -@end deffn - -@defun buffer-base-buffer buffer -This function returns the base buffer of @var{buffer}. If @var{buffer} -is not indirect, the value is @code{nil}. Otherwise, the value is -another buffer, which is never an indirect buffer. -@end defun - diff --git a/lispref/calendar.texi b/lispref/calendar.texi deleted file mode 100644 index 8e42a530f25..00000000000 --- a/lispref/calendar.texi +++ /dev/null @@ -1,908 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@node Calendar, Tips, Display, Top -@chapter Customizing the Calendar and Diary - - There are many customizations that you can use to make the calendar and -diary suit your personal tastes. - -@menu -* Calendar Customizing:: Defaults you can set. -* Holiday Customizing:: Defining your own holidays. -* Date Display Format:: Changing the format. -* Time Display Format:: Changing the format. -* Daylight Savings:: Changing the default. -* Diary Customizing:: Defaults you can set. -* Hebrew/Islamic Entries:: How to obtain them. -* Fancy Diary Display:: Enhancing the diary display, sorting entries, - using included diary files. -* Sexp Diary Entries:: Fancy things you can do. -* Appt Customizing:: Customizing appointment reminders. -@end menu - -@node Calendar Customizing -@section Customizing the Calendar -@vindex view-diary-entries-initially - - If you set the variable @code{view-diary-entries-initially} to -@code{t}, calling up the calendar automatically displays the diary -entries for the current date as well. The diary dates appear only if -the current date is visible. If you add both of the following lines to -your @file{.emacs} file:@refill - -@example -(setq view-diary-entries-initially t) -(calendar) -@end example - -@noindent -this displays both the calendar and diary windows whenever you start Emacs. - -@vindex view-calendar-holidays-initially - Similarly, if you set the variable -@code{view-calendar-holidays-initially} to @code{t}, entering the -calendar automatically displays a list of holidays for the current -three-month period. The holiday list appears in a separate -window. - -@vindex mark-diary-entries-in-calendar - You can set the variable @code{mark-diary-entries-in-calendar} to -@code{t} in order to mark any dates with diary entries. This takes -effect whenever the calendar window contents are recomputed. There are -two ways of marking these dates: by changing the face (@pxref{Faces}), -if the display supports that, or by placing a plus sign (@samp{+}) -beside the date otherwise. - -@vindex mark-holidays-in-calendar - Similarly, setting the variable @code{mark-holidays-in-calendar} to -@code{t} marks holiday dates, either with a change of face or with an -asterisk (@samp{*}). - -@vindex calendar-holiday-marker -@vindex diary-entry-marker - The variable @code{calendar-holiday-marker} specifies how to mark a -date as being a holiday. Its value may be a character to insert next to -the date, or a face name to use for displaying the date. Likewise, the -variable @code{diary-entry-marker} specifies how to mark a date that has -diary entries. The calendar creates faces named @code{holiday-face} and -@code{diary-face} for these purposes; those symbols are the default -values of these variables, when Emacs supports multiple faces on your -terminal. - -@vindex calendar-load-hook - The variable @code{calendar-load-hook} is a normal hook run when the -calendar package is first loaded (before actually starting to display -the calendar). - -@vindex initial-calendar-window-hook - Starting the calendar runs the normal hook -@code{initial-calendar-window-hook}. Recomputation of the calendar -display does not run this hook. But if you leave the calendar with the -@kbd{q} command and reenter it, the hook runs again.@refill - -@vindex today-visible-calendar-hook - The variable @code{today-visible-calendar-hook} is a normal hook run -after the calendar buffer has been prepared with the calendar when the -current date is visible in the window. One use of this hook is to -replace today's date with asterisks; to do that, use the hook function -@code{calendar-star-date}. - -@findex calendar-star-date -@example -(add-hook 'today-visible-calendar-hook 'calendar-star-date) -@end example - -@noindent -Another standard hook function marks the current date, either by -changing its face or by adding an asterisk. Here's how to use it: - -@findex calendar-mark-today -@example -(add-hook 'today-visible-calendar-hook 'calendar-mark-today) -@end example - -@noindent -@vindex calendar-today-marker -The variable @code{calendar-today-marker} specifies how to mark today's -date. Its value should be a character to insert next to the date or a -face name to use for displaying the date. A face named -@code{calendar-today-face} is provided for this purpose; that symbol is -the default for this variable when Emacs supports multiple faces on your -terminal. - -@vindex today-invisible-calendar-hook -@noindent - A similar normal hook, @code{today-invisible-calendar-hook} is run if -the current date is @emph{not} visible in the window. - -@node Holiday Customizing -@section Customizing the Holidays - -@vindex calendar-holidays -@vindex christian-holidays -@vindex hebrew-holidays -@vindex islamic-holidays - Emacs knows about holidays defined by entries on one of several lists. -You can customize these lists of holidays to your own needs, adding or -deleting holidays. The lists of holidays that Emacs uses are for -general holidays (@code{general-holidays}), local holidays -(@code{local-holidays}), Christian holidays (@code{christian-holidays}), -Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Moslem) -holidays (@code{islamic-holidays}), and other holidays -(@code{other-holidays}). - -@vindex general-holidays - The general holidays are, by default, holidays common throughout the -United States. To eliminate these holidays, set @code{general-holidays} -to @code{nil}. - -@vindex local-holidays - There are no default local holidays (but sites may supply some). You -can set the variable @code{local-holidays} to any list of holidays, as -described below. - -@vindex all-christian-calendar-holidays -@vindex all-hebrew-calendar-holidays -@vindex all-islamic-calendar-holidays - By default, Emacs does not include all the holidays of the religions -that it knows, only those commonly found in secular calendars. For a -more extensive collection of religious holidays, you can set any (or -all) of the variables @code{all-christian-calendar-holidays}, -@code{all-hebrew-calendar-holidays}, or -@code{all-islamic-calendar-holidays} to @code{t}. If you want to -eliminate the religious holidays, set any or all of the corresponding -variables @code{christian-holidays}, @code{hebrew-holidays}, and -@code{islamic-holidays} to @code{nil}.@refill - -@vindex other-holidays - You can set the variable @code{other-holidays} to any list of -holidays. This list, normally empty, is intended for individual use. - -@cindex holiday forms - Each of the lists (@code{general-holidays}, @code{local-holidays}, -@code{christian-holidays}, @code{hebrew-holidays}, -@code{islamic-holidays}, and @code{other-holidays}) is a list of -@dfn{holiday forms}, each holiday form describing a holiday (or -sometimes a list of holidays). - - Here is a table of the possible kinds of holiday form. Day numbers -and month numbers count starting from 1, but ``dayname'' numbers -count Sunday as 0. The element @var{string} is always the -name of the holiday, as a string. - -@table @code -@item (holiday-fixed @var{month} @var{day} @var{string}) -A fixed date on the Gregorian calendar. - -@item (holiday-float @var{month} @var{dayname} @var{k} @var{string}) -The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar -(@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back -from the end of the month. - -@item (holiday-hebrew @var{month} @var{day} @var{string}) -A fixed date on the Hebrew calendar. - -@item (holiday-islamic @var{month} @var{day} @var{string}) -A fixed date on the Islamic calendar. - -@item (holiday-julian @var{month} @var{day} @var{string}) -A fixed date on the Julian calendar. - -@item (holiday-sexp @var{sexp} @var{string}) -A date calculated by the Lisp expression @var{sexp}. The expression -should use the variable @code{year} to compute and return the date of a -holiday, or @code{nil} if the holiday doesn't happen this year. The -value of @var{sexp} must represent the date as a list of the form -@code{(@var{month} @var{day} @var{year})}. - -@item (if @var{condition} @var{holiday-form}) -A holiday that happens only if @var{condition} is true. - -@item (@var{function} @r{[}@var{args}@r{]}) -A list of dates calculated by the function @var{function}, called with -arguments @var{args}. -@end table - - For example, suppose you want to add Bastille Day, celebrated in -France on July 14. You can do this as follows: - -@smallexample -(setq other-holidays '((holiday-fixed 7 14 "Bastille Day"))) -@end smallexample - -@noindent -The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the -fourteenth day of the seventh month (July). - - Many holidays occur on a specific day of the week, at a specific time -of month. Here is a holiday form describing Hurricane Supplication Day, -celebrated in the Virgin Islands on the fourth Monday in August: - -@smallexample -(holiday-float 8 1 4 "Hurricane Supplication Day") -@end smallexample - -@noindent -Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, -Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in -the month (1 specifies the first occurrence, 2 the second occurrence, -@minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and -so on). - - You can specify holidays that occur on fixed days of the Hebrew, -Islamic, and Julian calendars too. For example, - -@smallexample -(setq other-holidays - '((holiday-hebrew 10 2 "Last day of Hanukkah") - (holiday-islamic 3 12 "Mohammed's Birthday") - (holiday-julian 4 2 "Jefferson's Birthday"))) -@end smallexample - -@noindent -adds the last day of Hanukkah (since the Hebrew months are numbered with -1 starting from Nisan), the Islamic feast celebrating Mohammed's -birthday (since the Islamic months are numbered from 1 starting with -Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the -Julian calendar. - - To include a holiday conditionally, use either Emacs Lisp's @code{if} or the -@code{holiday-sexp} form. For example, American presidential elections -occur on the first Tuesday after the first Monday in November of years -divisible by 4: - -@smallexample -(holiday-sexp (if (= 0 (% year 4)) - (calendar-gregorian-from-absolute - (1+ (calendar-dayname-on-or-before - 1 (+ 6 (calendar-absolute-from-gregorian - (list 11 1 year)))))) - "US Presidential Election")) -@end smallexample - -@noindent -or - -@smallexample -(if (= 0 (% displayed-year 4)) - (fixed 11 - (extract-calendar-day - (calendar-gregorian-from-absolute - (1+ (calendar-dayname-on-or-before - 1 (+ 6 (calendar-absolute-from-gregorian - (list 11 1 displayed-year))))))) - "US Presidential Election")) -@end smallexample - - Some holidays just don't fit into any of these forms because special -calculations are involved in their determination. In such cases you -must write a Lisp function to do the calculation. To include eclipses, -for example, add @code{(eclipses)} to @code{other-holidays} -and write an Emacs Lisp function @code{eclipses} that returns a -(possibly empty) list of the relevant Gregorian dates among the range -visible in the calendar window, with descriptive strings, like this: - -@smallexample -(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... ) -@end smallexample - -@node Date Display Format -@section Date Display Format -@vindex calendar-date-display-form - - You can customize the manner of displaying dates in the diary, in mode -lines, and in messages by setting @code{calendar-date-display-form}. -This variable holds a list of expressions that can involve the variables -@code{month}, @code{day}, and @code{year}, which are all numbers in -string form, and @code{monthname} and @code{dayname}, which are both -alphabetic strings. In the American style, the default value of this -list is as follows: - -@smallexample -((if dayname (concat dayname ", ")) monthname " " day ", " year) -@end smallexample - -@noindent -while in the European style this value is the default: - -@smallexample -((if dayname (concat dayname ", ")) day " " monthname " " year) -@end smallexample - -@noindent -The ISO standard date representation is this: - -@smallexample -(year "-" month "-" day) -@end smallexample - -@noindent -This specifies a typical American format: - -@smallexample -(month "/" day "/" (substring year -2)) -@end smallexample - -@node Time Display Format -@section Time Display Format -@vindex calendar-time-display-form - - The calendar and diary by default display times of day in the -conventional American style with the hours from 1 through 12, minutes, -and either @samp{am} or @samp{pm}. If you prefer the European style, -also known in the US as military, in which the hours go from 00 to 23, -you can alter the variable @code{calendar-time-display-form}. This -variable is a list of expressions that can involve the variables -@code{12-hours}, @code{24-hours}, and @code{minutes}, which are all -numbers in string form, and @code{am-pm} and @code{time-zone}, which are -both alphabetic strings. The default value of -@code{calendar-time-display-form} is as follows: - -@smallexample -(12-hours ":" minutes am-pm - (if time-zone " (") time-zone (if time-zone ")")) -@end smallexample - -@noindent -Here is a value that provides European style times: - -@smallexample -(24-hours ":" minutes - (if time-zone " (") time-zone (if time-zone ")")) -@end smallexample - -@node Daylight Savings -@section Daylight Savings Time -@cindex daylight savings time - - Emacs understands the difference between standard time and daylight -savings time---the times given for sunrise, sunset, solstices, -equinoxes, and the phases of the moon take that into account. The rules -for daylight savings time vary from place to place and have also varied -historically from year to year. To do the job properly, Emacs needs to -know which rules to use. - - Some operating systems keep track of the rules that apply to the place -where you are; on these systems, Emacs gets the information it needs -from the system automatically. If some or all of this information is -missing, Emacs fills in the gaps with the rules currently used in -Cambridge, Massachusetts, which is the center of GNU's world. - - -@vindex calendar-daylight-savings-starts -@vindex calendar-daylight-savings-ends - If the default choice of rules is not appropriate for your location, -you can tell Emacs the rules to use by setting the variables -@code{calendar-daylight-savings-starts} and -@code{calendar-daylight-savings-ends}. Their values should be Lisp -expressions that refer to the variable @code{year}, and evaluate to the -Gregorian date on which daylight savings time starts or (respectively) -ends, in the form of a list @code{(@var{month} @var{day} @var{year})}. -The values should be @code{nil} if your area does not use daylight -savings time. - - Emacs uses these expressions to determine the start and end dates of -daylight savings time as holidays and for correcting times of day in the -solar and lunar calculations. - - The values for Cambridge, Massachusetts are as follows: - -@example -@group -(calendar-nth-named-day 1 0 4 year) -(calendar-nth-named-day -1 0 10 year) -@end group -@end example - -@noindent -i.e., the first 0th day (Sunday) of the fourth month (April) in -the year specified by @code{year}, and the last Sunday of the tenth month -(October) of that year. If daylight savings time were -changed to start on October 1, you would set -@code{calendar-daylight-savings-starts} to this: - -@example -(list 10 1 year) -@end example - - For a more complex example, suppose daylight savings time begins on -the first of Nisan on the Hebrew calendar. You should set -@code{calendar-daylight-savings-starts} to this value: - -@example -(calendar-gregorian-from-absolute - (calendar-absolute-from-hebrew - (list 1 1 (+ year 3760)))) -@end example - -@noindent -because Nisan is the first month in the Hebrew calendar and the Hebrew -year differs from the Gregorian year by 3760 at Nisan. - - If there is no daylight savings time at your location, or if you want -all times in standard time, set @code{calendar-daylight-savings-starts} -and @code{calendar-daylight-savings-ends} to @code{nil}. - -@vindex calendar-daylight-time-offset - The variable @code{calendar-daylight-time-offset} specifies the -difference between daylight savings time and standard time, measured in -minutes. The value for Cambridge is 60. - -@vindex calendar-daylight-savings-starts-time -@vindex calendar-daylight-savings-ends-time - The variable @code{calendar-daylight-savings-starts-time} and the -variable @code{calendar-daylight-savings-ends-time} specify the number -of minutes after midnight local time when the transition to and from -daylight savings time should occur. For Cambridge, both variables' -values are 120. - -@node Diary Customizing -@section Customizing the Diary - -@vindex holidays-in-diary-buffer - Ordinarily, the mode line of the diary buffer window indicates any -holidays that fall on the date of the diary entries. The process of -checking for holidays can take several seconds, so including holiday -information delays the display of the diary buffer noticeably. If you'd -prefer to have a faster display of the diary buffer but without the -holiday information, set the variable @code{holidays-in-diary-buffer} to -@code{nil}.@refill - -@vindex number-of-diary-entries - The variable @code{number-of-diary-entries} controls the number of -days of diary entries to be displayed at one time. It affects the -initial display when @code{view-diary-entries-initially} is @code{t}, as -well as the command @kbd{M-x diary}. For example, the default value is -1, which says to display only the current day's diary entries. If the -value is 2, both the current day's and the next day's entries are -displayed. The value can also be a vector of seven elements: for -example, if the value is @code{[0 2 2 2 2 4 1]} then no diary entries -appear on Sunday, the current date's and the next day's diary entries -appear Monday through Thursday, Friday through Monday's entries appear -on Friday, while on Saturday only that day's entries appear. - -@vindex print-diary-entries-hook -@findex print-diary-entries - The variable @code{print-diary-entries-hook} is a normal hook run -after preparation of a temporary buffer containing just the diary -entries currently visible in the diary buffer. (The other, irrelevant -diary entries are really absent from the temporary buffer; in the diary -buffer, they are merely hidden.) The default value of this hook does -the printing with the command @code{lpr-buffer}. If you want to use a -different command to do the printing, just change the value of this -hook. Other uses might include, for example, rearranging the lines into -order by day and time. - -@vindex diary-date-forms - You can customize the form of dates in your diary file, if neither the -standard American nor European styles suits your needs, by setting the -variable @code{diary-date-forms}. This variable is a list of patterns -for recognizing a date. Each date pattern is a list whose elements may -be regular expressions (@pxref{Regular Expressions}) or the symbols -@code{month}, @code{day}, @code{year}, @code{monthname}, and -@code{dayname}. All these elements serve as patterns that match certain -kinds of text in the diary file. In order for the date pattern, as a -whole, to match, all of its elements must match consecutively. - - A regular expression in a date pattern matches in its usual fashion, -using the standard syntax table altered so that @samp{*} is a word -constituent. - - The symbols @code{month}, @code{day}, @code{year}, @code{monthname}, -and @code{dayname} match the month number, day number, year number, -month name, and day name of the date being considered. The symbols that -match numbers allow leading zeros; those that match names allow -three-letter abbreviations and capitalization. All the symbols can -match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any -month'', and so on, it should match regardless of the date being -considered. - - The default value of @code{diary-date-forms} in the American style is -this: - -@example -((month "/" day "[^/0-9]") - (month "/" day "/" year "[^0-9]") - (monthname " *" day "[^,0-9]") - (monthname " *" day ", *" year "[^0-9]") - (dayname "\\W")) -@end example - - The date patterns in the list must be @emph{mutually exclusive} and -must not match any portion of the diary entry itself, just the date and -one character of whitespace. If, to be mutually exclusive, the pattern -must match a portion of the diary entry text---beyond the whitespace -that ends the date---then the first element of the date pattern -@emph{must} be @code{backup}. This causes the date recognizer to back -up to the beginning of the current word of the diary entry, after -finishing the match. Even if you use @code{backup}, the date pattern -must absolutely not match more than a portion of the first word of the -diary entry. The default value of @code{diary-date-forms} in the -European style is this list: - -@example -((day "/" month "[^/0-9]") - (day "/" month "/" year "[^0-9]") - (backup day " *" monthname "\\W+\\<[^*0-9]") - (day " *" monthname " *" year "[^0-9]") - (dayname "\\W")) -@end example - -@noindent -Notice the use of @code{backup} in the third pattern, because it needs -to match part of a word beyond the date itself to distinguish it from -the fourth pattern. - -@node Hebrew/Islamic Entries -@section Hebrew- and Islamic-Date Diary Entries - - Your diary file can have entries based on Hebrew or Islamic dates, as -well as entries based on the world-standard Gregorian calendar. -However, because recognition of such entries is time-consuming and most -people don't use them, you must explicitly enable their use. If you -want the diary to recognize Hebrew-date diary entries, for example, -you must do this: - -@vindex nongregorian-diary-listing-hook -@vindex nongregorian-diary-marking-hook -@findex list-hebrew-diary-entries -@findex mark-hebrew-diary-entries -@smallexample -(add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries) -(add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries) -@end smallexample - -@noindent -If you want Islamic-date entries, do this: - -@findex list-islamic-diary-entries -@findex mark-islamic-diary-entries -@smallexample -(add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries) -(add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries) -@end smallexample - - Hebrew- and Islamic-date diary entries have the same formats as -Gregorian-date diary entries, except that @samp{H} precedes a Hebrew -date and @samp{I} precedes an Islamic date. Moreover, because the -Hebrew and Islamic month names are not uniquely specified by the first -three letters, you may not abbreviate them. For example, a diary entry -for the Hebrew date Heshvan 25 could look like this: - -@smallexample -HHeshvan 25 Happy Hebrew birthday! -@end smallexample - -@noindent -and would appear in the diary for any date that corresponds to Heshvan 25 -on the Hebrew calendar. And here is Islamic-date diary entry that matches -Dhu al-Qada 25: - -@smallexample -IDhu al-Qada 25 Happy Islamic birthday! -@end smallexample - - As with Gregorian-date diary entries, Hebrew- and Islamic-date entries -are nonmarking if they are preceded with an ampersand (@samp{&}). - - Here is a table of commands used in the calendar to create diary entries -that match the selected date and other dates that are similar in the Hebrew -or Islamic calendar: - -@table @kbd -@item i h d -Add a diary entry for the Hebrew date corresponding to the selected date -(@code{insert-hebrew-diary-entry}). -@item i h m -Add a diary entry for the day of the Hebrew month corresponding to the -selected date (@code{insert-monthly-hebrew-diary-entry}). This diary -entry matches any date that has the same Hebrew day-within-month as the -selected date. -@item i h y -Add a diary entry for the day of the Hebrew year corresponding to the -selected date (@code{insert-yearly-hebrew-diary-entry}). This diary -entry matches any date which has the same Hebrew month and day-within-month -as the selected date. -@item i i d -Add a diary entry for the Islamic date corresponding to the selected date -(@code{insert-islamic-diary-entry}). -@item i i m -Add a diary entry for the day of the Islamic month corresponding to the -selected date (@code{insert-monthly-islamic-diary-entry}). -@item i i y -Add a diary entry for the day of the Islamic year corresponding to the -selected date (@code{insert-yearly-islamic-diary-entry}). -@end table - -@findex insert-hebrew-diary-entry -@findex insert-monthly-hebrew-diary-entry -@findex insert-yearly-hebrew-diary-entry -@findex insert-islamic-diary-entry -@findex insert-monthly-islamic-diary-entry -@findex insert-yearly-islamic-diary-entry - These commands work much like the corresponding commands for ordinary -diary entries: they apply to the date that point is on in the calendar -window, and what they do is insert just the date portion of a diary entry -at the end of your diary file. You must then insert the rest of the -diary entry. - -@node Fancy Diary Display -@section Fancy Diary Display -@vindex diary-display-hook -@findex simple-diary-display - - Diary display works by preparing the diary buffer and then running the -hook @code{diary-display-hook}. The default value of this hook -(@code{simple-diary-display}) hides the irrelevant diary entries and -then displays the buffer. However, if you specify the hook as follows, - -@cindex diary buffer -@findex fancy-diary-display -@example -(add-hook 'diary-display-hook 'fancy-diary-display) -@end example - -@noindent -this enables fancy diary display. It displays diary entries and -holidays by copying them into a special buffer that exists only for the -sake of display. Copying to a separate buffer provides an opportunity -to change the displayed text to make it prettier---for example, to sort -the entries by the dates they apply to. - - As with simple diary display, you can print a hard copy of the buffer -with @code{print-diary-entries}. To print a hard copy of a day-by-day -diary for a week by positioning point on Sunday of that week, type -@kbd{7 d} and then do @kbd{M-x print-diary-entries}. As usual, the -inclusion of the holidays slows down the display slightly; you can speed -things up by setting the variable @code{holidays-in-diary-buffer} to -@code{nil}. - -@vindex diary-list-include-blanks - Ordinarily, the fancy diary buffer does not show days for which there are -no diary entries, even if that day is a holiday. If you want such days to be -shown in the fancy diary buffer, set the variable -@code{diary-list-include-blanks} to @code{t}.@refill - -@cindex sorting diary entries - If you use the fancy diary display, you can use the normal hook -@code{list-diary-entries-hook} to sort each day's diary entries by their -time of day. Here's how - -@findex sort-diary-entries -@example -(add-hook 'list-diary-entries-hook 'sort-diary-entries t) -@end example - -@noindent -For each day, this sorts diary entries that begin with a recognizable -time of day according to their times. Diary entries without times come -first within each day. - - Fancy diary display also has the ability to process included diary -files. This permits a group of people to share a diary file for events -that apply to all of them. Lines in the diary file of this form: - -@smallexample -#include "@var{filename}" -@end smallexample - -@noindent -includes the diary entries from the file @var{filename} in the fancy -diary buffer. The include mechanism is recursive, so that included files -can include other files, and so on; you must be careful not to have a -cycle of inclusions, of course. Here is how to enable the include -facility: - -@vindex list-diary-entries-hook -@vindex mark-diary-entries-hook -@findex include-other-diary-files -@findex mark-included-diary-files -@smallexample -(add-hook 'list-diary-entries-hook 'include-other-diary-files) -(add-hook 'mark-diary-entries-hook 'mark-included-diary-files) -@end smallexample - -The include mechanism works only with the fancy diary display, because -ordinary diary display shows the entries directly from your diary file. - -@node Sexp Diary Entries -@section Sexp Entries and the Fancy Diary Display -@cindex sexp diary entries - - Sexp diary entries allow you to do more than just have complicated -conditions under which a diary entry applies. If you use the fancy -diary display, sexp entries can generate the text of the entry depending -on the date itself. For example, an anniversary diary entry can insert -the number of years since the anniversary date into the text of the -diary entry. Thus the @samp{%d} in this dairy entry: - -@findex diary-anniversary -@smallexample -%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) -@end smallexample - -@noindent -gets replaced by the age, so on October 31, 1990 the entry appears in -the fancy diary buffer like this: - -@smallexample -Arthur's birthday (42 years old) -@end smallexample - -@noindent -If the diary file instead contains this entry: - -@smallexample -%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday -@end smallexample - -@noindent -the entry in the fancy diary buffer for October 31, 1990 appears like this: - -@smallexample -Arthur's 42nd birthday -@end smallexample - - Similarly, cyclic diary entries can interpolate the number of repetitions -that have occurred: - -@findex diary-cyclic -@smallexample -%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) -@end smallexample - -@noindent -looks like this: - -@smallexample -Renew medication (5th time) -@end smallexample - -@noindent -in the fancy diary display on September 8, 1990. - - The generality of sexp diary entries lets you specify any diary entry -that you can describe algorithmically. A sexp diary entry contains an -expression that computes whether the entry applies to any given date. -If its value is non-@code{nil}, the entry applies to that date; -otherwise, it does not. The expression can use the variable @code{date} -to find the date being considered; its value is a list (@var{month} -@var{day} @var{year}) that refers to the Gregorian calendar. - - Suppose you get paid on the 21st of the month if it is a weekday, and -on the Friday before if the 21st is on a weekend. Here is how to write -a sexp diary entry that matches those dates: - -@smallexample -&%%(let ((dayname (calendar-day-of-week date)) - (day (car (cdr date)))) - (or (and (= day 21) (memq dayname '(1 2 3 4 5))) - (and (memq day '(19 20)) (= dayname 5))) - ) Pay check deposited -@end smallexample - - The following sexp diary entries take advantage of the ability (in the fancy -diary display) to concoct diary entries whose text varies based on the date: - -@findex diary-sunrise-sunset -@findex diary-phases-of-moon -@findex diary-day-of-year -@findex diary-iso-date -@findex diary-julian-date -@findex diary-astro-day-number -@findex diary-hebrew-date -@findex diary-islamic-date -@findex diary-french-date -@findex diary-mayan-date -@table @code -@item %%(diary-sunrise-sunset) -Make a diary entry for the local times of today's sunrise and sunset. -@item %%(diary-phases-of-moon) -Make a diary entry for the phases (quarters) of the moon. -@item %%(diary-day-of-year) -Make a diary entry with today's day number in the current year and the number -of days remaining in the current year. -@item %%(diary-iso-date) -Make a diary entry with today's equivalent ISO commercial date. -@item %%(diary-julian-date) -Make a diary entry with today's equivalent date on the Julian calendar. -@item %%(diary-astro-day-number) -Make a diary entry with today's equivalent astronomical (Julian) day number. -@item %%(diary-hebrew-date) -Make a diary entry with today's equivalent date on the Hebrew calendar. -@item %%(diary-islamic-date) -Make a diary entry with today's equivalent date on the Islamic calendar. -@item %%(diary-french-date) -Make a diary entry with today's equivalent date on the French Revolutionary -calendar. -@item %%(diary-mayan-date) -Make a diary entry with today's equivalent date on the Mayan calendar. -@end table - -@noindent -Thus including the diary entry - -@example -&%%(diary-hebrew-date) -@end example - -@noindent -causes every day's diary display to contain the equivalent date on the -Hebrew calendar, if you are using the fancy diary display. (With simple -diary display, the line @samp{&%%(diary-hebrew-date)} appears in the -diary for any date, but does nothing particularly useful.) - - These functions can be used to construct sexp diary entries based on -the Hebrew calendar in certain standard ways: - -@cindex rosh hodesh -@findex diary-rosh-hodesh -@cindex parasha, weekly -@findex diary-parasha -@cindex candle lighting times -@findex diary-sabbath-candles -@cindex omer count -@findex diary-omer -@cindex yahrzeits -@findex diary-yahrzeit -@table @code -@item %%(diary-rosh-hodesh) -Make a diary entry that tells the occurrence and ritual announcement of each -new Hebrew month. -@item %%(diary-parasha) -Make a Saturday diary entry that tells the weekly synagogue scripture reading. -@item %%(diary-sabbath-candles) -Make a Friday diary entry that tells the @emph{local time} of Sabbath -candle lighting. -@item %%(diary-omer) -Make a diary entry that gives the omer count, when appropriate. -@item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name} -Make a diary entry marking the anniversary of a date of death. The date -is the @emph{Gregorian} (civil) date of death. The diary entry appears -on the proper Hebrew calendar anniversary and on the day before. (In -the European style, the order of the parameters is changed to @var{day}, -@var{month}, @var{year}.) -@end table - -@node Appt Customizing -@section Customizing Appointment Reminders - - You can specify exactly how Emacs reminds you of an appointment, and -how far in advance it begins doing so, by setting these variables: - -@vindex appt-message-warning-time -@vindex appt-audible -@vindex appt-visible -@vindex appt-display-mode-line -@vindex appt-msg-window -@vindex appt-display-duration -@vindex appt-disp-window-function -@vindex appt-delete-window-function -@table @code -@item appt-message-warning-time -The time in minutes before an appointment that the reminder begins. The -default is 10 minutes. -@item appt-audible -If this is non-@code{nil}, Emacs rings the -terminal bell for appointment reminders. The default is @code{t}. -@item appt-visible -If this is non-@code{nil}, Emacs displays the appointment -message in the echo area. The default is @code{t}. -@item appt-display-mode-line -If this is non-@code{nil}, Emacs displays the number of minutes -to the appointment on the mode line. The default is @code{t}. -@item appt-msg-window -If this is non-@code{nil}, Emacs displays the appointment -message in another window. The default is @code{t}. -@item appt-disp-window-function -This variable holds a function to use to create the other window -for the appointment message. -@item appt-delete-window-function -This variable holds a function to use to get rid of the appointment -message window, when its time is up. -@item appt-display-duration -The number of seconds to display an appointment message. The default -is 5 seconds. -@end table diff --git a/lispref/commands.texi b/lispref/commands.texi deleted file mode 100644 index d8199e27161..00000000000 --- a/lispref/commands.texi +++ /dev/null @@ -1,2493 +0,0 @@ -@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/commands -@node Command Loop, Keymaps, Minibuffers, Top -@chapter Command Loop -@cindex editor command loop -@cindex command loop - - When you run Emacs, it enters the @dfn{editor command loop} almost -immediately. This loop reads key sequences, executes their definitions, -and displays the results. In this chapter, we describe how these things -are done, and the subroutines that allow Lisp programs to do them. - -@menu -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. -@end menu - -@node Command Overview -@section Command Loop Overview - - The first thing the command loop must do is read a key sequence, which -is a sequence of events that translates into a command. It does this by -calling the function @code{read-key-sequence}. Your Lisp code can also -call this function (@pxref{Key Sequence Input}). Lisp programs can also -do input at a lower level with @code{read-event} (@pxref{Reading One -Event}) or discard pending input with @code{discard-input} -(@pxref{Event Input Misc}). - - The key sequence is translated into a command through the currently -active keymaps. @xref{Key Lookup}, for information on how this is done. -The result should be a keyboard macro or an interactively callable -function. If the key is @kbd{M-x}, then it reads the name of another -command, which it then calls. This is done by the command -@code{execute-extended-command} (@pxref{Interactive Call}). - - To execute a command requires first reading the arguments for it. -This is done by calling @code{command-execute} (@pxref{Interactive -Call}). For commands written in Lisp, the @code{interactive} -specification says how to read the arguments. This may use the prefix -argument (@pxref{Prefix Command Arguments}) or may read with prompting -in the minibuffer (@pxref{Minibuffers}). For example, the command -@code{find-file} has an @code{interactive} specification which says to -read a file name using the minibuffer. The command's function body does -not use the minibuffer; if you call this command from Lisp code as a -function, you must supply the file name string as an ordinary Lisp -function argument. - - If the command is a string or vector (i.e., a keyboard macro) then -@code{execute-kbd-macro} is used to execute it. You can call this -function yourself (@pxref{Keyboard Macros}). - - To terminate the execution of a running command, type @kbd{C-g}. This -character causes @dfn{quitting} (@pxref{Quitting}). - -@defvar pre-command-hook -The editor command loop runs this normal hook before each command. At -that time, @code{this-command} contains the command that is about to -run, and @code{last-command} describes the previous command. -@xref{Hooks}. -@end defvar - -@defvar post-command-hook -The editor command loop runs this normal hook after each command -(including commands terminated prematurely by quitting or by errors), -and also when the command loop is first entered. At that time, -@code{this-command} describes the command that just ran, and -@code{last-command} describes the command before that. @xref{Hooks}. -@end defvar - - Quitting is suppressed while running @code{pre-command-hook} and -@code{post-command-hook}. If an error happens while executing one of -these hooks, it terminates execution of the hook, but that is all it -does. - -@node Defining Commands -@section Defining Commands -@cindex defining commands -@cindex commands, defining -@cindex functions, making them interactive -@cindex interactive function - - A Lisp function becomes a command when its body contains, at top -level, a form that calls the special form @code{interactive}. This -form does nothing when actually executed, but its presence serves as a -flag to indicate that interactive calling is permitted. Its argument -controls the reading of arguments for an interactive call. - -@menu -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. -@end menu - -@node Using Interactive -@subsection Using @code{interactive} - - This section describes how to write the @code{interactive} form that -makes a Lisp function an interactively-callable command. - -@defspec interactive arg-descriptor -@cindex argument descriptors -This special form declares that the function in which it appears is a -command, and that it may therefore be called interactively (via -@kbd{M-x} or by entering a key sequence bound to it). The argument -@var{arg-descriptor} declares how to compute the arguments to the -command when the command is called interactively. - -A command may be called from Lisp programs like any other function, but -then the caller supplies the arguments and @var{arg-descriptor} has no -effect. - -The @code{interactive} form has its effect because the command loop -(actually, its subroutine @code{call-interactively}) scans through the -function definition looking for it, before calling the function. Once -the function is called, all its body forms including the -@code{interactive} form are executed, but at this time -@code{interactive} simply returns @code{nil} without even evaluating its -argument. -@end defspec - -There are three possibilities for the argument @var{arg-descriptor}: - -@itemize @bullet -@item -It may be omitted or @code{nil}; then the command is called with no -arguments. This leads quickly to an error if the command requires one -or more arguments. - -@item -It may be a Lisp expression that is not a string; then it should be a -form that is evaluated to get a list of arguments to pass to the -command. -@cindex argument evaluation form - -If this expression reads keyboard input (this includes using the -minibuffer), keep in mind that the integer value of point or the mark -before reading input may be incorrect after reading input. This is -because the current buffer may be receiving subprocess output; -if subprocess output arrives while the command is waiting for input, -it could relocate point and the mark. - -Here's an example of what @emph{not} to do: - -@smallexample -(interactive - (list (region-beginning) (region-end) - (read-string "Foo: " nil 'my-history))) -@end smallexample - -@noindent -Here's how to avoid the problem, by examining point and the mark only -after reading the keyboard input: - -@smallexample -(interactive - (let ((string (read-string "Foo: " nil 'my-history))) - (list (region-beginning) (region-end) string))) -@end smallexample - -@item -@cindex argument prompt -It may be a string; then its contents should consist of a code character -followed by a prompt (which some code characters use and some ignore). -The prompt ends either with the end of the string or with a newline. -Here is a simple example: - -@smallexample -(interactive "bFrobnicate buffer: ") -@end smallexample - -@noindent -The code letter @samp{b} says to read the name of an existing buffer, -with completion. The buffer name is the sole argument passed to the -command. The rest of the string is a prompt. - -If there is a newline character in the string, it terminates the prompt. -If the string does not end there, then the rest of the string should -contain another code character and prompt, specifying another argument. -You can specify any number of arguments in this way. - -@c Emacs 19 feature -The prompt string can use @samp{%} to include previous argument values -(starting with the first argument) in the prompt. This is done using -@code{format} (@pxref{Formatting Strings}). For example, here is how -you could read the name of an existing buffer followed by a new name to -give to that buffer: - -@smallexample -@group -(interactive "bBuffer to rename: \nsRename buffer %s to: ") -@end group -@end smallexample - -@cindex @samp{*} in interactive -@cindex read-only buffers in interactive -If the first character in the string is @samp{*}, then an error is -signaled if the buffer is read-only. - -@cindex @samp{@@} in interactive -@c Emacs 19 feature -If the first character in the string is @samp{@@}, and if the key -sequence used to invoke the command includes any mouse events, then -the window associated with the first of those events is selected -before the command is run. - -You can use @samp{*} and @samp{@@} together; the order does not matter. -Actual reading of arguments is controlled by the rest of the prompt -string (starting with the first character that is not @samp{*} or -@samp{@@}). -@end itemize - -@node Interactive Codes -@comment node-name, next, previous, up -@subsection Code Characters for @code{interactive} -@cindex interactive code description -@cindex description for interactive codes -@cindex codes, interactive, description of -@cindex characters for interactive codes - - The code character descriptions below contain a number of key words, -defined here as follows: - -@table @b -@item Completion -@cindex interactive completion -Provide completion. @key{TAB}, @key{SPC}, and @key{RET} perform name -completion because the argument is read using @code{completing-read} -(@pxref{Completion}). @kbd{?} displays a list of possible completions. - -@item Existing -Require the name of an existing object. An invalid name is not -accepted; the commands to exit the minibuffer do not exit if the current -input is not valid. - -@item Default -@cindex default argument string -A default value of some sort is used if the user enters no text in the -minibuffer. The default depends on the code character. - -@item No I/O -This code letter computes an argument without reading any input. -Therefore, it does not use a prompt string, and any prompt string you -supply is ignored. - -Even though the code letter doesn't use a prompt string, you must follow -it with a newline if it is not the last code character in the string. - -@item Prompt -A prompt immediately follows the code character. The prompt ends either -with the end of the string or with a newline. - -@item Special -This code character is meaningful only at the beginning of the -interactive string, and it does not look for a prompt or a newline. -It is a single, isolated character. -@end table - -@cindex reading interactive arguments - Here are the code character descriptions for use with @code{interactive}: - -@table @samp -@item * -Signal an error if the current buffer is read-only. Special. - -@item @@ -Select the window mentioned in the first mouse event in the key -sequence that invoked this command. Special. - -@item a -A function name (i.e., a symbol satisfying @code{fboundp}). Existing, -Completion, Prompt. - -@item b -The name of an existing buffer. By default, uses the name of the -current buffer (@pxref{Buffers}). Existing, Completion, Default, -Prompt. - -@item B -A buffer name. The buffer need not exist. By default, uses the name of -a recently used buffer other than the current buffer. Completion, -Default, Prompt. - -@item c -A character. The cursor does not move into the echo area. Prompt. - -@item C -A command name (i.e., a symbol satisfying @code{commandp}). Existing, -Completion, Prompt. - -@item d -@cindex position argument -The position of point, as an integer (@pxref{Point}). No I/O. - -@item D -A directory name. The default is the current default directory of the -current buffer, @code{default-directory} (@pxref{System Environment}). -Existing, Completion, Default, Prompt. - -@item e -The first or next mouse event in the key sequence that invoked the command. -More precisely, @samp{e} gets events that are lists, so you can look at -the data in the lists. @xref{Input Events}. No I/O. - -You can use @samp{e} more than once in a single command's interactive -specification. If the key sequence that invoked the command has -@var{n} events that are lists, the @var{n}th @samp{e} provides the -@var{n}th such event. Events that are not lists, such as function keys -and @sc{ASCII} characters, do not count where @samp{e} is concerned. - -@item f -A file name of an existing file (@pxref{File Names}). The default -directory is @code{default-directory}. Existing, Completion, Default, -Prompt. - -@item F -A file name. The file need not exist. Completion, Default, Prompt. - -@item k -A key sequence (@pxref{Keymap Terminology}). This keeps reading events -until a command (or undefined command) is found in the current key -maps. The key sequence argument is represented as a string or vector. -The cursor does not move into the echo area. Prompt. - -This kind of input is used by commands such as @code{describe-key} and -@code{global-set-key}. - -@item K -A key sequence, whose definition you intend to change. This works like -@samp{k}, except that it suppresses, for the last input event in the key -sequence, the conversions that are normally used (when necessary) to -convert an undefined key into a defined one. - -@item m -@cindex marker argument -The position of the mark, as an integer. No I/O. - -@item n -A number read with the minibuffer. If the input is not a number, the -user is asked to try again. The prefix argument, if any, is not used. -Prompt. - -@item N -@cindex raw prefix argument usage -The numeric prefix argument; but if there is no prefix argument, read a -number as with @kbd{n}. Requires a number. @xref{Prefix Command -Arguments}. Prompt. - -@item p -@cindex numeric prefix argument usage -The numeric prefix argument. (Note that this @samp{p} is lower case.) -No I/O. - -@item P -The raw prefix argument. (Note that this @samp{P} is upper case.) No -I/O. - -@item r -@cindex region argument -Point and the mark, as two numeric arguments, smallest first. This is -the only code letter that specifies two successive arguments rather than -one. No I/O. - -@item s -Arbitrary text, read in the minibuffer and returned as a string -(@pxref{Text from Minibuffer}). Terminate the input with either -@key{LFD} or @key{RET}. (@kbd{C-q} may be used to include either of -these characters in the input.) Prompt. - -@item S -An interned symbol whose name is read in the minibuffer. Any whitespace -character terminates the input. (Use @kbd{C-q} to include whitespace in -the string.) Other characters that normally terminate a symbol (e.g., -parentheses and brackets) do not do so here. Prompt. - -@item v -A variable declared to be a user option (i.e., satisfying the predicate -@code{user-variable-p}). @xref{High-Level Completion}. Existing, -Completion, Prompt. - -@item x -A Lisp object, specified with its read syntax, terminated with a -@key{LFD} or @key{RET}. The object is not evaluated. @xref{Object from -Minibuffer}. Prompt. - -@item X -@cindex evaluated expression argument -A Lisp form is read as with @kbd{x}, but then evaluated so that its -value becomes the argument for the command. Prompt. -@end table - -@node Interactive Examples -@comment node-name, next, previous, up -@subsection Examples of Using @code{interactive} -@cindex examples of using @code{interactive} -@cindex @code{interactive}, examples of using - - Here are some examples of @code{interactive}: - -@example -@group -(defun foo1 () ; @r{@code{foo1} takes no arguments,} - (interactive) ; @r{just moves forward two words.} - (forward-word 2)) - @result{} foo1 -@end group - -@group -(defun foo2 (n) ; @r{@code{foo2} takes one argument,} - (interactive "p") ; @r{which is the numeric prefix.} - (forward-word (* 2 n))) - @result{} foo2 -@end group - -@group -(defun foo3 (n) ; @r{@code{foo3} takes one argument,} - (interactive "nCount:") ; @r{which is read with the Minibuffer.} - (forward-word (* 2 n))) - @result{} foo3 -@end group - -@group -(defun three-b (b1 b2 b3) - "Select three existing buffers. -Put them into three windows, selecting the last one." -@end group - (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:") - (delete-other-windows) - (split-window (selected-window) 8) - (switch-to-buffer b1) - (other-window 1) - (split-window (selected-window) 8) - (switch-to-buffer b2) - (other-window 1) - (switch-to-buffer b3)) - @result{} three-b -@group -(three-b "*scratch*" "declarations.texi" "*mail*") - @result{} nil -@end group -@end example - -@node Interactive Call -@section Interactive Call -@cindex interactive call - - After the command loop has translated a key sequence into a -definition, it invokes that definition using the function -@code{command-execute}. If the definition is a function that is a -command, @code{command-execute} calls @code{call-interactively}, which -reads the arguments and calls the command. You can also call these -functions yourself. - -@defun commandp object -Returns @code{t} if @var{object} is suitable for calling interactively; -that is, if @var{object} is a command. Otherwise, returns @code{nil}. - -The interactively callable objects include strings and vectors (treated -as keyboard macros), lambda expressions that contain a top-level call to -@code{interactive}, byte-code function objects made from such lambda -expressions, autoload objects that are declared as interactive -(non-@code{nil} fourth argument to @code{autoload}), and some of the -primitive functions. - -A symbol is @code{commandp} if its function definition is -@code{commandp}. - -Keys and keymaps are not commands. Rather, they are used to look up -commands (@pxref{Keymaps}). - -See @code{documentation} in @ref{Accessing Documentation}, for a -realistic example of using @code{commandp}. -@end defun - -@defun call-interactively command &optional record-flag -This function calls the interactively callable function @var{command}, -reading arguments according to its interactive calling specifications. -An error is signaled if @var{command} is not a function or if it cannot -be called interactively (i.e., is not a command). Note that keyboard -macros (strings and vectors) are not accepted, even though they are -considered commands, because they are not functions. - -@cindex record command history -If @var{record-flag} is non-@code{nil}, then this command and its -arguments are unconditionally added to the list @code{command-history}. -Otherwise, the command is added only if it uses the minibuffer to read -an argument. @xref{Command History}. -@end defun - -@defun command-execute command &optional record-flag -@cindex keyboard macro execution -This function executes @var{command} as an editing command. The -argument @var{command} must satisfy the @code{commandp} predicate; i.e., -it must be an interactively callable function or a keyboard macro. - -A string or vector as @var{command} is executed with -@code{execute-kbd-macro}. A function is passed to -@code{call-interactively}, along with the optional @var{record-flag}. - -A symbol is handled by using its function definition in its place. A -symbol with an @code{autoload} definition counts as a command if it was -declared to stand for an interactively callable function. Such a -definition is handled by loading the specified library and then -rechecking the definition of the symbol. -@end defun - -@deffn Command execute-extended-command prefix-argument -@cindex read command name -This function reads a command name from the minibuffer using -@code{completing-read} (@pxref{Completion}). Then it uses -@code{command-execute} to call the specified command. Whatever that -command returns becomes the value of @code{execute-extended-command}. - -@cindex execute with prefix argument -If the command asks for a prefix argument, it receives the value -@var{prefix-argument}. If @code{execute-extended-command} is called -interactively, the current raw prefix argument is used for -@var{prefix-argument}, and thus passed on to whatever command is run. - -@c !!! Should this be @kindex? -@cindex @kbd{M-x} -@code{execute-extended-command} is the normal definition of @kbd{M-x}, -so it uses the string @w{@samp{M-x }} as a prompt. (It would be better -to take the prompt from the events used to invoke -@code{execute-extended-command}, but that is painful to implement.) A -description of the value of the prefix argument, if any, also becomes -part of the prompt. - -@example -@group -(execute-extended-command 1) ----------- Buffer: Minibuffer ---------- -1 M-x forward-word RET ----------- Buffer: Minibuffer ---------- - @result{} t -@end group -@end example -@end deffn - -@defun interactive-p -This function returns @code{t} if the containing function (the one whose -code includes the call to @code{interactive-p}) was called -interactively, with the function @code{call-interactively}. (It makes -no difference whether @code{call-interactively} was called from Lisp or -directly from the editor command loop.) If the containing function was -called by Lisp evaluation (or with @code{apply} or @code{funcall}), then -it was not called interactively. - -The most common use of @code{interactive-p} is for deciding whether to -print an informative message. As a special exception, -@code{interactive-p} returns @code{nil} whenever a keyboard macro is -being run. This is to suppress the informative messages and speed -execution of the macro. - -For example: - -@example -@group -(defun foo () - (interactive) - (and (interactive-p) - (message "foo"))) - @result{} foo -@end group - -@group -(defun bar () - (interactive) - (setq foobar (list (foo) (interactive-p)))) - @result{} bar -@end group - -@group -;; @r{Type @kbd{M-x foo}.} - @print{} foo -@end group - -@group -;; @r{Type @kbd{M-x bar}.} -;; @r{This does not print anything.} -@end group - -@group -foobar - @result{} (nil t) -@end group -@end example -@end defun - -@node Command Loop Info -@comment node-name, next, previous, up -@section Information from the Command Loop - -The editor command loop sets several Lisp variables to keep status -records for itself and for commands that are run. - -@defvar last-command -This variable records the name of the previous command executed by the -command loop (the one before the current command). Normally the value -is a symbol with a function definition, but this is not guaranteed. - -The value is copied from @code{this-command} when a command returns to -the command loop, except when the command specifies a prefix argument -for the following command. - -This variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Displays}. -@end defvar - -@defvar this-command -@cindex current command -This variable records the name of the command now being executed by -the editor command loop. Like @code{last-command}, it is normally a symbol -with a function definition. - -The command loop sets this variable just before running a command, and -copies its value into @code{last-command} when the command finishes -(unless the command specifies a prefix argument for the following -command). - -@cindex kill command repetition -Some commands set this variable during their execution, as a flag for -whatever command runs next. In particular, the functions for killing text -set @code{this-command} to @code{kill-region} so that any kill commands -immediately following will know to append the killed text to the -previous kill. -@end defvar - -If you do not want a particular command to be recognized as the previous -command in the case where it got an error, you must code that command to -prevent this. One way is to set @code{this-command} to @code{t} at the -beginning of the command, and set @code{this-command} back to its proper -value at the end, like this: - -@example -(defun foo (args@dots{}) - (interactive @dots{}) - (let ((old-this-command this-command)) - (setq this-command t) - @r{@dots{}do the work@dots{}} - (setq this-command old-this-command))) -@end example - -@defun this-command-keys -This function returns a string or vector containing the key sequence -that invoked the present command, plus any previous commands that -generated the prefix argument for this command. The value is a string -if all those events were characters. @xref{Input Events}. - -@example -@group -(this-command-keys) -;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} - @result{} "^U^X^E" -@end group -@end example -@end defun - -@defvar last-nonmenu-event -This variable holds the last input event read as part of a key -sequence, not counting events resulting from mouse menus. - -One use of this variable is to figure out a good default location to -pop up another menu. -@end defvar - -@defvar last-command-event -@defvarx last-command-char -This variable is set to the last input event that was read by the -command loop as part of a command. The principal use of this variable -is in @code{self-insert-command}, which uses it to decide which -character to insert. - -@example -@group -last-command-event -;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.} - @result{} 5 -@end group -@end example - -@noindent -The value is 5 because that is the @sc{ASCII} code for @kbd{C-e}. - -The alias @code{last-command-char} exists for compatibility with -Emacs version 18. -@end defvar - -@c Emacs 19 feature -@defvar last-event-frame -This variable records which frame the last input event was directed to. -Usually this is the frame that was selected when the event was -generated, but if that frame has redirected input focus to another -frame, the value is the frame to which the event was redirected. -@xref{Input Focus}. -@end defvar - -@node Input Events -@section Input Events -@cindex events -@cindex input events - -The Emacs command loop reads a sequence of @dfn{input events} that -represent keyboard or mouse activity. The events for keyboard activity -are characters or symbols; mouse events are always lists. This section -describes the representation and meaning of input events in detail. - -@defun eventp object -This function returns non-@code{nil} if @var{object} is an input event. -@end defun - -@menu -* Keyboard Events:: Ordinary characters--keys with symbols on them. -* Function Keys:: Function keys--keys with names, not symbols. -* Mouse Events:: Overview of mouse events. -* Click Events:: Pushing and releasing a mouse button. -* Drag Events:: Moving the mouse before releasing the button. -* Button-Down Events:: A button was pushed and not yet released. -* Repeat Events:: Double and triple click (or drag, or down). -* Motion Events:: Just moving the mouse, not pushing a button. -* Focus Events:: Moving the mouse between frames. -* Misc Events:: Other events window systems can generate. -* Event Examples:: Examples of the lists for mouse events. -* Classifying Events:: Finding the modifier keys in an event symbol. - Event types. -* Accessing Events:: Functions to extract info from events. -* Strings of Events:: Special considerations for putting - keyboard character events in a string. -@end menu - -@node Keyboard Events -@subsection Keyboard Events - -There are two kinds of input you can get from the keyboard: ordinary -keys, and function keys. Ordinary keys correspond to characters; the -events they generate are represented in Lisp as characters. In Emacs -versions 18 and earlier, characters were the only events. The event -type of a character event is the character itself (an integer); -see @ref{Classifying Events}. - -@cindex modifier bits (of input character) -@cindex basic code (of input character) -An input character event consists of a @dfn{basic code} between 0 and -255, plus any or all of these @dfn{modifier bits}: - -@table @asis -@item meta -The -@iftex -$2^{27}$ -@end iftex -@ifinfo -2**27 -@end ifinfo -bit in the character code indicates a character -typed with the meta key held down. - -@item control -The -@iftex -$2^{26}$ -@end iftex -@ifinfo -2**26 -@end ifinfo -bit in the character code indicates a non-@sc{ASCII} -control character. - -@sc{ASCII} control characters such as @kbd{C-a} have special basic -codes of their own, so Emacs needs no special bit to indicate them. -Thus, the code for @kbd{C-a} is just 1. - -But if you type a control combination not in @sc{ASCII}, such as -@kbd{%} with the control key, the numeric value you get is the code -for @kbd{%} plus -@iftex -$2^{26}$ -@end iftex -@ifinfo -2**26 -@end ifinfo -(assuming the terminal supports non-@sc{ASCII} -control characters). - -@item shift -The -@iftex -$2^{25}$ -@end iftex -@ifinfo -2**25 -@end ifinfo -bit in the character code indicates an @sc{ASCII} control -character typed with the shift key held down. - -For letters, the basic code indicates upper versus lower case; for -digits and punctuation, the shift key selects an entirely different -character with a different basic code. In order to keep within -the @sc{ASCII} character set whenever possible, Emacs avoids using -the -@iftex -$2^{25}$ -@end iftex -@ifinfo -2**25 -@end ifinfo -bit for those characters. - -However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from -@kbd{C-a}, so Emacs uses the -@iftex -$2^{25}$ -@end iftex -@ifinfo -2**25 -@end ifinfo -bit in @kbd{C-A} and not in -@kbd{C-a}. - -@item hyper -The -@iftex -$2^{24}$ -@end iftex -@ifinfo -2**24 -@end ifinfo -bit in the character code indicates a character -typed with the hyper key held down. - -@item super -The -@iftex -$2^{23}$ -@end iftex -@ifinfo -2**23 -@end ifinfo -bit in the character code indicates a character -typed with the super key held down. - -@item alt -The -@iftex -$2^{22}$ -@end iftex -@ifinfo -2**22 -@end ifinfo -bit in the character code indicates a character typed with -the alt key held down. (On some terminals, the key labeled @key{ALT} -is actually the meta key.) -@end table - - It is best to avoid mentioning specific bit numbers in your program. -To test the modifier bits of a character, use the function -@code{event-modifiers} (@pxref{Classifying Events}). When making key -bindings, you can use the read syntax for characters with modifier bits -(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with -@code{define-key}, you can use lists such as @code{(control hyper ?x)} to -specify the characters (@pxref{Changing Key Bindings}). The function -@code{event-convert-list} converts such a list into an event type -(@pxref{Classifying Events}). - -@node Function Keys -@subsection Function Keys - -@cindex function keys -Most keyboards also have @dfn{function keys}---keys that have names or -symbols that are not characters. Function keys are represented in Lisp -as symbols; the symbol's name is the function key's label, in lower -case. For example, pressing a key labeled @key{F1} places the symbol -@code{f1} in the input stream. - -The event type of a function key event is the event symbol itself. -@xref{Classifying Events}. - -Here are a few special cases in the symbol-naming convention for -function keys: - -@table @asis -@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete} -These keys correspond to common @sc{ASCII} control characters that have -special keys on most keyboards. - -In @sc{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the -terminal can distinguish between them, Emacs conveys the distinction to -Lisp programs by representing the former as the integer 9, and the -latter as the symbol @code{tab}. - -Most of the time, it's not useful to distinguish the two. So normally -@code{function-key-map} (@pxref{Translating Input}) is set up to map -@code{tab} into 9. Thus, a key binding for character code 9 (the -character @kbd{C-i}) also applies to @code{tab}. Likewise for the other -symbols in this group. The function @code{read-char} likewise converts -these events into characters. - -In @sc{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace} -converts into the character code 127 (@key{DEL}), not into code 8 -(@key{BS}). This is what most users prefer. - -@item @code{left}, @code{up}, @code{right}, @code{down} -Cursor arrow keys -@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{} -Keypad keys (to the right of the regular keyboard). -@item @code{kp-0}, @code{kp-1}, @dots{} -Keypad keys with digits. -@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} -Keypad PF keys. -@item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down} -Keypad arrow keys. Emacs normally translates these -into the non-keypad keys @code{home}, @code{left}, @dots{} -@item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete} -Additional keypad duplicates of keys ordinarily found elsewhere. Emacs -normally translates these into the like-named non-keypad keys. -@end table - -You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER}, -@key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to -represent them is with prefixes in the symbol name: - -@table @samp -@item A- -The alt modifier. -@item C- -The control modifier. -@item H- -The hyper modifier. -@item M- -The meta modifier. -@item S- -The shift modifier. -@item s- -The super modifier. -@end table - -Thus, the symbol for the key @key{F3} with @key{META} held down is -@code{M-f3}. When you use more than one prefix, we recommend you -write them in alphabetical order; but the order does not matter in -arguments to the key-binding lookup and modification functions. - -@node Mouse Events -@subsection Mouse Events - -Emacs supports four kinds of mouse events: click events, drag events, -button-down events, and motion events. All mouse events are represented -as lists. The @sc{car} of the list is the event type; this says which -mouse button was involved, and which modifier keys were used with it. -The event type can also distinguish double or triple button presses -(@pxref{Repeat Events}). The rest of the list elements give position -and time information. - -For key lookup, only the event type matters: two events of the same type -necessarily run the same command. The command can access the full -values of these events using the @samp{e} interactive code. -@xref{Interactive Codes}. - -A key sequence that starts with a mouse event is read using the keymaps -of the buffer in the window that the mouse was in, not the current -buffer. This does not imply that clicking in a window selects that -window or its buffer---that is entirely under the control of the command -binding of the key sequence. - -@node Click Events -@subsection Click Events -@cindex click event -@cindex mouse click event - -When the user presses a mouse button and releases it at the same -location, that generates a @dfn{click} event. Mouse click events have -this form: - -@example -(@var{event-type} - (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}) - @var{click-count}) -@end example - -Here is what the elements normally mean: - -@table @asis -@item @var{event-type} -This is a symbol that indicates which mouse button was used. It is -one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the -buttons are numbered left to right. - -You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-}, -@samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift -and super, just as you would with function keys. - -This symbol also serves as the event type of the event. Key bindings -describe events by their types; thus, if there is a key binding for -@code{mouse-1}, that binding would apply to all events whose -@var{event-type} is @code{mouse-1}. - -@item @var{window} -This is the window in which the click occurred. - -@item @var{x}, @var{y} -These are the pixel-denominated coordinates of the click, relative to -the top left corner of @var{window}, which is @code{(0 . 0)}. - -@item @var{buffer-pos} -This is the buffer position of the character clicked on. - -@item @var{timestamp} -This is the time at which the event occurred, in milliseconds. (Since -this value wraps around the entire range of Emacs Lisp integers in about -five hours, it is useful only for relating the times of nearby events.) - -@item @var{click-count} -This is the number of rapid repeated presses so far of the same mouse -button. @xref{Repeat Events}. -@end table - -The meanings of @var{buffer-pos}, @var{x} and @var{y} are somewhat -different when the event location is in a special part of the screen, -such as the mode line or a scroll bar. - -If the location is in a scroll bar, then @var{buffer-pos} is the symbol -@code{vertical-scroll-bar} or @code{horizontal-scroll-bar}, and the pair -@code{(@var{x} . @var{y})} is replaced with a pair @code{(@var{portion} -. @var{whole})}, where @var{portion} is the distance of the click from -the top or left end of the scroll bar, and @var{whole} is the length of -the entire scroll bar. - -If the position is on a mode line or the vertical line separating -@var{window} from its neighbor to the right, then @var{buffer-pos} is -the symbol @code{mode-line} or @code{vertical-line}. For the mode line, -@var{y} does not have meaningful data. For the vertical line, @var{x} -does not have meaningful data. - -In one special case, @var{buffer-pos} is a list containing a symbol (one -of the symbols listed above) instead of just the symbol. This happens -after the imaginary prefix keys for the event are inserted into the -input stream. @xref{Key Sequence Input}. - -@node Drag Events -@subsection Drag Events -@cindex drag event -@cindex mouse drag event - -With Emacs, you can have a drag event without even changing your -clothes. A @dfn{drag event} happens every time the user presses a mouse -button and then moves the mouse to a different character position before -releasing the button. Like all mouse events, drag events are -represented in Lisp as lists. The lists record both the starting mouse -position and the final position, like this: - -@example -(@var{event-type} - (@var{window1} @var{buffer-pos1} (@var{x1} . @var{y1}) @var{timestamp1}) - (@var{window2} @var{buffer-pos2} (@var{x2} . @var{y2}) @var{timestamp2}) - @var{click-count}) -@end example - -For a drag event, the name of the symbol @var{event-type} contains the -prefix @samp{drag-}. The second and third elements of the event give -the starting and ending position of the drag. Aside from that, the data -have the same meanings as in a click event (@pxref{Click Events}). You -can access the second element of any mouse event in the same way, with -no need to distinguish drag events from others. - -The @samp{drag-} prefix follows the modifier key prefixes such as -@samp{C-} and @samp{M-}. - -If @code{read-key-sequence} receives a drag event that has no key -binding, and the corresponding click event does have a binding, it -changes the drag event into a click event at the drag's starting -position. This means that you don't have to distinguish between click -and drag events unless you want to. - -@node Button-Down Events -@subsection Button-Down Events -@cindex button-down event - -Click and drag events happen when the user releases a mouse button. -They cannot happen earlier, because there is no way to distinguish a -click from a drag until the button is released. - -If you want to take action as soon as a button is pressed, you need to -handle @dfn{button-down} events.@footnote{Button-down is the -conservative antithesis of drag.} These occur as soon as a button is -pressed. They are represented by lists that look exactly like click -events (@pxref{Click Events}), except that the @var{event-type} symbol -name contains the prefix @samp{down-}. The @samp{down-} prefix follows -modifier key prefixes such as @samp{C-} and @samp{M-}. - -The function @code{read-key-sequence}, and therefore the Emacs command -loop as well, ignore any button-down events that don't have command -bindings. This means that you need not worry about defining button-down -events unless you want them to do something. The usual reason to define -a button-down event is so that you can track mouse motion (by reading -motion events) until the button is released. @xref{Motion Events}. - -@node Repeat Events -@subsection Repeat Events -@cindex repeat events -@cindex double-click events -@cindex triple-click events - -If you press the same mouse button more than once in quick succession -without moving the mouse, Emacs generates special @dfn{repeat} mouse -events for the second and subsequent presses. - -The most common repeat events are @dfn{double-click} events. Emacs -generates a double-click event when you click a button twice; the event -happens when you release the button (as is normal for all click -events). - -The event type of a double-click event contains the prefix -@samp{double-}. Thus, a double click on the second mouse button with -@key{meta} held down comes to the Lisp program as -@code{M-double-mouse-2}. If a double-click event has no binding, the -binding of the corresponding ordinary click event is used to execute -it. Thus, you need not pay attention to the double click feature -unless you really want to. - -When the user performs a double click, Emacs generates first an ordinary -click event, and then a double-click event. Therefore, you must design -the command binding of the double click event to assume that the -single-click command has already run. It must produce the desired -results of a double click, starting from the results of a single click. - -This is convenient, if the meaning of a double click somehow ``builds -on'' the meaning of a single click---which is recommended user interface -design practice for double clicks. - -If you click a button, then press it down again and start moving the -mouse with the button held down, then you get a @dfn{double-drag} event -when you ultimately release the button. Its event type contains -@samp{double-drag} instead of just @samp{drag}. If a double-drag event -has no binding, Emacs looks for an alternate binding as if the event -were an ordinary drag. - -Before the double-click or double-drag event, Emacs generates a -@dfn{double-down} event when the user presses the button down for the -second time. Its event type contains @samp{double-down} instead of just -@samp{down}. If a double-down event has no binding, Emacs looks for an -alternate binding as if the event were an ordinary button-down event. -If it finds no binding that way either, the double-down event is -ignored. - -To summarize, when you click a button and then press it again right -away, Emacs generates a down event and a click event for the first -click, a double-down event when you press the button again, and finally -either a double-click or a double-drag event. - -If you click a button twice and then press it again, all in quick -succession, Emacs generates a @dfn{triple-down} event, followed by -either a @dfn{triple-click} or a @dfn{triple-drag}. The event types of -these events contain @samp{triple} instead of @samp{double}. If any -triple event has no binding, Emacs uses the binding that it would use -for the corresponding double event. - -If you click a button three or more times and then press it again, the -events for the presses beyond the third are all triple events. Emacs -does not have separate event types for quadruple, quintuple, etc.@: -events. However, you can look at the event list to find out precisely -how many times the button was pressed. - -@defun event-click-count event -This function returns the number of consecutive button presses that led -up to @var{event}. If @var{event} is a double-down, double-click or -double-drag event, the value is 2. If @var{event} is a triple event, -the value is 3 or greater. If @var{event} is an ordinary mouse event -(not a repeat event), the value is 1. -@end defun - -@defvar double-click-time -To generate repeat events, successive mouse button presses must be at -the same screen position, and the number of milliseconds between -successive button presses must be less than the value of -@code{double-click-time}. Setting @code{double-click-time} to -@code{nil} disables multi-click detection entirely. Setting it to -@code{t} removes the time limit; Emacs then detects multi-clicks by -position only. -@end defvar - -@node Motion Events -@subsection Motion Events -@cindex motion event -@cindex mouse motion events - -Emacs sometimes generates @dfn{mouse motion} events to describe motion -of the mouse without any button activity. Mouse motion events are -represented by lists that look like this: - -@example -(mouse-movement - (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp})) -@end example - -The second element of the list describes the current position of the -mouse, just as in a click event (@pxref{Click Events}). - -The special form @code{track-mouse} enables generation of motion events -within its body. Outside of @code{track-mouse} forms, Emacs does not -generate events for mere motion of the mouse, and these events do not -appear. - -@defspec track-mouse body@dots{} -This special form executes @var{body}, with generation of mouse motion -events enabled. Typically @var{body} would use @code{read-event} -to read the motion events and modify the display accordingly. - -When the user releases the button, that generates a click event. -Typically, @var{body} should return when it sees the click event, and -discard that event. -@end defspec - -@node Focus Events -@subsection Focus Events -@cindex focus event - -Window systems provide general ways for the user to control which window -gets keyboard input. This choice of window is called the @dfn{focus}. -When the user does something to switch between Emacs frames, that -generates a @dfn{focus event}. The normal definition of a focus event, -in the global keymap, is to select a new frame within Emacs, as the user -would expect. @xref{Input Focus}. - -Focus events are represented in Lisp as lists that look like this: - -@example -(switch-frame @var{new-frame}) -@end example - -@noindent -where @var{new-frame} is the frame switched to. - -Most X window managers are set up so that just moving the mouse into a -window is enough to set the focus there. Emacs appears to do this, -because it changes the cursor to solid in the new frame. However, there -is no need for the Lisp program to know about the focus change until -some other kind of input arrives. So Emacs generates a focus event only -when the user actually types a keyboard key or presses a mouse button in -the new frame; just moving the mouse between frames does not generate a -focus event. - -A focus event in the middle of a key sequence would garble the -sequence. So Emacs never generates a focus event in the middle of a key -sequence. If the user changes focus in the middle of a key -sequence---that is, after a prefix key---then Emacs reorders the events -so that the focus event comes either before or after the multi-event key -sequence, and not within it. - -@node Misc Events -@subsection Miscellaneous Window System Events - -A few other event types represent occurrences within the window system. - -@table @code -@cindex @code{delete-frame} event -@item (delete-frame (@var{frame})) -This kind of event indicates that the user gave the window manager -a command to delete a particular window, which happens to be an Emacs frame. - -The standard definition of the @code{delete-frame} event is to delete @var{frame}. - -@cindex @code{iconify-frame} event -@item (iconify-frame (@var{frame})) -This kind of event indicates that the user iconified @var{frame} using -the window manager. Its standard definition is @code{ignore}; since the -frame has already been iconified, Emacs has no work to do. The purpose -of this event type is so that you can keep track of such events if you -want to. - -@cindex @code{make-frame-visible} event -@item (make-frame-visible (@var{frame})) -This kind of event indicates that the user deiconified @var{frame} using -the window manager. Its standard definition is @code{ignore}; since the -frame has already been made visible, Emacs has no work to do. -@end table - - If one of these events arrives in the middle of a key sequence---that -is, after a prefix key---then Emacs reorders the events so that this -event comes either before or after the multi-event key sequence, not -within it. - -@node Event Examples -@subsection Event Examples - -If the user presses and releases the left mouse button over the same -location, that generates a sequence of events like this: - -@smallexample -(down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320)) -(mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864180)) -@end smallexample - -While holding the control key down, the user might hold down the -second mouse button, and drag the mouse from one line to the next. -That produces two events, as shown here: - -@smallexample -(C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)) -(C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219) - (#<window 18 on NEWS> 3510 (0 . 28) -729648)) -@end smallexample - -While holding down the meta and shift keys, the user might press the -second mouse button on the window's mode line, and then drag the mouse -into another window. That produces a pair of events like these: - -@smallexample -(M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)) -(M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844) - (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3) - -453816)) -@end smallexample - -@node Classifying Events -@subsection Classifying Events -@cindex event type - - Every event has an @dfn{event type}, which classifies the event for -key binding purposes. For a keyboard event, the event type equals the -event value; thus, the event type for a character is the character, and -the event type for a function key symbol is the symbol itself. For -events that are lists, the event type is the symbol in the @sc{car} of -the list. Thus, the event type is always a symbol or a character. - - Two events of the same type are equivalent where key bindings are -concerned; thus, they always run the same command. That does not -necessarily mean they do the same things, however, as some commands look -at the whole event to decide what to do. For example, some commands use -the location of a mouse event to decide where in the buffer to act. - - Sometimes broader classifications of events are useful. For example, -you might want to ask whether an event involved the @key{META} key, -regardless of which other key or mouse button was used. - - The functions @code{event-modifiers} and @code{event-basic-type} are -provided to get such information conveniently. - -@defun event-modifiers event -This function returns a list of the modifiers that @var{event} has. The -modifiers are symbols; they include @code{shift}, @code{control}, -@code{meta}, @code{alt}, @code{hyper} and @code{super}. In addition, -the modifiers list of a mouse event symbol always contains one of -@code{click}, @code{drag}, and @code{down}. - -The argument @var{event} may be an entire event object, or just an event -type. - -Here are some examples: - -@example -(event-modifiers ?a) - @result{} nil -(event-modifiers ?\C-a) - @result{} (control) -(event-modifiers ?\C-%) - @result{} (control) -(event-modifiers ?\C-\S-a) - @result{} (control shift) -(event-modifiers 'f5) - @result{} nil -(event-modifiers 's-f5) - @result{} (super) -(event-modifiers 'M-S-f5) - @result{} (meta shift) -(event-modifiers 'mouse-1) - @result{} (click) -(event-modifiers 'down-mouse-1) - @result{} (down) -@end example - -The modifiers list for a click event explicitly contains @code{click}, -but the event symbol name itself does not contain @samp{click}. -@end defun - -@defun event-basic-type event -This function returns the key or mouse button that @var{event} -describes, with all modifiers removed. For example: - -@example -(event-basic-type ?a) - @result{} 97 -(event-basic-type ?A) - @result{} 97 -(event-basic-type ?\C-a) - @result{} 97 -(event-basic-type ?\C-\S-a) - @result{} 97 -(event-basic-type 'f5) - @result{} f5 -(event-basic-type 's-f5) - @result{} f5 -(event-basic-type 'M-S-f5) - @result{} f5 -(event-basic-type 'down-mouse-1) - @result{} mouse-1 -@end example -@end defun - -@defun mouse-movement-p object -This function returns non-@code{nil} if @var{object} is a mouse movement -event. -@end defun - -@defun event-convert-list list -This function converts a list of modifier names and a basic event type -to an event type which specifies all of them. For example, - -@example -(event-convert-list '(control ?a)) - @result{} 1 -(event-convert-list '(control meta ?a)) - @result{} -134217727 -(event-convert-list '(control super f1)) - @result{} C-s-f1 -@end example -@end defun - -@node Accessing Events -@subsection Accessing Events - - This section describes convenient functions for accessing the data in -a mouse button or motion event. - - These two functions return the starting or ending position of a -mouse-button event. The position is a list of this form: - -@example -(@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp}) -@end example - -@defun event-start event -This returns the starting position of @var{event}. - -If @var{event} is a click or button-down event, this returns the -location of the event. If @var{event} is a drag event, this returns the -drag's starting position. -@end defun - -@defun event-end event -This returns the ending position of @var{event}. - -If @var{event} is a drag event, this returns the position where the user -released the mouse button. If @var{event} is a click or button-down -event, the value is actually the starting position, which is the only -position such events have. -@end defun - - These five functions take a position as described above, and return -various parts of it. - -@defun posn-window position -Return the window that @var{position} is in. -@end defun - -@defun posn-point position -Return the buffer position in @var{position}. This is an integer. -@end defun - -@defun posn-x-y position -Return the pixel-based x and y coordinates in @var{position}, as a cons -cell @code{(@var{x} . @var{y})}. -@end defun - -@defun posn-col-row position -Return the row and column (in units of characters) of @var{position}, as -a cons cell @code{(@var{col} . @var{row})}. These are computed from the -@var{x} and @var{y} values actually found in @var{position}. -@end defun - -@defun posn-timestamp position -Return the timestamp in @var{position}. -@end defun - -@defun scroll-bar-event-ratio event -This function returns the fractional vertical position of a scroll bar -event within the scroll bar. The value is a cons cell -@code{(@var{portion} . @var{whole})} containing two integers whose ratio -is the fractional position. -@end defun - -@defun scroll-bar-scale ratio total -This function multiplies (in effect) @var{ratio} by @var{total}, -rounding the result to an integer. The argument @var{ratio} is not a -number, but rather a pair @code{(@var{num} . @var{denom})}---typically a -value returned by @code{scroll-bar-event-ratio}. - -This function is handy for scaling a position on a scroll bar into a -buffer position. Here's how to do that: - -@example -(+ (point-min) - (scroll-bar-scale - (posn-x-y (event-start event)) - (- (point-max) (point-min)))) -@end example - -Recall that scroll bar events have two integers forming ratio in place -of a pair of x and y coordinates. -@end defun - -@node Strings of Events -@subsection Putting Keyboard Events in Strings - - In most of the places where strings are used, we conceptualize the -string as containing text characters---the same kind of characters found -in buffers or files. Occasionally Lisp programs use strings that -conceptually contain keyboard characters; for example, they may be key -sequences or keyboard macro definitions. There are special rules for -how to put keyboard characters into a string, because they are not -limited to the range of 0 to 255 as text characters are. - - A keyboard character typed using the @key{META} key is called a -@dfn{meta character}. The numeric code for such an event includes the -@iftex -$2^{27}$ -@end iftex -@ifinfo -2**27 -@end ifinfo -bit; it does not even come close to fitting in a string. However, -earlier Emacs versions used a different representation for these -characters, which gave them codes in the range of 128 to 255. That did -fit in a string, and many Lisp programs contain string constants that -use @samp{\M-} to express meta characters, especially as the argument to -@code{define-key} and similar functions. - - We provide backward compatibility to run those programs using special -rules for how to put a keyboard character event in a string. Here are -the rules: - -@itemize @bullet -@item -If the keyboard character value is in the range of 0 to 127, it can go -in the string unchanged. - -@item -The meta variants of those characters, with codes in the range of -@iftex -$2^{27}$ -@end iftex -@ifinfo -2**27 -@end ifinfo -to -@iftex -$2^{27} + 127$, -@end iftex -@ifinfo -2**27+127, -@end ifinfo -can also go in the string, but you must change their -numeric values. You must set the -@iftex -$2^{7}$ -@end iftex -@ifinfo -2**7 -@end ifinfo -bit instead of the -@iftex -$2^{27}$ -@end iftex -@ifinfo -2**27 -@end ifinfo -bit, -resulting in a value between 128 and 255. - -@item -Other keyboard character events cannot fit in a string. This includes -keyboard events in the range of 128 to 255. -@end itemize - - Functions such as @code{read-key-sequence} that can construct strings -of keyboard input characters follow these rules. They construct vectors -instead of strings, when the events won't fit in a string. - - When you use the read syntax @samp{\M-} in a string, it produces a -code in the range of 128 to 255---the same code that you get if you -modify the corresponding keyboard event to put it in the string. Thus, -meta events in strings work consistently regardless of how they get into -the strings. - - The reason we changed the representation of meta characters as -keyboard events is to make room for basic character codes beyond 127, -and support meta variants of such larger character codes. - - New programs can avoid dealing with these special compatibility rules -by using vectors instead of strings for key sequences when there is any -possibility that they might contain meta characters, and by using -@code{listify-key-sequence} to access a string of events. - -@defun listify-key-sequence key -This function converts the string or vector @var{key} to a list of -events, which you can put in @code{unread-command-events}. Converting a -vector is simple, but converting a string is tricky because of the -special representation used for meta characters in a string. -@end defun - -@node Reading Input -@section Reading Input - - The editor command loop reads keyboard input using the function -@code{read-key-sequence}, which uses @code{read-event}. These and other -functions for keyboard input are also available for use in Lisp -programs. See also @code{momentary-string-display} in @ref{Temporary -Displays}, and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, -for functions and variables for controlling terminal input modes and -debugging terminal input. @xref{Translating Input}, for features you -can use for translating or modifying input events while reading them. - - For higher-level input facilities, see @ref{Minibuffers}. - -@menu -* Key Sequence Input:: How to read one key sequence. -* Reading One Event:: How to read just one event. -* Quoted Character Input:: Asking the user to specify a character. -* Event Input Misc:: How to reread or throw away input events. -@end menu - -@node Key Sequence Input -@subsection Key Sequence Input -@cindex key sequence input - - The command loop reads input a key sequence at a time, by calling -@code{read-key-sequence}. Lisp programs can also call this function; -for example, @code{describe-key} uses it to read the key to describe. - -@defun read-key-sequence prompt -@cindex key sequence -This function reads a key sequence and returns it as a string or -vector. It keeps reading events until it has accumulated a full key -sequence; that is, enough to specify a non-prefix command using the -currently active keymaps. - -If the events are all characters and all can fit in a string, then -@code{read-key-sequence} returns a string (@pxref{Strings of Events}). -Otherwise, it returns a vector, since a vector can hold all kinds of -events---characters, symbols, and lists. The elements of the string or -vector are the events in the key sequence. - -The function @code{read-key-sequence} suppresses quitting: @kbd{C-g} -typed while reading with this function works like any other character, -and does not set @code{quit-flag}. @xref{Quitting}. - -The argument @var{prompt} is either a string to be displayed in the echo -area as a prompt, or @code{nil}, meaning not to display a prompt. - -In the example below, the prompt @samp{?} is displayed in the echo area, -and the user types @kbd{C-x C-f}. - -@example -(read-key-sequence "?") - -@group ----------- Echo Area ---------- -?@kbd{C-x C-f} ----------- Echo Area ---------- - - @result{} "^X^F" -@end group -@end example -@end defun - -@defvar num-input-keys -@c Emacs 19 feature -This variable's value is the number of key sequences processed so far in -this Emacs session. This includes key sequences read from the terminal -and key sequences read from keyboard macros being executed. -@end defvar - -@cindex upper case key sequence -@cindex downcasing in @code{lookup-key} -If an input character is an upper-case letter and has no key binding, -but its lower-case equivalent has one, then @code{read-key-sequence} -converts the character to lower case. Note that @code{lookup-key} does -not perform case conversion in this way. - -The function @code{read-key-sequence} also transforms some mouse events. -It converts unbound drag events into click events, and discards unbound -button-down events entirely. It also reshuffles focus events and -miscellaneous window events so that they never appear in a key sequence -with any other events. - -When mouse events occur in special parts of a window, such as a mode -line or a scroll bar, the event type shows nothing special---it is the -same symbol that would normally represent that combination of mouse -button and modifier keys. The information about the window part is -kept elsewhere in the event---in the coordinates. But -@code{read-key-sequence} translates this information into imaginary -prefix keys, all of which are symbols: @code{mode-line}, -@code{vertical-line}, @code{horizontal-scroll-bar} and -@code{vertical-scroll-bar}. - -You can define meanings for mouse clicks in special window parts by -defining key sequences using these imaginary prefix keys. - -For example, if you call @code{read-key-sequence} and then click the -mouse on the window's mode line, you get two events, like this: - -@example -(read-key-sequence "Click on the mode line: ") - @result{} [mode-line - (mouse-1 - (#<window 6 on NEWS> mode-line - (40 . 63) 5959987))] -@end example - -@node Reading One Event -@subsection Reading One Event - - The lowest level functions for command input are those that read a -single event. - -@defun read-event -This function reads and returns the next event of command input, waiting -if necessary until an event is available. Events can come directly from -the user or from a keyboard macro. - -The function @code{read-event} does not display any message to indicate -it is waiting for input; use @code{message} first, if you wish to -display one. If you have not displayed a message, @code{read-event} -prompts by echoing: it displays descriptions of the events that led to -or were read by the current command. @xref{The Echo Area}. - -If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event} -moves the cursor temporarily to the echo area, to the end of any message -displayed there. Otherwise @code{read-event} does not move the cursor. - -Here is what happens if you call @code{read-event} and then press the -right-arrow function key: - -@example -@group -(read-event) - @result{} right -@end group -@end example -@end defun - -@defun read-char -This function reads and returns a character of command input. It -discards any events that are not characters, until it gets a character. - -In the first example, the user types the character @kbd{1} (@sc{ASCII} -code 49). The second example shows a keyboard macro definition that -calls @code{read-char} from the minibuffer using @code{eval-expression}. -@code{read-char} reads the keyboard macro's very next character, which -is @kbd{1}. Then @code{eval-expression} displays its return value in -the echo area. - -@example -@group -(read-char) - @result{} 49 -@end group - -@group -;; @r{We assume here you use @kbd{M-:} to evaluate this.} -(symbol-function 'foo) - @result{} "^[:(read-char)^M1" -@end group -@group -(execute-kbd-macro 'foo) - @print{} 49 - @result{} nil -@end group -@end example -@end defun - -@node Quoted Character Input -@subsection Quoted Character Input -@cindex quoted character input - - You can use the function @code{read-quoted-char} to ask the user to -specify a character, and allow the user to specify a control or meta -character conveniently, either literally or as an octal character code. -The command @code{quoted-insert} uses this function. - -@defun read-quoted-char &optional prompt -@cindex octal character input -@cindex control characters, reading -@cindex nonprinting characters, reading -This function is like @code{read-char}, except that if the first -character read is an octal digit (0-7), it reads up to two more octal digits -(but stopping if a non-octal digit is found) and returns the -character represented by those digits in octal. - -Quitting is suppressed when the first character is read, so that the -user can enter a @kbd{C-g}. @xref{Quitting}. - -If @var{prompt} is supplied, it specifies a string for prompting the -user. The prompt string is always displayed in the echo area, followed -by a single @samp{-}. - -In the following example, the user types in the octal number 177 (which -is 127 in decimal). - -@example -(read-quoted-char "What character") - -@group ----------- Echo Area ---------- -What character-@kbd{177} ----------- Echo Area ---------- - - @result{} 127 -@end group -@end example -@end defun - -@need 2000 -@node Event Input Misc -@subsection Miscellaneous Event Input Features - -This section describes how to ``peek ahead'' at events without using -them up, how to check for pending input, and how to discard pending -input. - -@defvar unread-command-events -@cindex next input -@cindex peeking at input -This variable holds a list of events waiting to be read as command -input. The events are used in the order they appear in the list, and -removed one by one as they are used. - -The variable is needed because in some cases a function reads a event -and then decides not to use it. Storing the event in this variable -causes it to be processed normally, by the command loop or by the -functions to read command input. - -@cindex prefix argument unreading -For example, the function that implements numeric prefix arguments reads -any number of digits. When it finds a non-digit event, it must unread -the event so that it can be read normally by the command loop. -Likewise, incremental search uses this feature to unread events with no -special meaning in a search, because these events should exit the search -and then execute normally. - -The reliable and easy way to extract events from a key sequence so as to -put them in @code{unread-command-events} is to use -@code{listify-key-sequence} (@pxref{Strings of Events}). -@end defvar - -@defvar unread-command-char -This variable holds a character to be read as command input. -A value of -1 means ``empty''. - -This variable is mostly obsolete now that you can use -@code{unread-command-events} instead; it exists only to support programs -written for Emacs versions 18 and earlier. -@end defvar - -@defun input-pending-p -@cindex waiting for command key input -This function determines whether any command input is currently -available to be read. It returns immediately, with value @code{t} if -there is available input, @code{nil} otherwise. On rare occasions it -may return @code{t} when no input is available. -@end defun - -@defvar last-input-event -This variable records the last terminal input event read, whether -as part of a command or explicitly by a Lisp program. - -In the example below, the Lisp program reads the character @kbd{1}, -@sc{ASCII} code 49. It becomes the value of @code{last-input-event}, -while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate -this expression) remains the value of @code{last-command-event}. - -@example -@group -(progn (print (read-char)) - (print last-command-event) - last-input-event) - @print{} 49 - @print{} 5 - @result{} 49 -@end group -@end example - -@vindex last-input-char -The alias @code{last-input-char} exists for compatibility with -Emacs version 18. -@end defvar - -@defun discard-input -@cindex flush input -@cindex discard input -@cindex terminate keyboard macro -This function discards the contents of the terminal input buffer and -cancels any keyboard macro that might be in the process of definition. -It returns @code{nil}. - -In the following example, the user may type a number of characters right -after starting the evaluation of the form. After the @code{sleep-for} -finishes sleeping, @code{discard-input} discards any characters typed -during the sleep. - -@example -(progn (sleep-for 2) - (discard-input)) - @result{} nil -@end example -@end defun - -@node Waiting -@section Waiting for Elapsed Time or Input -@cindex pausing -@cindex waiting - - The wait functions are designed to wait for a certain amount of time -to pass or until there is input. For example, you may wish to pause in -the middle of a computation to allow the user time to view the display. -@code{sit-for} pauses and updates the screen, and returns immediately if -input comes in, while @code{sleep-for} pauses without updating the -screen. - -@defun sit-for seconds &optional millisec nodisp -This function performs redisplay (provided there is no pending input -from the user), then waits @var{seconds} seconds, or until input is -available. The value is @code{t} if @code{sit-for} waited the full -time with no input arriving (see @code{input-pending-p} in @ref{Event -Input Misc}). Otherwise, the value is @code{nil}. - -The argument @var{seconds} need not be an integer. If it is a floating -point number, @code{sit-for} waits for a fractional number of seconds. -Some systems support only a whole number of seconds; on these systems, -@var{seconds} is rounded down. - -The optional argument @var{millisec} specifies an additional waiting -period measured in milliseconds. This adds to the period specified by -@var{seconds}. If the system doesn't support waiting fractions of a -second, you get an error if you specify nonzero @var{millisec}. - -@cindex forcing redisplay -Redisplay is always preempted if input arrives, and does not happen at -all if input is available before it starts. Thus, there is no way to -force screen updating if there is pending input; however, if there is no -input pending, you can force an update with no delay by using -@code{(sit-for 0)}. - -If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not -redisplay, but it still returns as soon as input is available (or when -the timeout elapses). - -Iconifying or deiconifying a frame makes @code{sit-for} return, because -that generates an event. @xref{Misc Events}. - -The usual purpose of @code{sit-for} is to give the user time to read -text that you display. -@end defun - -@defun sleep-for seconds &optional millisec -This function simply pauses for @var{seconds} seconds without updating -the display. It pays no attention to available input. It returns -@code{nil}. - -The argument @var{seconds} need not be an integer. If it is a floating -point number, @code{sleep-for} waits for a fractional number of seconds. -Some systems support only a whole number of seconds; on these systems, -@var{seconds} is rounded down. - -The optional argument @var{millisec} specifies an additional waiting -period measured in milliseconds. This adds to the period specified by -@var{seconds}. If the system doesn't support waiting fractions of a -second, you get an error if you specify nonzero @var{millisec}. - -Use @code{sleep-for} when you wish to guarantee a delay. -@end defun - - @xref{Time of Day}, for functions to get the current time. - -@node Quitting -@section Quitting -@cindex @kbd{C-g} -@cindex quitting - - Typing @kbd{C-g} while a Lisp function is running causes Emacs to -@dfn{quit} whatever it is doing. This means that control returns to the -innermost active command loop. - - Typing @kbd{C-g} while the command loop is waiting for keyboard input -does not cause a quit; it acts as an ordinary input character. In the -simplest case, you cannot tell the difference, because @kbd{C-g} -normally runs the command @code{keyboard-quit}, whose effect is to quit. -However, when @kbd{C-g} follows a prefix key, the result is an undefined -key. The effect is to cancel the prefix key as well as any prefix -argument. - - In the minibuffer, @kbd{C-g} has a different definition: it aborts out -of the minibuffer. This means, in effect, that it exits the minibuffer -and then quits. (Simply quitting would return to the command loop -@emph{within} the minibuffer.) The reason why @kbd{C-g} does not quit -directly when the command reader is reading input is so that its meaning -can be redefined in the minibuffer in this way. @kbd{C-g} following a -prefix key is not redefined in the minibuffer, and it has its normal -effect of canceling the prefix key and prefix argument. This too -would not be possible if @kbd{C-g} always quit directly. - - When @kbd{C-g} does directly quit, it does so by setting the variable -@code{quit-flag} to @code{t}. Emacs checks this variable at appropriate -times and quits if it is not @code{nil}. Setting @code{quit-flag} -non-@code{nil} in any way thus causes a quit. - - At the level of C code, quitting cannot happen just anywhere; only at the -special places that check @code{quit-flag}. The reason for this is -that quitting at other places might leave an inconsistency in Emacs's -internal state. Because quitting is delayed until a safe place, quitting -cannot make Emacs crash. - - Certain functions such as @code{read-key-sequence} or -@code{read-quoted-char} prevent quitting entirely even though they wait -for input. Instead of quitting, @kbd{C-g} serves as the requested -input. In the case of @code{read-key-sequence}, this serves to bring -about the special behavior of @kbd{C-g} in the command loop. In the -case of @code{read-quoted-char}, this is so that @kbd{C-q} can be used -to quote a @kbd{C-g}. - - You can prevent quitting for a portion of a Lisp function by binding -the variable @code{inhibit-quit} to a non-@code{nil} value. Then, -although @kbd{C-g} still sets @code{quit-flag} to @code{t} as usual, the -usual result of this---a quit---is prevented. Eventually, -@code{inhibit-quit} will become @code{nil} again, such as when its -binding is unwound at the end of a @code{let} form. At that time, if -@code{quit-flag} is still non-@code{nil}, the requested quit happens -immediately. This behavior is ideal when you wish to make sure that -quitting does not happen within a ``critical section'' of the program. - -@cindex @code{read-quoted-char} quitting - In some functions (such as @code{read-quoted-char}), @kbd{C-g} is -handled in a special way that does not involve quitting. This is done -by reading the input with @code{inhibit-quit} bound to @code{t}, and -setting @code{quit-flag} to @code{nil} before @code{inhibit-quit} -becomes @code{nil} again. This excerpt from the definition of -@code{read-quoted-char} shows how this is done; it also shows that -normal quitting is permitted after the first character of input. - -@example -(defun read-quoted-char (&optional prompt) - "@dots{}@var{documentation}@dots{}" - (let ((count 0) (code 0) char) - (while (< count 3) - (let ((inhibit-quit (zerop count)) - (help-form nil)) - (and prompt (message "%s-" prompt)) - (setq char (read-char)) - (if inhibit-quit (setq quit-flag nil))) - @dots{}) - (logand 255 code))) -@end example - -@defvar quit-flag -If this variable is non-@code{nil}, then Emacs quits immediately, unless -@code{inhibit-quit} is non-@code{nil}. Typing @kbd{C-g} ordinarily sets -@code{quit-flag} non-@code{nil}, regardless of @code{inhibit-quit}. -@end defvar - -@defvar inhibit-quit -This variable determines whether Emacs should quit when @code{quit-flag} -is set to a value other than @code{nil}. If @code{inhibit-quit} is -non-@code{nil}, then @code{quit-flag} has no special effect. -@end defvar - -@deffn Command keyboard-quit -This function signals the @code{quit} condition with @code{(signal 'quit -nil)}. This is the same thing that quitting does. (See @code{signal} -in @ref{Errors}.) -@end deffn - - You can specify a character other than @kbd{C-g} to use for quitting. -See the function @code{set-input-mode} in @ref{Terminal Input}. - -@node Prefix Command Arguments -@section Prefix Command Arguments -@cindex prefix argument -@cindex raw prefix argument -@cindex numeric prefix argument - - Most Emacs commands can use a @dfn{prefix argument}, a number -specified before the command itself. (Don't confuse prefix arguments -with prefix keys.) The prefix argument is at all times represented by a -value, which may be @code{nil}, meaning there is currently no prefix -argument. Each command may use the prefix argument or ignore it. - - There are two representations of the prefix argument: @dfn{raw} and -@dfn{numeric}. The editor command loop uses the raw representation -internally, and so do the Lisp variables that store the information, but -commands can request either representation. - - Here are the possible values of a raw prefix argument: - -@itemize @bullet -@item -@code{nil}, meaning there is no prefix argument. Its numeric value is -1, but numerous commands make a distinction between @code{nil} and the -integer 1. - -@item -An integer, which stands for itself. - -@item -A list of one element, which is an integer. This form of prefix -argument results from one or a succession of @kbd{C-u}'s with no -digits. The numeric value is the integer in the list, but some -commands make a distinction between such a list and an integer alone. - -@item -The symbol @code{-}. This indicates that @kbd{M--} or @kbd{C-u -} was -typed, without following digits. The equivalent numeric value is -@minus{}1, but some commands make a distinction between the integer -@minus{}1 and the symbol @code{-}. -@end itemize - -We illustrate these possibilities by calling the following function with -various prefixes: - -@example -@group -(defun display-prefix (arg) - "Display the value of the raw prefix arg." - (interactive "P") - (message "%s" arg)) -@end group -@end example - -@noindent -Here are the results of calling @code{display-prefix} with various -raw prefix arguments: - -@example - M-x display-prefix @print{} nil - -C-u M-x display-prefix @print{} (4) - -C-u C-u M-x display-prefix @print{} (16) - -C-u 3 M-x display-prefix @print{} 3 - -M-3 M-x display-prefix @print{} 3 ; @r{(Same as @code{C-u 3}.)} - -C-u - M-x display-prefix @print{} - - -M-- M-x display-prefix @print{} - ; @r{(Same as @code{C-u -}.)} - -C-u - 7 M-x display-prefix @print{} -7 - -M-- 7 M-x display-prefix @print{} -7 ; @r{(Same as @code{C-u -7}.)} -@end example - - Emacs uses two variables to store the prefix argument: -@code{prefix-arg} and @code{current-prefix-arg}. Commands such as -@code{universal-argument} that set up prefix arguments for other -commands store them in @code{prefix-arg}. In contrast, -@code{current-prefix-arg} conveys the prefix argument to the current -command, so setting it has no effect on the prefix arguments for future -commands. - - Normally, commands specify which representation to use for the prefix -argument, either numeric or raw, in the @code{interactive} declaration. -(@xref{Using Interactive}.) Alternatively, functions may look at the -value of the prefix argument directly in the variable -@code{current-prefix-arg}, but this is less clean. - -@defun prefix-numeric-value arg -This function returns the numeric meaning of a valid raw prefix argument -value, @var{arg}. The argument may be a symbol, a number, or a list. -If it is @code{nil}, the value 1 is returned; if it is @code{-}, the -value @minus{}1 is returned; if it is a number, that number is returned; -if it is a list, the @sc{car} of that list (which should be a number) is -returned. -@end defun - -@defvar current-prefix-arg -This variable holds the raw prefix argument for the @emph{current} -command. Commands may examine it directly, but the usual method for -accessing it is with @code{(interactive "P")}. -@end defvar - -@defvar prefix-arg -The value of this variable is the raw prefix argument for the -@emph{next} editing command. Commands that specify prefix arguments for -the following command work by setting this variable. -@end defvar - - Do not call @code{universal-argument}, @code{digit-argument}, or -@code{negative-argument} unless you intend to let the user enter the -prefix argument for the @emph{next} command. - -@deffn Command universal-argument -This command reads input and specifies a prefix argument for the -following command. Don't call this command yourself unless you know -what you are doing. -@end deffn - -@deffn Command digit-argument arg -This command adds to the prefix argument for the following command. The -argument @var{arg} is the raw prefix argument as it was before this -command; it is used to compute the updated prefix argument. Don't call -this command yourself unless you know what you are doing. -@end deffn - -@deffn Command negative-argument arg -This command adds to the numeric argument for the next command. The -argument @var{arg} is the raw prefix argument as it was before this -command; its value is negated to form the new prefix argument. Don't -call this command yourself unless you know what you are doing. -@end deffn - -@node Recursive Editing -@section Recursive Editing -@cindex recursive command loop -@cindex recursive editing level -@cindex command loop, recursive - - The Emacs command loop is entered automatically when Emacs starts up. -This top-level invocation of the command loop never exits; it keeps -running as long as Emacs does. Lisp programs can also invoke the -command loop. Since this makes more than one activation of the command -loop, we call it @dfn{recursive editing}. A recursive editing level has -the effect of suspending whatever command invoked it and permitting the -user to do arbitrary editing before resuming that command. - - The commands available during recursive editing are the same ones -available in the top-level editing loop and defined in the keymaps. -Only a few special commands exit the recursive editing level; the others -return to the recursive editing level when they finish. (The special -commands for exiting are always available, but they do nothing when -recursive editing is not in progress.) - - All command loops, including recursive ones, set up all-purpose error -handlers so that an error in a command run from the command loop will -not exit the loop. - -@cindex minibuffer input - Minibuffer input is a special kind of recursive editing. It has a few -special wrinkles, such as enabling display of the minibuffer and the -minibuffer window, but fewer than you might suppose. Certain keys -behave differently in the minibuffer, but that is only because of the -minibuffer's local map; if you switch windows, you get the usual Emacs -commands. - -@cindex @code{throw} example -@kindex exit -@cindex exit recursive editing -@cindex aborting - To invoke a recursive editing level, call the function -@code{recursive-edit}. This function contains the command loop; it also -contains a call to @code{catch} with tag @code{exit}, which makes it -possible to exit the recursive editing level by throwing to @code{exit} -(@pxref{Catch and Throw}). If you throw a value other than @code{t}, -then @code{recursive-edit} returns normally to the function that called -it. The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. -Throwing a @code{t} value causes @code{recursive-edit} to quit, so that -control returns to the command loop one level up. This is called -@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}). - - Most applications should not use recursive editing, except as part of -using the minibuffer. Usually it is more convenient for the user if you -change the major mode of the current buffer temporarily to a special -major mode, which should have a command to go back to the previous mode. -(The @kbd{e} command in Rmail uses this technique.) Or, if you wish to -give the user different text to edit ``recursively'', create and select -a new buffer in a special mode. In this mode, define a command to -complete the processing and go back to the previous buffer. (The -@kbd{m} command in Rmail does this.) - - Recursive edits are useful in debugging. You can insert a call to -@code{debug} into a function definition as a sort of breakpoint, so that -you can look around when the function gets there. @code{debug} invokes -a recursive edit but also provides the other features of the debugger. - - Recursive editing levels are also used when you type @kbd{C-r} in -@code{query-replace} or use @kbd{C-x q} (@code{kbd-macro-query}). - -@defun recursive-edit -@cindex suspend evaluation -This function invokes the editor command loop. It is called -automatically by the initialization of Emacs, to let the user begin -editing. When called from a Lisp program, it enters a recursive editing -level. - - In the following example, the function @code{simple-rec} first -advances point one word, then enters a recursive edit, printing out a -message in the echo area. The user can then do any editing desired, and -then type @kbd{C-M-c} to exit and continue executing @code{simple-rec}. - -@example -(defun simple-rec () - (forward-word 1) - (message "Recursive edit in progress") - (recursive-edit) - (forward-word 1)) - @result{} simple-rec -(simple-rec) - @result{} nil -@end example -@end defun - -@deffn Command exit-recursive-edit -This function exits from the innermost recursive edit (including -minibuffer input). Its definition is effectively @code{(throw 'exit -nil)}. -@end deffn - -@deffn Command abort-recursive-edit -This function aborts the command that requested the innermost recursive -edit (including minibuffer input), by signaling @code{quit} -after exiting the recursive edit. Its definition is effectively -@code{(throw 'exit t)}. @xref{Quitting}. -@end deffn - -@deffn Command top-level -This function exits all recursive editing levels; it does not return a -value, as it jumps completely out of any computation directly back to -the main command loop. -@end deffn - -@defun recursion-depth -This function returns the current depth of recursive edits. When no -recursive edit is active, it returns 0. -@end defun - -@node Disabling Commands -@section Disabling Commands -@cindex disabled command - - @dfn{Disabling a command} marks the command as requiring user -confirmation before it can be executed. Disabling is used for commands -which might be confusing to beginning users, to prevent them from using -the commands by accident. - -@kindex disabled - The low-level mechanism for disabling a command is to put a -non-@code{nil} @code{disabled} property on the Lisp symbol for the -command. These properties are normally set up by the user's -@file{.emacs} file with Lisp expressions such as this: - -@example -(put 'upcase-region 'disabled t) -@end example - -@noindent -For a few commands, these properties are present by default and may be -removed by the @file{.emacs} file. - - If the value of the @code{disabled} property is a string, the message -saying the command is disabled includes that string. For example: - -@example -(put 'delete-region 'disabled - "Text deleted this way cannot be yanked back!\n") -@end example - - @xref{Disabling,,, emacs, The GNU Emacs Manual}, for the details on -what happens when a disabled command is invoked interactively. -Disabling a command has no effect on calling it as a function from Lisp -programs. - -@deffn Command enable-command command -Allow @var{command} to be executed without special confirmation from now -on, and (if the user confirms) alter the user's @file{.emacs} file so -that this will apply to future sessions. -@end deffn - -@deffn Command disable-command command -Require special confirmation to execute @var{command} from now on, and -(if the user confirms) alter the user's @file{.emacs} file so that this -will apply to future sessions. -@end deffn - -@defvar disabled-command-hook -This normal hook is run instead of a disabled command, when the user -invokes the disabled command interactively. The hook functions can use -@code{this-command-keys} to determine what the user typed to run the -command, and thus find the command itself. @xref{Hooks}. - -By default, @code{disabled-command-hook} contains a function that asks -the user whether to proceed. -@end defvar - -@node Command History -@section Command History -@cindex command history -@cindex complex command -@cindex history of commands - - The command loop keeps a history of the complex commands that have -been executed, to make it convenient to repeat these commands. A -@dfn{complex command} is one for which the interactive argument reading -uses the minibuffer. This includes any @kbd{M-x} command, any -@kbd{M-:} command, and any command whose @code{interactive} -specification reads an argument from the minibuffer. Explicit use of -the minibuffer during the execution of the command itself does not cause -the command to be considered complex. - -@defvar command-history -This variable's value is a list of recent complex commands, each -represented as a form to evaluate. It continues to accumulate all -complex commands for the duration of the editing session, but all but -the first (most recent) thirty elements are deleted when a garbage -collection takes place (@pxref{Garbage Collection}). - -@example -@group -command-history -@result{} ((switch-to-buffer "chistory.texi") - (describe-key "^X^[") - (visit-tags-table "~/emacs/src/") - (find-tag "repeat-complex-command")) -@end group -@end example -@end defvar - - This history list is actually a special case of minibuffer history -(@pxref{Minibuffer History}), with one special twist: the elements are -expressions rather than strings. - - There are a number of commands devoted to the editing and recall of -previous commands. The commands @code{repeat-complex-command}, and -@code{list-command-history} are described in the user manual -(@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the -minibuffer, the history commands used are the same ones available in any -minibuffer. - -@node Keyboard Macros -@section Keyboard Macros -@cindex keyboard macros - - A @dfn{keyboard macro} is a canned sequence of input events that can -be considered a command and made the definition of a key. The Lisp -representation of a keyboard macro is a string or vector containing the -events. Don't confuse keyboard macros with Lisp macros -(@pxref{Macros}). - -@defun execute-kbd-macro macro &optional count -This function executes @var{macro} as a sequence of events. If -@var{macro} is a string or vector, then the events in it are executed -exactly as if they had been input by the user. The sequence is -@emph{not} expected to be a single key sequence; normally a keyboard -macro definition consists of several key sequences concatenated. - -If @var{macro} is a symbol, then its function definition is used in -place of @var{macro}. If that is another symbol, this process repeats. -Eventually the result should be a string or vector. If the result is -not a symbol, string, or vector, an error is signaled. - -The argument @var{count} is a repeat count; @var{macro} is executed that -many times. If @var{count} is omitted or @code{nil}, @var{macro} is -executed once. If it is 0, @var{macro} is executed over and over until it -encounters an error or a failing search. -@end defun - -@defvar executing-macro -This variable contains the string or vector that defines the keyboard -macro that is currently executing. It is @code{nil} if no macro is -currently executing. A command can test this variable to behave -differently when run from an executing macro. Do not set this variable -yourself. -@end defvar - -@defvar defining-kbd-macro -This variable indicates whether a keyboard macro is being defined. A -command can test this variable to behave differently while a macro is -being defined. The commands @code{start-kbd-macro} and -@code{end-kbd-macro} set this variable---do not set it yourself. - -The variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Displays}. -@end defvar - -@defvar last-kbd-macro -This variable is the definition of the most recently defined keyboard -macro. Its value is a string or vector, or @code{nil}. - -The variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Displays}. -@end defvar - diff --git a/lispref/compile.texi b/lispref/compile.texi deleted file mode 100644 index d43ea51f074..00000000000 --- a/lispref/compile.texi +++ /dev/null @@ -1,731 +0,0 @@ -@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/compile -@node Byte Compilation, Debugging, Loading, Top -@chapter Byte Compilation -@cindex byte-code -@cindex compilation - - GNU Emacs Lisp has a @dfn{compiler} that translates functions written -in Lisp into a special representation called @dfn{byte-code} that can be -executed more efficiently. The compiler replaces Lisp function -definitions with byte-code. When a byte-code function is called, its -definition is evaluated by the @dfn{byte-code interpreter}. - - Because the byte-compiled code is evaluated by the byte-code -interpreter, instead of being executed directly by the machine's -hardware (as true compiled code is), byte-code is completely -transportable from machine to machine without recompilation. It is not, -however, as fast as true compiled code. - - In general, any version of Emacs can run byte-compiled code produced -by recent earlier versions of Emacs, but the reverse is not true. In -particular, if you compile a program with Emacs 19.29, the compiled -code does not run in earlier versions. -@iftex -@xref{Docs and Compilation}. -@end iftex -Files compiled in versions before 19.29 may not work in 19.29 if they -contain character constants with modifier bits, because the bits were -renumbered in Emacs 19.29. - - @xref{Compilation Errors}, for how to investigate errors occurring in -byte compilation. - -@menu -* Speed of Byte-Code:: An example of speedup from byte compilation. -* Compilation Functions:: Byte compilation functions. -* Docs and Compilation:: Dynamic loading of documentation strings. -* Dynamic Loading:: Dynamic loading of individual functions. -* Eval During Compile:: Code to be evaluated when you compile. -* Byte-Code Objects:: The data type used for byte-compiled functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. -@end menu - -@node Speed of Byte-Code -@section Performance of Byte-Compiled Code - - A byte-compiled function is not as efficient as a primitive function -written in C, but runs much faster than the version written in Lisp. -Here is an example: - -@example -@group -(defun silly-loop (n) - "Return time before and after N iterations of a loop." - (let ((t1 (current-time-string))) - (while (> (setq n (1- n)) - 0)) - (list t1 (current-time-string)))) -@result{} silly-loop -@end group - -@group -(silly-loop 100000) -@result{} ("Fri Mar 18 17:25:57 1994" - "Fri Mar 18 17:26:28 1994") ; @r{31 seconds} -@end group - -@group -(byte-compile 'silly-loop) -@result{} @r{[Compiled code not shown]} -@end group - -@group -(silly-loop 100000) -@result{} ("Fri Mar 18 17:26:52 1994" - "Fri Mar 18 17:26:58 1994") ; @r{6 seconds} -@end group -@end example - - In this example, the interpreted code required 31 seconds to run, -whereas the byte-compiled code required 6 seconds. These results are -representative, but actual results will vary greatly. - -@node Compilation Functions -@comment node-name, next, previous, up -@section The Compilation Functions -@cindex compilation functions - - You can byte-compile an individual function or macro definition with -the @code{byte-compile} function. You can compile a whole file with -@code{byte-compile-file}, or several files with -@code{byte-recompile-directory} or @code{batch-byte-compile}. - - The byte compiler produces error messages and warnings about each file -in a buffer called @samp{*Compile-Log*}. These report things in your -program that suggest a problem but are not necessarily erroneous. - -@cindex macro compilation - Be careful when byte-compiling code that uses macros. Macro calls are -expanded when they are compiled, so the macros must already be defined -for proper compilation. For more details, see @ref{Compiling Macros}. - - Normally, compiling a file does not evaluate the file's contents or -load the file. But it does execute any @code{require} calls at top -level in the file. One way to ensure that necessary macro definitions -are available during compilation is to require the file that defines -them (@pxref{Named Features}). To avoid loading the macro definition files -when someone @emph{runs} the compiled program, write -@code{eval-when-compile} around the @code{require} calls (@pxref{Eval -During Compile}). - -@defun byte-compile symbol -This function byte-compiles the function definition of @var{symbol}, -replacing the previous definition with the compiled one. The function -definition of @var{symbol} must be the actual code for the function; -i.e., the compiler does not follow indirection to another symbol. -@code{byte-compile} returns the new, compiled definition of -@var{symbol}. - - If @var{symbol}'s definition is a byte-code function object, -@code{byte-compile} does nothing and returns @code{nil}. Lisp records -only one function definition for any symbol, and if that is already -compiled, non-compiled code is not available anywhere. So there is no -way to ``compile the same definition again.'' - -@example -@group -(defun factorial (integer) - "Compute factorial of INTEGER." - (if (= 1 integer) 1 - (* integer (factorial (1- integer))))) -@result{} factorial -@end group - -@group -(byte-compile 'factorial) -@result{} -#[(integer) - "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" - [integer 1 * factorial] - 4 "Compute factorial of INTEGER."] -@end group -@end example - -@noindent -The result is a byte-code function object. The string it contains is -the actual byte-code; each character in it is an instruction or an -operand of an instruction. The vector contains all the constants, -variable names and function names used by the function, except for -certain primitives that are coded as special instructions. -@end defun - -@deffn Command compile-defun -This command reads the defun containing point, compiles it, and -evaluates the result. If you use this on a defun that is actually a -function definition, the effect is to install a compiled version of that -function. -@end deffn - -@deffn Command byte-compile-file filename -This function compiles a file of Lisp code named @var{filename} into -a file of byte-code. The output file's name is made by appending -@samp{c} to the end of @var{filename}. - -Compilation works by reading the input file one form at a time. If it -is a definition of a function or macro, the compiled function or macro -definition is written out. Other forms are batched together, then each -batch is compiled, and written so that its compiled code will be -executed when the file is read. All comments are discarded when the -input file is read. - -This command returns @code{t}. When called interactively, it prompts -for the file name. - -@example -@group -% ls -l push* --rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el -@end group - -@group -(byte-compile-file "~/emacs/push.el") - @result{} t -@end group - -@group -% ls -l push* --rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el --rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc -@end group -@end example -@end deffn - -@deffn Command byte-recompile-directory directory flag -@cindex library compilation -This function recompiles every @samp{.el} file in @var{directory} that -needs recompilation. A file needs recompilation if a @samp{.elc} file -exists but is older than the @samp{.el} file. - -When a @samp{.el} file has no corresponding @samp{.elc} file, then -@var{flag} says what to do. If it is @code{nil}, these files are -ignored. If it is non-@code{nil}, the user is asked whether to compile -each such file. - -The returned value of this command is unpredictable. -@end deffn - -@defun batch-byte-compile -This function runs @code{byte-compile-file} on files specified on the -command line. This function must be used only in a batch execution of -Emacs, as it kills Emacs on completion. An error in one file does not -prevent processing of subsequent files. (The file that gets the error -will not, of course, produce any compiled code.) - -@example -% emacs -batch -f batch-byte-compile *.el -@end example -@end defun - -@defun byte-code code-string data-vector max-stack -@cindex byte-code interpreter -This function actually interprets byte-code. A byte-compiled function -is actually defined with a body that calls @code{byte-code}. Don't call -this function yourself. Only the byte compiler knows how to generate -valid calls to this function. - -In newer Emacs versions (19 and up), byte-code is usually executed as -part of a byte-code function object, and only rarely due to an explicit -call to @code{byte-code}. -@end defun - -@node Docs and Compilation -@section Documentation Strings and Compilation -@cindex dynamic loading of documentation - - Functions and variables loaded from a byte-compiled file access their -documentation strings dynamically from the file whenever needed. This -saves space within Emacs, and makes loading faster because the -documentation strings themselves need not be processed while loading the -file. Actual access to the documentation strings becomes slower as a -result, but this normally is not enough to bother users. - - Dynamic access to documentation strings does have drawbacks: - -@itemize @bullet -@item -If you delete or move the compiled file after loading it, Emacs can no -longer access the documentation strings for the functions and variables -in the file. - -@item -If you alter the compiled file (such as by compiling a new version), -then further access to documentation strings in this file will give -nonsense results. -@end itemize - - If your site installs Emacs following the usual procedures, these -problems will never normally occur. Installing a new version uses a new -directory with a different name; as long as the old version remains -installed, its files will remain unmodified in the places where they are -expected to be. - - However, if you have built Emacs yourself and use it from the -directory where you built it, you will experience this problem -occasionally if you edit and recompile Lisp files. When it happens, you -can cure the problem by reloading the file after recompiling it. - - Byte-compiled files made with Emacs 19.29 will not load into older -versions because the older versions don't support this feature. You can -turn off this feature by setting @code{byte-compile-dynamic-docstrings} -to @code{nil}. Once this is done, you can compile files that will load -into older Emacs versions. You can do this globally, or for one source -file by specifying a file-local binding for the variable. Here's one -way to do that: - -@example --*-byte-compile-dynamic-docstrings: nil;-*- -@end example - -@defvar byte-compile-dynamic-docstrings -If this is non-@code{nil}, the byte compiler generates compiled files -that are set up for dynamic loading of documentation strings. -@end defvar - -@cindex @samp{#@@@var{count}} -@cindex @samp{#$} - The dynamic documentation string feature writes compiled files that -use a special Lisp reader construct, @samp{#@@@var{count}}. This -construct skips the next @var{count} characters. It also uses the -@samp{#$} construct, which stands for ``the name of this file, as a -string.'' It is best not to use these constructs in Lisp source files. - -@node Dynamic Loading -@section Dynamic Loading of Individual Functions - -@cindex dynamic loading of functions -@cindex lazy loading - When you compile a file, you can optionally enable the @dfn{dynamic -function loading} feature (also known as @dfn{lazy loading}). With -dynamic function loading, loading the file doesn't fully read the -function definitions in the file. Instead, each function definition -contains a place-holder which refers to the file. The first time each -function is called, it reads the full definition from the file, to -replace the place-holder. - - The advantage of dynamic function loading is that loading the file -becomes much faster. This is a good thing for a file which contains -many separate commands, provided that using one of them does not imply -you will soon (or ever) use the rest. A specialized mode which provides -many keyboard commands often has that usage pattern: a user may invoke -the mode, but use only a few of the commands it provides. - - The dynamic loading feature has certain disadvantages: - -@itemize @bullet -@item -If you delete or move the compiled file after loading it, Emacs can no -longer load the remaining function definitions not already loaded. - -@item -If you alter the compiled file (such as by compiling a new version), -then trying to load any function not already loaded will get nonsense -results. -@end itemize - - If you compile a new version of the file, the best thing to do is -immediately load the new compiled file. That will prevent any future -problems. - - The byte compiler uses the dynamic function loading feature if the -variable @code{byte-compile-dynamic} is non-@code{nil} at compilation -time. Do not set this variable globally, since dynamic loading is -desirable only for certain files. Instead, enable the feature for -specific source files with file-local variable bindings, like this: - -@example --*-byte-compile-dynamic: t;-*- -@end example - -@defvar byte-compile-dynamic -If this is non-@code{nil}, the byte compiler generates compiled files -that are set up for dynamic function loading. -@end defvar - -@defun fetch-bytecode function -This immediately finishes loading the definition of @var{function} from -its byte-compiled file, if it is not fully loaded already. The argument -@var{function} may be a byte-code function object or a function name. -@end defun - -@node Eval During Compile -@section Evaluation During Compilation - - These features permit you to write code to be evaluated during -compilation of a program. - -@defspec eval-and-compile body -This form marks @var{body} to be evaluated both when you compile the -containing code and when you run it (whether compiled or not). - -You can get a similar result by putting @var{body} in a separate file -and referring to that file with @code{require}. Using @code{require} is -preferable if there is a substantial amount of code to be executed in -this way. -@end defspec - -@defspec eval-when-compile body -This form marks @var{body} to be evaluated at compile time and not when -the compiled program is loaded. The result of evaluation by the -compiler becomes a constant which appears in the compiled program. When -the program is interpreted, not compiled at all, @var{body} is evaluated -normally. - -At top level, this is analogous to the Common Lisp idiom -@code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp -@samp{#.} reader macro (but not when interpreting) is closer to what -@code{eval-when-compile} does. -@end defspec - -@node Byte-Code Objects -@section Byte-Code Function Objects -@cindex compiled function -@cindex byte-code function - - Byte-compiled functions have a special data type: they are -@dfn{byte-code function objects}. - - Internally, a byte-code function object is much like a vector; -however, the evaluator handles this data type specially when it appears -as a function to be called. The printed representation for a byte-code -function object is like that for a vector, with an additional @samp{#} -before the opening @samp{[}. - - In Emacs version 18, there was no byte-code function object data type; -compiled functions used the function @code{byte-code} to run the byte -code. - - A byte-code function object must have at least four elements; there is -no maximum number, but only the first six elements are actually used. -They are: - -@table @var -@item arglist -The list of argument symbols. - -@item byte-code -The string containing the byte-code instructions. - -@item constants -The vector of Lisp objects referenced by the byte code. These include -symbols used as function names and variable names. - -@item stacksize -The maximum stack size this function needs. - -@item docstring -The documentation string (if any); otherwise, @code{nil}. The value may -be a number or a list, in case the documentation string is stored in a -file. Use the function @code{documentation} to get the real -documentation string (@pxref{Accessing Documentation}). - -@item interactive -The interactive spec (if any). This can be a string or a Lisp -expression. It is @code{nil} for a function that isn't interactive. -@end table - -Here's an example of a byte-code function object, in printed -representation. It is the definition of the command -@code{backward-sexp}. - -@example -#[(&optional arg) - "^H\204^F^@@\301^P\302^H[!\207" - [arg 1 forward-sexp] - 2 - 254435 - "p"] -@end example - - The primitive way to create a byte-code object is with -@code{make-byte-code}: - -@defun make-byte-code &rest elements -This function constructs and returns a byte-code function object -with @var{elements} as its elements. -@end defun - - You should not try to come up with the elements for a byte-code -function yourself, because if they are inconsistent, Emacs may crash -when you call the function. Always leave it to the byte compiler to -create these objects; it makes the elements consistent (we hope). - - You can access the elements of a byte-code object using @code{aref}; -you can also use @code{vconcat} to create a vector with the same -elements. - -@node Disassembly -@section Disassembled Byte-Code -@cindex disassembled byte-code - - People do not write byte-code; that job is left to the byte compiler. -But we provide a disassembler to satisfy a cat-like curiosity. The -disassembler converts the byte-compiled code into humanly readable -form. - - The byte-code interpreter is implemented as a simple stack machine. -It pushes values onto a stack of its own, then pops them off to use them -in calculations whose results are themselves pushed back on the stack. -When a byte-code function returns, it pops a value off the stack and -returns it as the value of the function. - - In addition to the stack, byte-code functions can use, bind, and set -ordinary Lisp variables, by transferring values between variables and -the stack. - -@deffn Command disassemble object &optional stream -This function prints the disassembled code for @var{object}. If -@var{stream} is supplied, then output goes there. Otherwise, the -disassembled code is printed to the stream @code{standard-output}. The -argument @var{object} can be a function name or a lambda expression. - -As a special exception, if this function is used interactively, -it outputs to a buffer named @samp{*Disassemble*}. -@end deffn - - Here are two examples of using the @code{disassemble} function. We -have added explanatory comments to help you relate the byte-code to the -Lisp source; these do not appear in the output of @code{disassemble}. -These examples show unoptimized byte-code. Nowadays byte-code is -usually optimized, but we did not want to rewrite these examples, since -they still serve their purpose. - -@example -@group -(defun factorial (integer) - "Compute factorial of an integer." - (if (= 1 integer) 1 - (* integer (factorial (1- integer))))) - @result{} factorial -@end group - -@group -(factorial 4) - @result{} 24 -@end group - -@group -(disassemble 'factorial) - @print{} byte-code for factorial: - doc: Compute factorial of an integer. - args: (integer) -@end group - -@group -0 constant 1 ; @r{Push 1 onto stack.} - -1 varref integer ; @r{Get value of @code{integer}} - ; @r{from the environment} - ; @r{and push the value} - ; @r{onto the stack.} -@end group - -@group -2 eqlsign ; @r{Pop top two values off stack,} - ; @r{compare them,} - ; @r{and push result onto stack.} -@end group - -@group -3 goto-if-nil 10 ; @r{Pop and test top of stack;} - ; @r{if @code{nil}, go to 10,} - ; @r{else continue.} -@end group - -@group -6 constant 1 ; @r{Push 1 onto top of stack.} - -7 goto 17 ; @r{Go to 17 (in this case, 1 will be} - ; @r{returned by the function).} -@end group - -@group -10 constant * ; @r{Push symbol @code{*} onto stack.} - -11 varref integer ; @r{Push value of @code{integer} onto stack.} -@end group - -@group -12 constant factorial ; @r{Push @code{factorial} onto stack.} - -13 varref integer ; @r{Push value of @code{integer} onto stack.} - -14 sub1 ; @r{Pop @code{integer}, decrement value,} - ; @r{push new value onto stack.} -@end group - -@group - ; @r{Stack now contains:} - ; @minus{} @r{decremented value of @code{integer}} - ; @minus{} @r{@code{factorial}} - ; @minus{} @r{value of @code{integer}} - ; @minus{} @r{@code{*}} -@end group - -@group -15 call 1 ; @r{Call function @code{factorial} using} - ; @r{the first (i.e., the top) element} - ; @r{of the stack as the argument;} - ; @r{push returned value onto stack.} -@end group - -@group - ; @r{Stack now contains:} - ; @minus{} @r{result of recursive} - ; @r{call to @code{factorial}} - ; @minus{} @r{value of @code{integer}} - ; @minus{} @r{@code{*}} -@end group - -@group -16 call 2 ; @r{Using the first two} - ; @r{(i.e., the top two)} - ; @r{elements of the stack} - ; @r{as arguments,} - ; @r{call the function @code{*},} - ; @r{pushing the result onto the stack.} -@end group - -@group -17 return ; @r{Return the top element} - ; @r{of the stack.} - @result{} nil -@end group -@end example - -The @code{silly-loop} function is somewhat more complex: - -@example -@group -(defun silly-loop (n) - "Return time before and after N iterations of a loop." - (let ((t1 (current-time-string))) - (while (> (setq n (1- n)) - 0)) - (list t1 (current-time-string)))) - @result{} silly-loop -@end group - -@group -(disassemble 'silly-loop) - @print{} byte-code for silly-loop: - doc: Return time before and after N iterations of a loop. - args: (n) - -0 constant current-time-string ; @r{Push} - ; @r{@code{current-time-string}} - ; @r{onto top of stack.} -@end group - -@group -1 call 0 ; @r{Call @code{current-time-string}} - ; @r{ with no argument,} - ; @r{ pushing result onto stack.} -@end group - -@group -2 varbind t1 ; @r{Pop stack and bind @code{t1}} - ; @r{to popped value.} -@end group - -@group -3 varref n ; @r{Get value of @code{n} from} - ; @r{the environment and push} - ; @r{the value onto the stack.} -@end group - -@group -4 sub1 ; @r{Subtract 1 from top of stack.} -@end group - -@group -5 dup ; @r{Duplicate the top of the stack;} - ; @r{i.e., copy the top of} - ; @r{the stack and push the} - ; @r{copy onto the stack.} -@end group - -@group -6 varset n ; @r{Pop the top of the stack,} - ; @r{and bind @code{n} to the value.} - - ; @r{In effect, the sequence @code{dup varset}} - ; @r{copies the top of the stack} - ; @r{into the value of @code{n}} - ; @r{without popping it.} -@end group - -@group -7 constant 0 ; @r{Push 0 onto stack.} -@end group - -@group -8 gtr ; @r{Pop top two values off stack,} - ; @r{test if @var{n} is greater than 0} - ; @r{and push result onto stack.} -@end group - -@group -9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0} - ; @r{(this exits the while loop).} - ; @r{else pop top of stack} - ; @r{and continue} -@end group - -@group -12 constant nil ; @r{Push @code{nil} onto stack} - ; @r{(this is the body of the loop).} -@end group - -@group -13 discard ; @r{Discard result of the body} - ; @r{of the loop (a while loop} - ; @r{is always evaluated for} - ; @r{its side effects).} -@end group - -@group -14 goto 3 ; @r{Jump back to beginning} - ; @r{of while loop.} -@end group - -@group -17 discard ; @r{Discard result of while loop} - ; @r{by popping top of stack.} - ; @r{This result is the value @code{nil} that} - ; @r{was not popped by the goto at 9.} -@end group - -@group -18 varref t1 ; @r{Push value of @code{t1} onto stack.} -@end group - -@group -19 constant current-time-string ; @r{Push} - ; @r{@code{current-time-string}} - ; @r{onto top of stack.} -@end group - -@group -20 call 0 ; @r{Call @code{current-time-string} again.} -@end group - -@group -21 list2 ; @r{Pop top two elements off stack,} - ; @r{create a list of them,} - ; @r{and push list onto stack.} -@end group - -@group -22 unbind 1 ; @r{Unbind @code{t1} in local environment.} - -23 return ; @r{Return value of the top of stack.} - - @result{} nil -@end group -@end example - - diff --git a/lispref/control.texi b/lispref/control.texi deleted file mode 100644 index 4973599d877..00000000000 --- a/lispref/control.texi +++ /dev/null @@ -1,1157 +0,0 @@ -@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/control -@node Control Structures, Variables, Evaluation, Top -@chapter Control Structures -@cindex special forms for control structures -@cindex control structures - - A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}). -We control the order of execution of the forms by enclosing them in -@dfn{control structures}. Control structures are special forms which -control when, whether, or how many times to execute the forms they -contain. - - The simplest order of execution is sequential execution: first form -@var{a}, then form @var{b}, and so on. This is what happens when you -write several forms in succession in the body of a function, or at top -level in a file of Lisp code---the forms are executed in the order -written. We call this @dfn{textual order}. For example, if a function -body consists of two forms @var{a} and @var{b}, evaluation of the -function evaluates first @var{a} and then @var{b}, and the function's -value is the value of @var{b}. - - Explicit control structures make possible an order of execution other -than sequential. - - Emacs Lisp provides several kinds of control structure, including -other varieties of sequencing, conditionals, iteration, and (controlled) -jumps---all discussed below. The built-in control structures are -special forms since their subforms are not necessarily evaluated or not -evaluated sequentially. You can use macros to define your own control -structure constructs (@pxref{Macros}). - -@menu -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. -@end menu - -@node Sequencing -@section Sequencing - - Evaluating forms in the order they appear is the most common way -control passes from one form to another. In some contexts, such as in a -function body, this happens automatically. Elsewhere you must use a -control structure construct to do this: @code{progn}, the simplest -control construct of Lisp. - - A @code{progn} special form looks like this: - -@example -@group -(progn @var{a} @var{b} @var{c} @dots{}) -@end group -@end example - -@noindent -and it says to execute the forms @var{a}, @var{b}, @var{c} and so on, in -that order. These forms are called the body of the @code{progn} form. -The value of the last form in the body becomes the value of the entire -@code{progn}. - -@cindex implicit @code{progn} - In the early days of Lisp, @code{progn} was the only way to execute -two or more forms in succession and use the value of the last of them. -But programmers found they often needed to use a @code{progn} in the -body of a function, where (at that time) only one form was allowed. So -the body of a function was made into an ``implicit @code{progn}'': -several forms are allowed just as in the body of an actual @code{progn}. -Many other control structures likewise contain an implicit @code{progn}. -As a result, @code{progn} is not used as often as it used to be. It is -needed now most often inside an @code{unwind-protect}, @code{and}, -@code{or}, or in the @var{then}-part of an @code{if}. - -@defspec progn forms@dots{} -This special form evaluates all of the @var{forms}, in textual -order, returning the result of the final form. - -@example -@group -(progn (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The third form" -@end group -@end example -@end defspec - - Two other control constructs likewise evaluate a series of forms but return -a different value: - -@defspec prog1 form1 forms@dots{} -This special form evaluates @var{form1} and all of the @var{forms}, in -textual order, returning the result of @var{form1}. - -@example -@group -(prog1 (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The first form" -@end group -@end example - -Here is a way to remove the first element from a list in the variable -@code{x}, then return the value of that former element: - -@example -(prog1 (car x) (setq x (cdr x))) -@end example -@end defspec - -@defspec prog2 form1 form2 forms@dots{} -This special form evaluates @var{form1}, @var{form2}, and all of the -following @var{forms}, in textual order, returning the result of -@var{form2}. - -@example -@group -(prog2 (print "The first form") - (print "The second form") - (print "The third form")) - @print{} "The first form" - @print{} "The second form" - @print{} "The third form" -@result{} "The second form" -@end group -@end example -@end defspec - -@node Conditionals -@section Conditionals -@cindex conditional evaluation - - Conditional control structures choose among alternatives. Emacs Lisp -has two conditional forms: @code{if}, which is much the same as in other -languages, and @code{cond}, which is a generalized case statement. - -@defspec if condition then-form else-forms@dots{} -@code{if} chooses between the @var{then-form} and the @var{else-forms} -based on the value of @var{condition}. If the evaluated @var{condition} is -non-@code{nil}, @var{then-form} is evaluated and the result returned. -Otherwise, the @var{else-forms} are evaluated in textual order, and the -value of the last one is returned. (The @var{else} part of @code{if} is -an example of an implicit @code{progn}. @xref{Sequencing}.) - -If @var{condition} has the value @code{nil}, and no @var{else-forms} are -given, @code{if} returns @code{nil}. - -@code{if} is a special form because the branch that is not selected is -never evaluated---it is ignored. Thus, in the example below, -@code{true} is not printed because @code{print} is never called. - -@example -@group -(if nil - (print 'true) - 'very-false) -@result{} very-false -@end group -@end example -@end defspec - -@defspec cond clause@dots{} -@code{cond} chooses among an arbitrary number of alternatives. Each -@var{clause} in the @code{cond} must be a list. The @sc{car} of this -list is the @var{condition}; the remaining elements, if any, the -@var{body-forms}. Thus, a clause looks like this: - -@example -(@var{condition} @var{body-forms}@dots{}) -@end example - -@code{cond} tries the clauses in textual order, by evaluating the -@var{condition} of each clause. If the value of @var{condition} is -non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its -@var{body-forms}, and the value of the last of @var{body-forms} becomes -the value of the @code{cond}. The remaining clauses are ignored. - -If the value of @var{condition} is @code{nil}, the clause ``fails'', so -the @code{cond} moves on to the following clause, trying its -@var{condition}. - -If every @var{condition} evaluates to @code{nil}, so that every clause -fails, @code{cond} returns @code{nil}. - -A clause may also look like this: - -@example -(@var{condition}) -@end example - -@noindent -Then, if @var{condition} is non-@code{nil} when tested, the value of -@var{condition} becomes the value of the @code{cond} form. - -The following example has four clauses, which test for the cases where -the value of @code{x} is a number, string, buffer and symbol, -respectively: - -@example -@group -(cond ((numberp x) x) - ((stringp x) x) - ((bufferp x) - (setq temporary-hack x) ; @r{multiple body-forms} - (buffer-name x)) ; @r{in one clause} - ((symbolp x) (symbol-value x))) -@end group -@end example - -Often we want to execute the last clause whenever none of the previous -clauses was successful. To do this, we use @code{t} as the -@var{condition} of the last clause, like this: @code{(t -@var{body-forms})}. The form @code{t} evaluates to @code{t}, which is -never @code{nil}, so this clause never fails, provided the @code{cond} -gets to it at all. - -For example, - -@example -@group -(cond ((eq a 'hack) 'foo) - (t "default")) -@result{} "default" -@end group -@end example - -@noindent -This expression is a @code{cond} which returns @code{foo} if the value -of @code{a} is 1, and returns the string @code{"default"} otherwise. -@end defspec - -Any conditional construct can be expressed with @code{cond} or with -@code{if}. Therefore, the choice between them is a matter of style. -For example: - -@example -@group -(if @var{a} @var{b} @var{c}) -@equiv{} -(cond (@var{a} @var{b}) (t @var{c})) -@end group -@end example - -@node Combining Conditions -@section Constructs for Combining Conditions - - This section describes three constructs that are often used together -with @code{if} and @code{cond} to express complicated conditions. The -constructs @code{and} and @code{or} can also be used individually as -kinds of multiple conditional constructs. - -@defun not condition -This function tests for the falsehood of @var{condition}. It returns -@code{t} if @var{condition} is @code{nil}, and @code{nil} otherwise. -The function @code{not} is identical to @code{null}, and we recommend -using the name @code{null} if you are testing for an empty list. -@end defun - -@defspec and conditions@dots{} -The @code{and} special form tests whether all the @var{conditions} are -true. It works by evaluating the @var{conditions} one by one in the -order written. - -If any of the @var{conditions} evaluates to @code{nil}, then the result -of the @code{and} must be @code{nil} regardless of the remaining -@var{conditions}; so @code{and} returns right away, ignoring the -remaining @var{conditions}. - -If all the @var{conditions} turn out non-@code{nil}, then the value of -the last of them becomes the value of the @code{and} form. - -Here is an example. The first condition returns the integer 1, which is -not @code{nil}. Similarly, the second condition returns the integer 2, -which is not @code{nil}. The third condition is @code{nil}, so the -remaining condition is never evaluated. - -@example -@group -(and (print 1) (print 2) nil (print 3)) - @print{} 1 - @print{} 2 -@result{} nil -@end group -@end example - -Here is a more realistic example of using @code{and}: - -@example -@group -(if (and (consp foo) (eq (car foo) 'x)) - (message "foo is a list starting with x")) -@end group -@end example - -@noindent -Note that @code{(car foo)} is not executed if @code{(consp foo)} returns -@code{nil}, thus avoiding an error. - -@code{and} can be expressed in terms of either @code{if} or @code{cond}. -For example: - -@example -@group -(and @var{arg1} @var{arg2} @var{arg3}) -@equiv{} -(if @var{arg1} (if @var{arg2} @var{arg3})) -@equiv{} -(cond (@var{arg1} (cond (@var{arg2} @var{arg3})))) -@end group -@end example -@end defspec - -@defspec or conditions@dots{} -The @code{or} special form tests whether at least one of the -@var{conditions} is true. It works by evaluating all the -@var{conditions} one by one in the order written. - -If any of the @var{conditions} evaluates to a non-@code{nil} value, then -the result of the @code{or} must be non-@code{nil}; so @code{or} returns -right away, ignoring the remaining @var{conditions}. The value it -returns is the non-@code{nil} value of the condition just evaluated. - -If all the @var{conditions} turn out @code{nil}, then the @code{or} -expression returns @code{nil}. - -For example, this expression tests whether @code{x} is either 0 or -@code{nil}: - -@example -(or (eq x nil) (eq x 0)) -@end example - -Like the @code{and} construct, @code{or} can be written in terms of -@code{cond}. For example: - -@example -@group -(or @var{arg1} @var{arg2} @var{arg3}) -@equiv{} -(cond (@var{arg1}) - (@var{arg2}) - (@var{arg3})) -@end group -@end example - -You could almost write @code{or} in terms of @code{if}, but not quite: - -@example -@group -(if @var{arg1} @var{arg1} - (if @var{arg2} @var{arg2} - @var{arg3})) -@end group -@end example - -@noindent -This is not completely equivalent because it can evaluate @var{arg1} or -@var{arg2} twice. By contrast, @code{(or @var{arg1} @var{arg2} -@var{arg3})} never evaluates any argument more than once. -@end defspec - -@node Iteration -@section Iteration -@cindex iteration -@cindex recursion - - Iteration means executing part of a program repetitively. For -example, you might want to repeat some computation once for each element -of a list, or once for each integer from 0 to @var{n}. You can do this -in Emacs Lisp with the special form @code{while}: - -@defspec while condition forms@dots{} -@code{while} first evaluates @var{condition}. If the result is -non-@code{nil}, it evaluates @var{forms} in textual order. Then it -reevaluates @var{condition}, and if the result is non-@code{nil}, it -evaluates @var{forms} again. This process repeats until @var{condition} -evaluates to @code{nil}. - -There is no limit on the number of iterations that may occur. The loop -will continue until either @var{condition} evaluates to @code{nil} or -until an error or @code{throw} jumps out of it (@pxref{Nonlocal Exits}). - -The value of a @code{while} form is always @code{nil}. - -@example -@group -(setq num 0) - @result{} 0 -@end group -@group -(while (< num 4) - (princ (format "Iteration %d." num)) - (setq num (1+ num))) - @print{} Iteration 0. - @print{} Iteration 1. - @print{} Iteration 2. - @print{} Iteration 3. - @result{} nil -@end group -@end example - -If you would like to execute something on each iteration before the -end-test, put it together with the end-test in a @code{progn} as the -first argument of @code{while}, as shown here: - -@example -@group -(while (progn - (forward-line 1) - (not (looking-at "^$")))) -@end group -@end example - -@noindent -This moves forward one line and continues moving by lines until it -reaches an empty. It is unusual in that the @code{while} has no body, -just the end test (which also does the real work of moving point). -@end defspec - -@node Nonlocal Exits -@section Nonlocal Exits -@cindex nonlocal exits - - A @dfn{nonlocal exit} is a transfer of control from one point in a -program to another remote point. Nonlocal exits can occur in Emacs Lisp -as a result of errors; you can also use them under explicit control. -Nonlocal exits unbind all variable bindings made by the constructs being -exited. - -@menu -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an error happens. -@end menu - -@node Catch and Throw -@subsection Explicit Nonlocal Exits: @code{catch} and @code{throw} - - Most control constructs affect only the flow of control within the -construct itself. The function @code{throw} is the exception to this -rule of normal program execution: it performs a nonlocal exit on -request. (There are other exceptions, but they are for error handling -only.) @code{throw} is used inside a @code{catch}, and jumps back to -that @code{catch}. For example: - -@example -@group -(catch 'foo - (progn - @dots{} - (throw 'foo t) - @dots{})) -@end group -@end example - -@noindent -The @code{throw} transfers control straight back to the corresponding -@code{catch}, which returns immediately. The code following the -@code{throw} is not executed. The second argument of @code{throw} is used -as the return value of the @code{catch}. - - The @code{throw} and the @code{catch} are matched through the first -argument: @code{throw} searches for a @code{catch} whose first argument -is @code{eq} to the one specified. Thus, in the above example, the -@code{throw} specifies @code{foo}, and the @code{catch} specifies the -same symbol, so that @code{catch} is applicable. If there is more than -one applicable @code{catch}, the innermost one takes precedence. - - Executing @code{throw} exits all Lisp constructs up to the matching -@code{catch}, including function calls. When binding constructs such as -@code{let} or function calls are exited in this way, the bindings are -unbound, just as they are when these constructs exit normally -(@pxref{Local Variables}). Likewise, @code{throw} restores the buffer -and position saved by @code{save-excursion} (@pxref{Excursions}), and -the narrowing status saved by @code{save-restriction} and the window -selection saved by @code{save-window-excursion} (@pxref{Window -Configurations}). It also runs any cleanups established with the -@code{unwind-protect} special form when it exits that form -(@pxref{Cleanups}). - - The @code{throw} need not appear lexically within the @code{catch} -that it jumps to. It can equally well be called from another function -called within the @code{catch}. As long as the @code{throw} takes place -chronologically after entry to the @code{catch}, and chronologically -before exit from it, it has access to that @code{catch}. This is why -@code{throw} can be used in commands such as @code{exit-recursive-edit} -that throw back to the editor command loop (@pxref{Recursive Editing}). - -@cindex CL note---only @code{throw} in Emacs -@quotation -@b{Common Lisp note:} Most other versions of Lisp, including Common Lisp, -have several ways of transferring control nonsequentially: @code{return}, -@code{return-from}, and @code{go}, for example. Emacs Lisp has only -@code{throw}. -@end quotation - -@defspec catch tag body@dots{} -@cindex tag on run time stack -@code{catch} establishes a return point for the @code{throw} function. The -return point is distinguished from other such return points by @var{tag}, -which may be any Lisp object. The argument @var{tag} is evaluated normally -before the return point is established. - -With the return point in effect, @code{catch} evaluates the forms of the -@var{body} in textual order. If the forms execute normally, without -error or nonlocal exit, the value of the last body form is returned from -the @code{catch}. - -If a @code{throw} is done within @var{body} specifying the same value -@var{tag}, the @code{catch} exits immediately; the value it returns is -whatever was specified as the second argument of @code{throw}. -@end defspec - -@defun throw tag value -The purpose of @code{throw} is to return from a return point previously -established with @code{catch}. The argument @var{tag} is used to choose -among the various existing return points; it must be @code{eq} to the value -specified in the @code{catch}. If multiple return points match @var{tag}, -the innermost one is used. - -The argument @var{value} is used as the value to return from that -@code{catch}. - -@kindex no-catch -If no return point is in effect with tag @var{tag}, then a @code{no-catch} -error is signaled with data @code{(@var{tag} @var{value})}. -@end defun - -@node Examples of Catch -@subsection Examples of @code{catch} and @code{throw} - - One way to use @code{catch} and @code{throw} is to exit from a doubly -nested loop. (In most languages, this would be done with a ``go to''.) -Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j} -varying from 0 to 9: - -@example -@group -(defun search-foo () - (catch 'loop - (let ((i 0)) - (while (< i 10) - (let ((j 0)) - (while (< j 10) - (if (foo i j) - (throw 'loop (list i j))) - (setq j (1+ j)))) - (setq i (1+ i)))))) -@end group -@end example - -@noindent -If @code{foo} ever returns non-@code{nil}, we stop immediately and return a -list of @var{i} and @var{j}. If @code{foo} always returns @code{nil}, the -@code{catch} returns normally, and the value is @code{nil}, since that -is the result of the @code{while}. - - Here are two tricky examples, slightly different, showing two -return points at once. First, two return points with the same tag, -@code{hack}: - -@example -@group -(defun catch2 (tag) - (catch tag - (throw 'hack 'yes))) -@result{} catch2 -@end group - -@group -(catch 'hack - (print (catch2 'hack)) - 'no) -@print{} yes -@result{} no -@end group -@end example - -@noindent -Since both return points have tags that match the @code{throw}, it goes to -the inner one, the one established in @code{catch2}. Therefore, -@code{catch2} returns normally with value @code{yes}, and this value is -printed. Finally the second body form in the outer @code{catch}, which is -@code{'no}, is evaluated and returned from the outer @code{catch}. - - Now let's change the argument given to @code{catch2}: - -@example -@group -(defun catch2 (tag) - (catch tag - (throw 'hack 'yes))) -@result{} catch2 -@end group - -@group -(catch 'hack - (print (catch2 'quux)) - 'no) -@result{} yes -@end group -@end example - -@noindent -We still have two return points, but this time only the outer one has -the tag @code{hack}; the inner one has the tag @code{quux} instead. -Therefore, @code{throw} makes the outer @code{catch} return the value -@code{yes}. The function @code{print} is never called, and the -body-form @code{'no} is never evaluated. - -@node Errors -@subsection Errors -@cindex errors - - When Emacs Lisp attempts to evaluate a form that, for some reason, -cannot be evaluated, it @dfn{signals} an @dfn{error}. - - When an error is signaled, Emacs's default reaction is to print an -error message and terminate execution of the current command. This is -the right thing to do in most cases, such as if you type @kbd{C-f} at -the end of the buffer. - - In complicated programs, simple termination may not be what you want. -For example, the program may have made temporary changes in data -structures, or created temporary buffers that should be deleted before -the program is finished. In such cases, you would use -@code{unwind-protect} to establish @dfn{cleanup expressions} to be -evaluated in case of error. (@xref{Cleanups}.) Occasionally, you may -wish the program to continue execution despite an error in a subroutine. -In these cases, you would use @code{condition-case} to establish -@dfn{error handlers} to recover control in case of error. - - Resist the temptation to use error handling to transfer control from -one part of the program to another; use @code{catch} and @code{throw} -instead. @xref{Catch and Throw}. - -@menu -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. -@end menu - -@node Signaling Errors -@subsubsection How to Signal an Error -@cindex signaling errors - - Most errors are signaled ``automatically'' within Lisp primitives -which you call for other purposes, such as if you try to take the -@sc{car} of an integer or move forward a character at the end of the -buffer; you can also signal errors explicitly with the functions -@code{error} and @code{signal}. - - Quitting, which happens when the user types @kbd{C-g}, is not -considered an error, but it is handled almost like an error. -@xref{Quitting}. - -@defun error format-string &rest args -This function signals an error with an error message constructed by -applying @code{format} (@pxref{String Conversion}) to -@var{format-string} and @var{args}. - -These examples show typical uses of @code{error}: - -@example -@group -(error "You have committed an error. - Try something else.") - @error{} You have committed an error. - Try something else. -@end group - -@group -(error "You have committed %d errors." 10) - @error{} You have committed 10 errors. -@end group -@end example - -@code{error} works by calling @code{signal} with two arguments: the -error symbol @code{error}, and a list containing the string returned by -@code{format}. - -If you want to use your own string as an error message verbatim, don't -just write @code{(error @var{string})}. If @var{string} contains -@samp{%}, it will be interpreted as a format specifier, with undesirable -results. Instead, use @code{(error "%s" @var{string})}. -@end defun - -@defun signal error-symbol data -This function signals an error named by @var{error-symbol}. The -argument @var{data} is a list of additional Lisp objects relevant to the -circumstances of the error. - -The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol -bearing a property @code{error-conditions} whose value is a list of -condition names. This is how Emacs Lisp classifies different sorts of -errors. - -The number and significance of the objects in @var{data} depends on -@var{error-symbol}. For example, with a @code{wrong-type-arg} error, -there are two objects in the list: a predicate that describes the type -that was expected, and the object that failed to fit that type. -@xref{Error Symbols}, for a description of error symbols. - -Both @var{error-symbol} and @var{data} are available to any error -handlers that handle the error: @code{condition-case} binds a local -variable to a list of the form @code{(@var{error-symbol} .@: -@var{data})} (@pxref{Handling Errors}). If the error is not handled, -these two values are used in printing the error message. - -The function @code{signal} never returns (though in older Emacs versions -it could sometimes return). - -@smallexample -@group -(signal 'wrong-number-of-arguments '(x y)) - @error{} Wrong number of arguments: x, y -@end group - -@group -(signal 'no-such-error '("My unknown error condition.")) - @error{} peculiar error: "My unknown error condition." -@end group -@end smallexample -@end defun - -@cindex CL note---no continuable errors -@quotation -@b{Common Lisp note:} Emacs Lisp has nothing like the Common Lisp -concept of continuable errors. -@end quotation - -@node Processing of Errors -@subsubsection How Emacs Processes Errors - -When an error is signaled, @code{signal} searches for an active -@dfn{handler} for the error. A handler is a sequence of Lisp -expressions designated to be executed if an error happens in part of the -Lisp program. If the error has an applicable handler, the handler is -executed, and control resumes following the handler. The handler -executes in the environment of the @code{condition-case} that -established it; all functions called within that @code{condition-case} -have already been exited, and the handler cannot return to them. - -If there is no applicable handler for the error, the current command is -terminated and control returns to the editor command loop, because the -command loop has an implicit handler for all kinds of errors. The -command loop's handler uses the error symbol and associated data to -print an error message. - -@cindex @code{debug-on-error} use -An error that has no explicit handler may call the Lisp debugger. The -debugger is enabled if the variable @code{debug-on-error} (@pxref{Error -Debugging}) is non-@code{nil}. Unlike error handlers, the debugger runs -in the environment of the error, so that you can examine values of -variables precisely as they were at the time of the error. - -@node Handling Errors -@subsubsection Writing Code to Handle Errors -@cindex error handler -@cindex handling errors - - The usual effect of signaling an error is to terminate the command -that is running and return immediately to the Emacs editor command loop. -You can arrange to trap errors occurring in a part of your program by -establishing an error handler, with the special form -@code{condition-case}. A simple example looks like this: - -@example -@group -(condition-case nil - (delete-file filename) - (error nil)) -@end group -@end example - -@noindent -This deletes the file named @var{filename}, catching any error and -returning @code{nil} if an error occurs. - - The second argument of @code{condition-case} is called the -@dfn{protected form}. (In the example above, the protected form is a -call to @code{delete-file}.) The error handlers go into effect when -this form begins execution and are deactivated when this form returns. -They remain in effect for all the intervening time. In particular, they -are in effect during the execution of functions called by this form, in -their subroutines, and so on. This is a good thing, since, strictly -speaking, errors can be signaled only by Lisp primitives (including -@code{signal} and @code{error}) called by the protected form, not by the -protected form itself. - - The arguments after the protected form are handlers. Each handler -lists one or more @dfn{condition names} (which are symbols) to specify -which errors it will handle. The error symbol specified when an error -is signaled also defines a list of condition names. A handler applies -to an error if they have any condition names in common. In the example -above, there is one handler, and it specifies one condition name, -@code{error}, which covers all errors. - - The search for an applicable handler checks all the established handlers -starting with the most recently established one. Thus, if two nested -@code{condition-case} forms offer to handle the same error, the inner of -the two will actually handle it. - - When an error is handled, control returns to the handler. Before this -happens, Emacs unbinds all variable bindings made by binding constructs -that are being exited and executes the cleanups of all -@code{unwind-protect} forms that are exited. Once control arrives at -the handler, the body of the handler is executed. - - After execution of the handler body, execution returns from the -@code{condition-case} form. Because the protected form is exited -completely before execution of the handler, the handler cannot resume -execution at the point of the error, nor can it examine variable -bindings that were made within the protected form. All it can do is -clean up and proceed. - - @code{condition-case} is often used to trap errors that are -predictable, such as failure to open a file in a call to -@code{insert-file-contents}. It is also used to trap errors that are -totally unpredictable, such as when the program evaluates an expression -read from the user. - - Error signaling and handling have some resemblance to @code{throw} and -@code{catch}, but they are entirely separate facilities. An error -cannot be caught by a @code{catch}, and a @code{throw} cannot be handled -by an error handler (though using @code{throw} when there is no suitable -@code{catch} signals an error that can be handled). - -@defspec condition-case var protected-form handlers@dots{} -This special form establishes the error handlers @var{handlers} around -the execution of @var{protected-form}. If @var{protected-form} executes -without error, the value it returns becomes the value of the -@code{condition-case} form; in this case, the @code{condition-case} has -no effect. The @code{condition-case} form makes a difference when an -error occurs during @var{protected-form}. - -Each of the @var{handlers} is a list of the form @code{(@var{conditions} -@var{body}@dots{})}. Here @var{conditions} is an error condition name -to be handled, or a list of condition names; @var{body} is one or more -Lisp expressions to be executed when this handler handles an error. -Here are examples of handlers: - -@smallexample -@group -(error nil) - -(arith-error (message "Division by zero")) - -((arith-error file-error) - (message - "Either division by zero or failure to open a file")) -@end group -@end smallexample - -Each error that occurs has an @dfn{error symbol} that describes what -kind of error it is. The @code{error-conditions} property of this -symbol is a list of condition names (@pxref{Error Symbols}). Emacs -searches all the active @code{condition-case} forms for a handler that -specifies one or more of these condition names; the innermost matching -@code{condition-case} handles the error. Within this -@code{condition-case}, the first applicable handler handles the error. - -After executing the body of the handler, the @code{condition-case} -returns normally, using the value of the last form in the handler body -as the overall value. - -@cindex error description -The argument @var{var} is a variable. @code{condition-case} does not -bind this variable when executing the @var{protected-form}, only when it -handles an error. At that time, it binds @var{var} locally to an -@dfn{error description}, which is a list giving the particulars of the -error. The error description has the form @code{(@var{error-symbol} -. @var{data})}. The handler can refer to this list to decide what to -do. For example, if the error is for failure opening a file, the file -name is the second element of @var{data}---the third element of the -error description. - -If @var{var} is @code{nil}, that means no variable is bound. Then the -error symbol and associated data are not available to the handler. -@end defspec - -@defun error-message-string error-description -This function returns the error message string for a given error -descriptor. It is useful if you want to handle an error by printing the -usual error message for that error. -@end defun - -@cindex @code{arith-error} example -Here is an example of using @code{condition-case} to handle the error -that results from dividing by zero. The handler displays the error -message (but without a beep), then returns a very large number. - -@smallexample -@group -(defun safe-divide (dividend divisor) - (condition-case err - ;; @r{Protected form.} - (/ dividend divisor) - ;; @r{The handler.} - (arith-error ; @r{Condition.} - ;; @r{Display the usual message for this error.} - (message "%s" (error-message-string err)) - 1000000))) -@result{} safe-divide -@end group - -@group -(safe-divide 5 0) - @print{} Arithmetic error: (arith-error) -@result{} 1000000 -@end group -@end smallexample - -@noindent -The handler specifies condition name @code{arith-error} so that it will handle only division-by-zero errors. Other kinds of errors will not be handled, at least not by this @code{condition-case}. Thus, - -@smallexample -@group -(safe-divide nil 3) - @error{} Wrong type argument: integer-or-marker-p, nil -@end group -@end smallexample - - Here is a @code{condition-case} that catches all kinds of errors, -including those signaled with @code{error}: - -@smallexample -@group -(setq baz 34) - @result{} 34 -@end group - -@group -(condition-case err - (if (eq baz 35) - t - ;; @r{This is a call to the function @code{error}.} - (error "Rats! The variable %s was %s, not 35" 'baz baz)) - ;; @r{This is the handler; it is not a form.} - (error (princ (format "The error was: %s" err)) - 2)) -@print{} The error was: (error "Rats! The variable baz was 34, not 35") -@result{} 2 -@end group -@end smallexample - -@node Error Symbols -@subsubsection Error Symbols and Condition Names -@cindex error symbol -@cindex error name -@cindex condition name -@cindex user-defined error -@kindex error-conditions - - When you signal an error, you specify an @dfn{error symbol} to specify -the kind of error you have in mind. Each error has one and only one -error symbol to categorize it. This is the finest classification of -errors defined by the Emacs Lisp language. - - These narrow classifications are grouped into a hierarchy of wider -classes called @dfn{error conditions}, identified by @dfn{condition -names}. The narrowest such classes belong to the error symbols -themselves: each error symbol is also a condition name. There are also -condition names for more extensive classes, up to the condition name -@code{error} which takes in all kinds of errors. Thus, each error has -one or more condition names: @code{error}, the error symbol if that -is distinct from @code{error}, and perhaps some intermediate -classifications. - - In order for a symbol to be an error symbol, it must have an -@code{error-conditions} property which gives a list of condition names. -This list defines the conditions that this kind of error belongs to. -(The error symbol itself, and the symbol @code{error}, should always be -members of this list.) Thus, the hierarchy of condition names is -defined by the @code{error-conditions} properties of the error symbols. - - In addition to the @code{error-conditions} list, the error symbol -should have an @code{error-message} property whose value is a string to -be printed when that error is signaled but not handled. If the -@code{error-message} property exists, but is not a string, the error -message @samp{peculiar error} is used. -@cindex peculiar error - - Here is how we define a new error symbol, @code{new-error}: - -@example -@group -(put 'new-error - 'error-conditions - '(error my-own-errors new-error)) -@result{} (error my-own-errors new-error) -@end group -@group -(put 'new-error 'error-message "A new error") -@result{} "A new error" -@end group -@end example - -@noindent -This error has three condition names: @code{new-error}, the narrowest -classification; @code{my-own-errors}, which we imagine is a wider -classification; and @code{error}, which is the widest of all. - - The error string should start with a capital letter but it should -not end with a period. This is for consistency with the rest of Emacs. - - Naturally, Emacs will never signal @code{new-error} on its own; only -an explicit call to @code{signal} (@pxref{Signaling Errors}) in your -code can do this: - -@example -@group -(signal 'new-error '(x y)) - @error{} A new error: x, y -@end group -@end example - - This error can be handled through any of the three condition names. -This example handles @code{new-error} and any other errors in the class -@code{my-own-errors}: - -@example -@group -(condition-case foo - (bar nil t) - (my-own-errors nil)) -@end group -@end example - - The significant way that errors are classified is by their condition -names---the names used to match errors with handlers. An error symbol -serves only as a convenient way to specify the intended error message -and list of condition names. It would be cumbersome to give -@code{signal} a list of condition names rather than one error symbol. - - By contrast, using only error symbols without condition names would -seriously decrease the power of @code{condition-case}. Condition names -make it possible to categorize errors at various levels of generality -when you write an error handler. Using error symbols alone would -eliminate all but the narrowest level of classification. - - @xref{Standard Errors}, for a list of all the standard error symbols -and their conditions. - -@node Cleanups -@subsection Cleaning Up from Nonlocal Exits - - The @code{unwind-protect} construct is essential whenever you -temporarily put a data structure in an inconsistent state; it permits -you to ensure the data are consistent in the event of an error or throw. - -@defspec unwind-protect body cleanup-forms@dots{} -@cindex cleanup forms -@cindex protected forms -@cindex error cleanup -@cindex unwinding -@code{unwind-protect} executes the @var{body} with a guarantee that the -@var{cleanup-forms} will be evaluated if control leaves @var{body}, no -matter how that happens. The @var{body} may complete normally, or -execute a @code{throw} out of the @code{unwind-protect}, or cause an -error; in all cases, the @var{cleanup-forms} will be evaluated. - -If the @var{body} forms finish normally, @code{unwind-protect} returns -the value of the last @var{body} form, after it evaluates the -@var{cleanup-forms}. If the @var{body} forms do not finish, -@code{unwind-protect} does not return any value in the normal sense. - -Only the @var{body} is actually protected by the @code{unwind-protect}. -If any of the @var{cleanup-forms} themselves exits nonlocally (e.g., via -a @code{throw} or an error), @code{unwind-protect} is @emph{not} -guaranteed to evaluate the rest of them. If the failure of one of the -@var{cleanup-forms} has the potential to cause trouble, then protect it -with another @code{unwind-protect} around that form. - -The number of currently active @code{unwind-protect} forms counts, -together with the number of local variable bindings, against the limit -@code{max-specpdl-size} (@pxref{Local Variables}). -@end defspec - - For example, here we make an invisible buffer for temporary use, and -make sure to kill it before finishing: - -@smallexample -@group -(save-excursion - (let ((buffer (get-buffer-create " *temp*"))) - (set-buffer buffer) - (unwind-protect - @var{body} - (kill-buffer buffer)))) -@end group -@end smallexample - -@noindent -You might think that we could just as well write @code{(kill-buffer -(current-buffer))} and dispense with the variable @code{buffer}. -However, the way shown above is safer, if @var{body} happens to get an -error after switching to a different buffer! (Alternatively, you could -write another @code{save-excursion} around the body, to ensure that the -temporary buffer becomes current in time to kill it.) - -@findex ftp-login - Here is an actual example taken from the file @file{ftp.el}. It -creates a process (@pxref{Processes}) to try to establish a connection -to a remote machine. As the function @code{ftp-login} is highly -susceptible to numerous problems that the writer of the function cannot -anticipate, it is protected with a form that guarantees deletion of the -process in the event of failure. Otherwise, Emacs might fill up with -useless subprocesses. - -@smallexample -@group -(let ((win nil)) - (unwind-protect - (progn - (setq process (ftp-setup-buffer host file)) - (if (setq win (ftp-login process host user password)) - (message "Logged in") - (error "Ftp login failed"))) - (or win (and process (delete-process process))))) -@end group -@end smallexample - - This example actually has a small bug: if the user types @kbd{C-g} to -quit, and the quit happens immediately after the function -@code{ftp-setup-buffer} returns but before the variable @code{process} is -set, the process will not be killed. There is no easy way to fix this bug, -but at least it is very unlikely. - - Here is another example which uses @code{unwind-protect} to make sure -to kill a temporary buffer. In this example, the value returned by -@code{unwind-protect} is used. - -@smallexample -(defun shell-command-string (cmd) - "Return the output of the shell command CMD, as a string." - (save-excursion - (set-buffer (generate-new-buffer " OS*cmd")) - (shell-command cmd t) - (unwind-protect - (buffer-string) - (kill-buffer (current-buffer))))) -@end smallexample diff --git a/lispref/debugging.texi b/lispref/debugging.texi deleted file mode 100644 index b045d93b94e..00000000000 --- a/lispref/debugging.texi +++ /dev/null @@ -1,724 +0,0 @@ -@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, Read and Print, 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 an 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. - -When this variable is non-@code{nil}, Emacs does not catch errors that -happen in process filter functions and sentinels. Therefore, these -errors also can invoke the debugger. @xref{Processes}. -@end defopt - -@defopt debug-ignored-errors -This variable specifies certain kinds of errors that should not enter -the debugger. Its value is a list of error condition symbols and/or -regular expressions. If the error has any of those condition symbols, -or if the error message matches any of the regular expressions, then -that error does not enter the debugger, regardless of the value of -@code{debug-on-error}. - -The normal value of this variable lists several errors that happen often -during editing but rarely result from bugs in Lisp programs. -@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 and -inhibits use of @code{condition-case} to catch init file errors. - - If your @file{.emacs} file sets @code{debug-on-error}, the effect may -not last past the end of loading @file{.emacs}. (This is an undesirable -byproduct of the code that implements the @samp{-debug-init} command -line option.) The best way to make @file{.emacs} set -@code{debug-on-error} permanently is with @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}. Likewise, @code{debug-on-quit} has no effect on -errors. - - 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. - - @strong{Note:} 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) -@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 @var{function-name} is -@code{nil} or the empty string, it cancels debugging for all functions. - -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 -of @code{(debug)} 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 backtrace buffer shows 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, and the current buffer, 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-:} 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 is useful 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. It -is also useful if you call @code{debug} and use its return value. -Otherwise, @kbd{r} has the same effect as @kbd{c}, and the specified -return value does not matter. - -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{debug} displays the rest of its arguments at 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 - -@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 down the stack, 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. - -This function is used only by the debugger. -@end defun - -@defvar command-debug-status -This variable records the debugging status of the 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, for the debugger, of using this variable rather than -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 the -@sc{car} of the 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 @var{frame-number} 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} with @kbd{C-_}, 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, back up over it, 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} with @kbd{C-_}, 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 Compilation Errors, Edebug, Syntax Errors, Debugging -@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, this technique can't localize the error precisely, but can still -show you which function to check. - -@include edebug.texi diff --git a/lispref/display.texi b/lispref/display.texi deleted file mode 100644 index ae91f450924..00000000000 --- a/lispref/display.texi +++ /dev/null @@ -1,1464 +0,0 @@ -@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/display -@node Display, Calendar, System Interface, Top -@chapter Emacs Display - - This chapter describes a number of features related to the display -that Emacs presents to the user. - -@menu -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Screen Size:: How big is the Emacs screen. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Where messages are displayed. -* Invisible Text:: Hiding part of the buffer text. -* Selective Display:: Hiding part of the buffer text (the old way). -* Overlay Arrow:: Display of an arrow to indicate position. -* Temporary Displays:: Displays that go away automatically. -* Overlays:: Use overlays to highlight parts of the buffer. -* Faces:: A face defines a graphics appearance: font, color, etc. -* Blinking:: How Emacs shows the matching open parenthesis. -* Inverse Video:: Specifying how the screen looks. -* Usual Display:: The usual conventions for displaying nonprinting chars. -* Display Tables:: How to specify other conventions. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. -@end menu - -@node Refresh Screen -@section Refreshing the Screen - -The function @code{redraw-frame} redisplays the entire contents of a -given frame. @xref{Frames}. - -@c Emacs 19 feature -@defun redraw-frame frame -This function clears and redisplays frame @var{frame}. -@end defun - -Even more powerful is @code{redraw-display}: - -@deffn Command redraw-display -This function clears and redisplays all visible frames. -@end deffn - - Processing user input takes absolute priority over redisplay. If you -call these functions when input is available, they do nothing -immediately, but a full redisplay does happen eventually---after all the -input has been processed. - - Normally, suspending and resuming Emacs also refreshes the screen. -Some terminal emulators record separate contents for display-oriented -programs such as Emacs and for ordinary sequential display. If you are -using such a terminal, you might want to inhibit the redisplay on -resumption. - -@defvar no-redraw-on-reenter -@cindex suspend (cf. @code{no-redraw-on-reenter}) -@cindex resume (cf. @code{no-redraw-on-reenter}) -This variable controls whether Emacs redraws the entire screen after it -has been suspended and resumed. Non-@code{nil} means yes, @code{nil} -means no. -@end defvar - -@node Screen Size -@section Screen Size -@cindex size of screen -@cindex screen size -@cindex display lines -@cindex display columns -@cindex resize redisplay - - The screen size functions access or specify the height or width of -the terminal. When you are using multiple frames, they apply to the -selected frame (@pxref{Frames}). - -@defun screen-height -This function returns the number of lines on the screen that are -available for display. - -@example -@group -(screen-height) - @result{} 50 -@end group -@end example -@end defun - -@defun screen-width -This function returns the number of columns on the screen that are -available for display. - -@example -@group -(screen-width) - @result{} 80 -@end group -@end example -@end defun - -@defun set-screen-height lines &optional not-actual-size -This function declares that the terminal can display @var{lines} lines. -The sizes of existing windows are altered proportionally to fit. - -If @var{not-actual-size} is non-@code{nil}, then Emacs displays -@var{lines} lines of output, but does not change its value for the -actual height of the screen. (Knowing the correct actual size may be -necessary for correct cursor positioning.) Using a smaller height than -the terminal actually implements may be useful to reproduce behavior -observed on a smaller screen, or if the terminal malfunctions when using -its whole screen. - -If @var{lines} is different from what it was previously, then the -entire screen is cleared and redisplayed using the new size. - -This function returns @code{nil}. -@end defun - -@defun set-screen-width columns &optional not-actual-size -This function declares that the terminal can display @var{columns} -columns. The details are as in @code{set-screen-height}. -@end defun - -@node Truncation -@section Truncation -@cindex line wrapping -@cindex continuation lines -@cindex @samp{$} in display -@cindex @samp{\} in display - - When a line of text extends beyond the right edge of a window, the -line can either be continued on the next screen line, or truncated to -one screen line. The additional screen lines used to display a long -text line are called @dfn{continuation} lines. Normally, a @samp{$} in -the rightmost column of the window indicates truncation; a @samp{\} on -the rightmost column indicates a line that ``wraps'' or is continued -onto the next line. (The display table can specify alternative -indicators; see @ref{Display Tables}.) - - Note that continuation is different from filling; continuation happens -on the screen only, not in the buffer contents, and it breaks a line -precisely at the right margin, not at a word boundary. @xref{Filling}. - -@defopt truncate-lines -This buffer-local variable controls how Emacs displays lines that extend -beyond the right edge of the window. The default is @code{nil}, which -specifies continuation. If the value is non-@code{nil}, then these -lines are truncated. - -If the variable @code{truncate-partial-width-windows} is non-@code{nil}, -then truncation is always used for side-by-side windows (within one -frame) regardless of the value of @code{truncate-lines}. -@end defopt - -@defopt default-truncate-lines -This variable is the default value for @code{truncate-lines}, for -buffers that do not have local values for it. -@end defopt - -@defopt truncate-partial-width-windows -This variable controls display of lines that extend beyond the right -edge of the window, in side-by-side windows (@pxref{Splitting Windows}). -If it is non-@code{nil}, these lines are truncated; otherwise, -@code{truncate-lines} says what to do with them. -@end defopt - - You can override the images that indicate continuation or truncation -with the display table; see @ref{Display Tables}. - - If your buffer contains @strong{very} long lines, and you use -continuation to display them, just thinking about them can make Emacs -redisplay slow. The column computation and indentation functions also -become slow. Then you might find it advisable to set -@code{cache-long-line-scans} to @code{t}. - -@defvar cache-long-line-scans -If this variable is non-@code{nil}, various indentation and motion -functions, and Emacs redisplay, cache the results of scanning the -buffer, and consult the cache to avoid rescanning regions of the buffer -unless they are modified. - -Turning on the cache slows down processing of short lines somewhat. - -This variable is automatically local in every buffer. -@end defvar - -@node The Echo Area -@section The Echo Area -@cindex error display -@cindex echo area - -The @dfn{echo area} is used for displaying messages made with the -@code{message} primitive, and for echoing keystrokes. It is not the -same as the minibuffer, despite the fact that the minibuffer appears -(when active) in the same place on the screen as the echo area. The -@cite{GNU Emacs Manual} specifies the rules for resolving conflicts -between the echo area and the minibuffer for use of that screen space -(@pxref{Minibuffer,, The Minibuffer, emacs, The GNU Emacs Manual}). -Error messages appear in the echo area; see @ref{Errors}. - -You can write output in the echo area by using the Lisp printing -functions with @code{t} as the stream (@pxref{Output Functions}), or as -follows: - -@defun message string &rest arguments -This function displays a one-line message in the echo area. The -argument @var{string} is similar to a C language @code{printf} control -string. See @code{format} in @ref{String Conversion}, for the details -on the conversion specifications. @code{message} returns the -constructed string. - -In batch mode, @code{message} prints the message text on the standard -error stream, followed by a newline. - -@c Emacs 19 feature -If @var{string} is @code{nil}, @code{message} clears the echo area. If -the minibuffer is active, this brings the minibuffer contents back onto -the screen immediately. - -@example -@group -(message "Minibuffer depth is %d." - (minibuffer-depth)) - @print{} Minibuffer depth is 0. -@result{} "Minibuffer depth is 0." -@end group - -@group ----------- Echo Area ---------- -Minibuffer depth is 0. ----------- Echo Area ---------- -@end group -@end example -@end defun - -Almost all the messages displayed in the echo area are also recorded -in the @samp{*Messages*} buffer. - -@defopt message-log-max -This variable specifies how many lines to keep in the @samp{*Messages*} -buffer. The value @code{t} means there is no limit on how many lines to -keep. The value @code{nil} disables message logging entirely. Here's -how to display a message and prevent it from being logged: - -@example -(let (message-log-max) - (message @dots{})) -@end example -@end defopt - -@defvar echo-keystrokes -This variable determines how much time should elapse before command -characters echo. Its value must be an integer, which specifies the -number of seconds to wait before echoing. If the user types a prefix -key (such as @kbd{C-x}) and then delays this many seconds before -continuing, the prefix key is echoed in the echo area. Any subsequent -characters in the same command will be echoed as well. - -If the value is zero, then command input is not echoed. -@end defvar - -@defvar cursor-in-echo-area -This variable controls where the cursor appears when a message is -displayed in the echo area. If it is non-@code{nil}, then the cursor -appears at the end of the message. Otherwise, the cursor appears at -point---not in the echo area at all. - -The value is normally @code{nil}; Lisp programs bind it to @code{t} -for brief periods of time. -@end defvar - -@node Invisible Text -@section Invisible Text - -@cindex invisible text -You can make characters @dfn{invisible}, so that they do not appear on -the screen, with the @code{invisible} property. This can be either a -text property or a property of an overlay. - -In the simplest case, any non-@code{nil} @code{invisible} property makes -a character invisible. This is the default case---if you don't alter -the default value of @code{buffer-invisibility-spec}, this is how the -@code{invisibility} property works. This feature is much like selective -display (@pxref{Selective Display}), but more general and cleaner. - -More generally, you can use the variable @code{buffer-invisibility-spec} -to control which values of the @code{invisible} property make text -invisible. This permits you to classify the text into different subsets -in advance, by giving them different @code{invisible} values, and -subsequently make various subsets visible or invisible by changing the -value of @code{buffer-invisibility-spec}. - -Controlling visibility with @code{buffer-invisibility-spec} is -especially useful in a program to display the list of entries in a data -base. It permits the implementation of convenient filtering commands to -view just a part of the entries in the data base. Setting this variable -is very fast, much faster than scanning all the text in the buffer -looking for properties to change. - -@defvar buffer-invisibility-spec -This variable specifies which kinds of @code{invisible} properties -actually make a character invisible. - -@table @asis -@item @code{t} -A character is invisible if its @code{invisible} property is -non-@code{nil}. This is the default. - -@item a list -Each element of the list makes certain characters invisible. -Ultimately, a character is invisible if any of the elements of this list -applies to it. The list can have two kinds of elements: - -@table @code -@item @var{atom} -A character is invisible if its @code{invisible} propery value -is @var{atom} or if it is a list with @var{atom} as a member. - -@item (@var{atom} . t) -A character is invisible if its @code{invisible} propery value -is @var{atom} or if it is a list with @var{atom} as a member. -Moreover, if this character is at the end of a line and is followed -by a visible newline, it displays an ellipsis. -@end table -@end table -@end defvar - -@vindex line-move-ignore-invisible - Ordinarily, commands that operate on text or move point do not care -whether the text is invisible. The user-level line motion commands -explicitly ignore invisible newlines if -@code{line-move-ignore-invisible} is non-@code{nil}, but only because -they are explicitly programmed to do so. - -@node Selective Display -@section Selective Display -@cindex selective display - - @dfn{Selective display} is a pair of features that hide certain -lines on the screen. - - The first variant, explicit selective display, is designed for use in -a Lisp program. The program controls which lines are hidden by altering -the text. Outline mode has traditionally used this variant. It has -been partially replaced by the invisible text feature (@pxref{Invisible -Text}); there is a new version of Outline mode which uses that instead. - - In the second variant, the choice of lines to hide is made -automatically based on indentation. This variant is designed to be a -user-level feature. - - The way you control explicit selective display is by replacing a -newline (control-j) with a carriage return (control-m). The text that -was formerly a line following that newline is now invisible. Strictly -speaking, it is temporarily no longer a line at all, since only newlines -can separate lines; it is now part of the previous line. - - Selective display does not directly affect editing commands. For -example, @kbd{C-f} (@code{forward-char}) moves point unhesitatingly into -invisible text. However, the replacement of newline characters with -carriage return characters affects some editing commands. For example, -@code{next-line} skips invisible lines, since it searches only for -newlines. Modes that use selective display can also define commands -that take account of the newlines, or that make parts of the text -visible or invisible. - - When you write a selectively displayed buffer into a file, all the -control-m's are output as newlines. This means that when you next read -in the file, it looks OK, with nothing invisible. The selective display -effect is seen only within Emacs. - -@defvar selective-display -This buffer-local variable enables selective display. This means that -lines, or portions of lines, may be made invisible. - -@itemize @bullet -@item -If the value of @code{selective-display} is @code{t}, then any portion -of a line that follows a control-m is not displayed. - -@item -If the value of @code{selective-display} is a positive integer, then -lines that start with more than that many columns of indentation are not -displayed. -@end itemize - -When some portion of a buffer is invisible, the vertical movement -commands operate as if that portion did not exist, allowing a single -@code{next-line} command to skip any number of invisible lines. -However, character movement commands (such as @code{forward-char}) do -not skip the invisible portion, and it is possible (if tricky) to insert -or delete text in an invisible portion. - -In the examples below, we show the @emph{display appearance} of the -buffer @code{foo}, which changes with the value of -@code{selective-display}. The @emph{contents} of the buffer do not -change. - -@example -@group -(setq selective-display nil) - @result{} nil - ----------- Buffer: foo ---------- -1 on this column - 2on this column - 3n this column - 3n this column - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group - -@group -(setq selective-display 2) - @result{} 2 - ----------- Buffer: foo ---------- -1 on this column - 2on this column - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group -@end example -@end defvar - -@defvar selective-display-ellipses -If this buffer-local variable is non-@code{nil}, then Emacs displays -@samp{@dots{}} at the end of a line that is followed by invisible text. -This example is a continuation of the previous one. - -@example -@group -(setq selective-display-ellipses t) - @result{} t - ----------- Buffer: foo ---------- -1 on this column - 2on this column ... - 2on this column -1 on this column ----------- Buffer: foo ---------- -@end group -@end example - -You can use a display table to substitute other text for the ellipsis -(@samp{@dots{}}). @xref{Display Tables}. -@end defvar - -@node Overlay Arrow -@section The Overlay Arrow -@cindex overlay arrow - - The @dfn{overlay arrow} is useful for directing the user's attention -to a particular line in a buffer. For example, in the modes used for -interface to debuggers, the overlay arrow indicates the line of code -about to be executed. - -@defvar overlay-arrow-string -This variable holds the string to display to call attention to a -particular line, or @code{nil} if the arrow feature is not in use. -@end defvar - -@defvar overlay-arrow-position -This variable holds a marker that indicates where to display the overlay -arrow. It should point at the beginning of a line. The arrow text -appears at the beginning of that line, overlaying any text that would -otherwise appear. Since the arrow is usually short, and the line -usually begins with indentation, normally nothing significant is -overwritten. - -The overlay string is displayed only in the buffer that this marker -points into. Thus, only one buffer can have an overlay arrow at any -given time. -@c !!! overlay-arrow-position: but the overlay string may remain in the display -@c of some other buffer until an update is required. This should be fixed -@c now. Is it? -@end defvar - - You can do the same job by creating an overlay with a -@code{before-string} property. @xref{Overlay Properties}. - -@node Temporary Displays -@section Temporary Displays - - Temporary displays are used by commands to put output into a buffer -and then present it to the user for perusal rather than for editing. -Many of the help commands use this feature. - -@defspec with-output-to-temp-buffer buffer-name forms@dots{} -This function executes @var{forms} while arranging to insert any -output they print into the buffer named @var{buffer-name}. The buffer -is then shown in some window for viewing, displayed but not selected. - -The string @var{buffer-name} specifies the temporary buffer, which -need not already exist. The argument must be a string, not a buffer. -The buffer is erased initially (with no questions asked), and it is -marked as unmodified after @code{with-output-to-temp-buffer} exits. - -@code{with-output-to-temp-buffer} binds @code{standard-output} to the -temporary buffer, then it evaluates the forms in @var{forms}. Output -using the Lisp output functions within @var{forms} goes by default to -that buffer (but screen display and messages in the echo area, although -they are ``output'' in the general sense of the word, are not affected). -@xref{Output Functions}. - -The value of the last form in @var{forms} is returned. - -@example -@group ----------- Buffer: foo ---------- - This is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(with-output-to-temp-buffer "foo" - (print 20) - (print standard-output)) -@result{} #<buffer foo> - ----------- Buffer: foo ---------- -20 - -#<buffer foo> - ----------- Buffer: foo ---------- -@end group -@end example -@end defspec - -@defvar temp-buffer-show-function -If this variable is non-@code{nil}, @code{with-output-to-temp-buffer} -calls it as a function to do the job of displaying a help buffer. The -function gets one argument, which is the buffer it should display. - -In Emacs versions 18 and earlier, this variable was called -@code{temp-buffer-show-hook}. -@end defvar - -@defun momentary-string-display string position &optional char message -This function momentarily displays @var{string} in the current buffer at -@var{position}. It has no effect on the undo list or on the buffer's -modification status. - -The momentary display remains until the next input event. If the next -input event is @var{char}, @code{momentary-string-display} ignores it -and returns. Otherwise, that event remains buffered for subsequent use -as input. Thus, typing @var{char} will simply remove the string from -the display, while typing (say) @kbd{C-f} will remove the string from -the display and later (presumably) move point forward. The argument -@var{char} is a space by default. - -The return value of @code{momentary-string-display} is not meaningful. - -If the string @var{string} does not contain control characters, you can -do the same job in a more general way by creating an overlay with a -@code{before-string} property. @xref{Overlay Properties}. - -If @var{message} is non-@code{nil}, it is displayed in the echo area -while @var{string} is displayed in the buffer. If it is @code{nil}, a -default message says to type @var{char} to continue. - -In this example, point is initially located at the beginning of the -second line: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of foo. -@point{}Second line. ----------- Buffer: foo ---------- -@end group - -@group -(momentary-string-display - "**** Important Message! ****" - (point) ?\r - "Type RET when done reading") -@result{} t -@end group - -@group ----------- Buffer: foo ---------- -This is the contents of foo. -**** Important Message! ****Second line. ----------- Buffer: foo ---------- - ----------- Echo Area ---------- -Type RET when done reading ----------- Echo Area ---------- -@end group -@end example -@end defun - -@node Overlays -@section Overlays -@cindex overlays - -You can use @dfn{overlays} to alter the appearance of a buffer's text on -the screen, for the sake of presentation features. An overlay is an -object that belongs to a particular buffer, and has a specified -beginning and end. It also has properties that you can examine and set; -these affect the display of the text within the overlay. - -@menu -* Overlay Properties:: How to read and set properties. - What properties do to the screen display. -* Managing Overlays:: Creating, moving, finding overlays. -@end menu - -@node Overlay Properties -@subsection Overlay Properties - -Overlay properties are like text properties in some respects, but the -differences are more important than the similarities. Text properties -are considered a part of the text; overlays are specifically considered -not to be part of the text. Thus, copying text between various buffers -and strings preserves text properties, but does not try to preserve -overlays. Changing a buffer's text properties marks the buffer as -modified, while moving an overlay or changing its properties does not. -Unlike text propery changes, overlay changes are not recorded in the -buffer's undo list. - -@table @code -@item priority -@kindex priority @r{(overlay property)} -This property's value (which should be a nonnegative number) determines -the priority of the overlay. The priority matters when two or more -overlays cover the same character and both specify a face for display; -the one whose @code{priority} value is larger takes priority over the -other, and its face attributes override the face attributes of the lower -priority overlay. - -Currently, all overlays take priority over text properties. Please -avoid using negative priority values, as we have not yet decided just -what they should mean. - -@item window -@kindex window @r{(overlay property)} -If the @code{window} property is non-@code{nil}, then the overlay -applies only on that window. - -@item category -@kindex category @r{(overlay property)} -If an overlay has a @code{category} property, we call it the -@dfn{category} of the overlay. It should be a symbol. The properties -of the symbol serve as defaults for the properties of the overlay. - -@item face -@kindex face @r{(overlay property)} -This property controls the font and color of text. Its value is a face -name or a list of face names. @xref{Faces}, for more information. This -feature may be temporary; in the future, we may replace it with other -ways of specifying how to display text. - -@item mouse-face -@kindex mouse-face @r{(overlay property)} -This property is used instead of @code{face} when the mouse is within -the range of the overlay. This feature may be temporary, like -@code{face}. - -@item modification-hooks -@kindex modification-hooks @r{(overlay property)} -This property's value is a list of functions to be called if any -character within the overlay is changed or if text is inserted strictly -within the overlay. - -The hook functions are called both before and after each change. -If the functions save the information they receive, and compare notes -between calls, they can determine exactly what change has been made -in the buffer text. - -When called before a change, each function receives four arguments: the -overlay, @code{nil}, and the beginning and end of the text range to be -modified. - -When called after a change, each function receives five arguments: the -overlay, @code{t}, the beginning and end of the text range just -modified, and the length of the pre-change text replaced by that range. -(For an insertion, the pre-change length is zero; for a deletion, that -length is the number of characters deleted, and the post-change -beginning and end are equal.) - -@item insert-in-front-hooks -@kindex insert-in-front-hooks @r{(overlay property)} -This property's value is a list of functions to be called before and -after inserting text right at the beginning of the overlay. The calling -conventions are the same as for the @code{modification-hooks} functions. - -@item insert-behind-hooks -@kindex insert-behind-hooks @r{(overlay property)} -This property's value is a list of functions to be called before and -after inserting text right at the end of the overlay. The calling -conventions are the same as for the @code{modification-hooks} functions. - -@item invisible -@kindex invisible @r{(overlay property)} -The @code{invisible} property can make the text in the overlay -invisible, which means that it does not appear on the screen. -@xref{Invisible Text}, for details. - -@ignore This isn't implemented yet -@item intangible -@kindex intangible @r{(overlay property)} -The @code{intangible} property on an overlay works just like the -@code{intangible} text property. @xref{Special Properties}, for details. -@end ignore - -@item before-string -@kindex before-string @r{(overlay property)} -This property's value is a string to add to the display at the beginning -of the overlay. The string does not appear in the buffer in any -sense---only on the screen. The string should contain only characters -that display as a single column---control characters, including tabs or -newlines, will give strange results. - -@item after-string -@kindex after-string @r{(overlay property)} -This property's value is a string to add to the display at the end of -the overlay. The string does not appear in the buffer in any -sense---only on the screen. The string should contain only characters -that display as a single column---control characters, including tabs or -newlines, will give strange results. - -@item evaporate -@kindex evaporate @r{(overlay property)} -If this property is non-@code{nil}, the overlay is deleted automatically -if it ever becomes empty (i.e., if it spans no characters). - -@item local-map -@cindex keymap of character -@kindex local-map @r{(text property)} -If this property is non-@code{nil}, it specifies a keymap for a portion -of the text. The property's value replaces the buffer's local map, when -the character after point is within the overlay. @xref{Active Keymaps}. -@end table - - These are the functions for reading and writing the properties of an -overlay. - -@defun overlay-get overlay prop -This function returns the value of property @var{prop} recorded in -@var{overlay}, if any. If @var{overlay} does not record any value for -that property, but it does have a @code{category} property which is a -symbol, that symbol's @var{prop} property is used. Otherwise, the value -is @code{nil}. -@end defun - -@defun overlay-put overlay prop value -This function sets the value of property @var{prop} recorded in -@var{overlay} to @var{value}. It returns @var{value}. -@end defun - - See also the function @code{get-char-property} which checks both -overlay properties and text properties for a given character. -@xref{Examining Properties}. - -@node Managing Overlays -@subsection Managing Overlays - - This section describes the functions to create, delete and move -overlays, and to examine their contents. - -@defun make-overlay start end &optional buffer -This function creates and returns an overlay that belongs to -@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start} -and @var{end} must specify buffer positions; they may be integers or -markers. If @var{buffer} is omitted, the overlay is created in the -current buffer. -@end defun - -@defun overlay-start overlay -This function returns the position at which @var{overlay} starts. -@end defun - -@defun overlay-end overlay -This function returns the position at which @var{overlay} ends. -@end defun - -@defun overlay-buffer overlay -This function returns the buffer that @var{overlay} belongs to. -@end defun - -@defun delete-overlay overlay -This function deletes @var{overlay}. The overlay continues to exist as -a Lisp object, but ceases to be part of the buffer it belonged to, and -ceases to have any effect on display. -@end defun - -@defun move-overlay overlay start end &optional buffer -This function moves @var{overlay} to @var{buffer}, and places its bounds -at @var{start} and @var{end}. Both arguments @var{start} and @var{end} -must specify buffer positions; they may be integers or markers. If -@var{buffer} is omitted, the overlay stays in the same buffer. - -The return value is @var{overlay}. - -This is the only valid way to change the endpoints of an overlay. Do -not try modifying the markers in the overlay by hand, as that fails to -update other vital data structures and can cause some overlays to be -``lost''. -@end defun - -@defun overlays-at pos -This function returns a list of all the overlays that contain position -@var{pos} in the current buffer. The list is in no particular order. -An overlay contains position @var{pos} if it begins at or before -@var{pos}, and ends after @var{pos}. -@end defun - -@defun next-overlay-change pos -This function returns the buffer position of the next beginning or end -of an overlay, after @var{pos}. -@end defun - -@defun previous-overlay-change pos -This function returns the buffer position of the previous beginning or -end of an overlay, before @var{pos}. -@end defun - -@node Faces -@section Faces -@cindex face - -A @dfn{face} is a named collection of graphical attributes: font, -foreground color, background color and optional underlining. Faces -control the display of text on the screen. - -@cindex face id -Each face has its own @dfn{face id number} which distinguishes faces at -low levels within Emacs. However, for most purposes, you can refer to -faces in Lisp programs by their names. - -@defun facep object -This function returns @code{t} if @var{object} is a face name symbol (or -if it is a vector of the kind used internally to record face data). It -returns @code{nil} otherwise. -@end defun - -Each face name is meaningful for all frames, and by default it has the -same meaning in all frames. But you can arrange to give a particular -face name a special meaning in one frame if you wish. - -@menu -* Standard Faces:: The faces Emacs normally comes with. -* Merging Faces:: How Emacs decides which face to use for a character. -* Face Functions:: How to define and examine faces. -@end menu - -@node Standard Faces -@subsection Standard Faces - - This table lists all the standard faces and their uses. - -@table @code -@item default -@kindex default @r{(face name)} -This face is used for ordinary text. - -@item modeline -@kindex modeline @r{(face name)} -This face is used for mode lines and menu bars. - -@item region -@kindex region @r{(face name)} -This face is used for highlighting the region in Transient Mark mode. - -@item secondary-selection -@kindex secondary-selection @r{(face name)} -This face is used to show any secondary selection you have made. - -@item highlight -@kindex highlight @r{(face name)} -This face is meant to be used for highlighting for various purposes. - -@item underline -@kindex underline @r{(face name)} -This face underlines text. - -@item bold -@kindex bold @r{(face name)} -This face uses a bold font, if possible. It uses the bold variant of -the frame's font, if it has one. It's up to you to choose a default -font that has a bold variant, if you want to use one. - -@item italic -@kindex italic @r{(face name)} -This face uses the italic variant of the frame's font, if it has one. - -@item bold-italic -@kindex bold-italic @r{(face name)} -This face uses the bold italic variant of the frame's font, if it has -one. -@end table - -@node Merging Faces -@subsection Merging Faces for Display - - Here are all the ways to specify which face to use for display of text: - -@itemize @bullet -@item -With defaults. Each frame has a @dfn{default face}, whose id number is -zero, which is used for all text that doesn't somehow specify another -face. - -@item -With text properties. A character may have a @code{face} property; if so, -it is displayed with that face. @xref{Special Properties}. - -If the character has a @code{mouse-face} property, that is used instead -of the @code{face} property when the mouse is ``near enough'' to the -character. - -@item -With overlays. An overlay may have @code{face} and @code{mouse-face} -properties too; they apply to all the text covered by the overlay. - -@item -With a region that is active. In Transient Mark mode, the region is -highlighted with a particular face (see @code{region-face}, below). - -@item -With special glyphs. Each glyph can specify a particular face id -number. @xref{Glyphs}. -@end itemize - - If these various sources together specify more than one face for a -particular character, Emacs merges the attributes of the various faces -specified. The attributes of the faces of special glyphs come first; -then comes the face for region highlighting, if appropriate; -then come attributes of faces from overlays, followed by those from text -properties, and last the default face. - - When multiple overlays cover one character, an overlay with higher -priority overrides those with lower priority. @xref{Overlays}. - - If an attribute such as the font or a color is not specified in any of -the above ways, the frame's own font or color is used. - -@node Face Functions -@subsection Functions for Working with Faces - - The attributes a face can specify include the font, the foreground -color, the background color, and underlining. The face can also leave -these unspecified by giving the value @code{nil} for them. - - Here are the primitives for creating and changing faces. - -@defun make-face name -This function defines a new face named @var{name}, initially with all -attributes @code{nil}. It does nothing if there is already a face named -@var{name}. -@end defun - -@defun face-list -This function returns a list of all defined face names. -@end defun - -@defun copy-face old-face new-name &optional frame new-frame -This function defines the face @var{new-name} as a copy of the existing -face named @var{old-face}. It creates the face @var{new-name} if that -doesn't already exist. - -If the optional argument @var{frame} is given, this function applies -only to that frame. Otherwise it applies to each frame individually, -copying attributes from @var{old-face} in each frame to @var{new-face} -in the same frame. - -If the optional argument @var{new-frame} is given, then @code{copy-face} -copies the attributes of @var{old-face} in @var{frame} to @var{new-name} -in @var{new-frame}. -@end defun - - You can modify the attributes of an existing face with the following -functions. If you specify @var{frame}, they affect just that frame; -otherwise, they affect all frames as well as the defaults that apply to -new frames. - -@defun set-face-foreground face color &optional frame -@defunx set-face-background face color &optional frame -These functions set the foreground (or background, respectively) color -of face @var{face} to @var{color}. The argument @var{color} should be a -string, the name of a color. - -Certain shades of gray are implemented by stipple patterns on -black-and-white screens. -@end defun - -@defun set-face-stipple face pattern &optional frame -This function sets the background stipple pattern of face @var{face} to -@var{pattern}. The argument @var{pattern} should be the name of a -stipple pattern defined by the X server, or @code{nil} meaning don't use -stipple. - -Normally there is no need to pay attention to stipple patterns, because -they are used automatically to handle certain shades of gray. -@end defun - -@defun set-face-font face font &optional frame -This function sets the font of face @var{face}. The argument @var{font} -should be a string. -@end defun - -@defun set-face-underline-p face underline-p &optional frame -This function sets the underline attribute of face @var{face}. -Non-@code{nil} means do underline; @code{nil} means don't. -@end defun - -@defun invert-face face &optional frame -Swap the foreground and background colors of face @var{face}. If the -face doesn't specify both foreground and background, then its foreground -and background are set to the default background and foreground, -respectively. -@end defun - - These functions examine the attributes of a face. If you don't -specify @var{frame}, they refer to the default data for new frames. - -@defun face-foreground face &optional frame -@defunx face-background face &optional frame -These functions return the foreground color (or background color, -respectively) of face @var{face}, as a string. -@end defun - -@defun face-stipple face &optional frame -This function returns the name of the background stipple pattern of face -@var{face}, or @code{nil} if it doesn't have one. -@end defun - -@defun face-font face &optional frame -This function returns the name of the font of face @var{face}. -@end defun - -@defun face-underline-p face &optional frame -This function returns the underline attribute of face @var{face}. -@end defun - -@defun face-id face -This function returns the face id number of face @var{face}. -@end defun - -@defun face-equal face1 face2 &optional frame -This returns @code{t} if the faces @var{face1} and @var{face2} have the -same attributes for display. -@end defun - -@defun face-differs-from-default-p face &optional frame -This returns @code{t} if the face @var{face} displays differently from -the default face. A face is considered to be ``the same'' as the normal -face if each attribute is either the same as that of the default face or -@code{nil} (meaning to inherit from the default). -@end defun - -@defvar region-face -This variable's value specifies the face id to use to display characters -in the region when it is active (in Transient Mark mode only). The face -thus specified takes precedence over all faces that come from text -properties and overlays, for characters in the region. @xref{The Mark}, -for more information about Transient Mark mode. - -Normally, the value is the id number of the face named @code{region}. -@end defvar - -@node Blinking -@section Blinking Parentheses -@cindex parenthesis matching -@cindex blinking -@cindex balancing parentheses -@cindex close parenthesis - - This section describes the mechanism by which Emacs shows a matching -open parenthesis when the user inserts a close parenthesis. - -@vindex blink-paren-hook -@defvar blink-paren-function -The value of this variable should be a function (of no arguments) to -be called whenever a character with close parenthesis syntax is inserted. -The value of @code{blink-paren-function} may be @code{nil}, in which -case nothing is done. - -@quotation -@strong{Please note:} This variable was named @code{blink-paren-hook} in -older Emacs versions, but since it is not called with the standard -convention for hooks, it was renamed to @code{blink-paren-function} in -version 19. -@end quotation -@end defvar - -@defvar blink-matching-paren -If this variable is @code{nil}, then @code{blink-matching-open} does -nothing. -@end defvar - -@defvar blink-matching-paren-distance -This variable specifies the maximum distance to scan for a matching -parenthesis before giving up. -@end defvar - -@defvar blink-matching-paren-delay -This variable specifies the number of seconds for the cursor to remain -at the matching parenthesis. A fraction of a second often gives -good results, but the default is 1, which works on all systems. -@end defvar - -@defun blink-matching-open -This function is the default value of @code{blink-paren-function}. It -assumes that point follows a character with close parenthesis syntax and -moves the cursor momentarily to the matching opening character. If that -character is not already on the screen, it displays the character's -context in the echo area. To avoid long delays, this function does not -search farther than @code{blink-matching-paren-distance} characters. - -Here is an example of calling this function explicitly. - -@smallexample -@group -(defun interactive-blink-matching-open () -@c Do not break this line! -- rms. -@c The first line of a doc string -@c must stand alone. - "Indicate momentarily the start of sexp before point." - (interactive) -@end group -@group - (let ((blink-matching-paren-distance - (buffer-size)) - (blink-matching-paren t)) - (blink-matching-open))) -@end group -@end smallexample -@end defun - -@node Inverse Video -@section Inverse Video -@cindex Inverse Video - -@defopt inverse-video -@cindex highlighting -This variable controls whether Emacs uses inverse video for all text -on the screen. Non-@code{nil} means yes, @code{nil} means no. The -default is @code{nil}. -@end defopt - -@defopt mode-line-inverse-video -This variable controls the use of inverse video for mode lines. If it -is non-@code{nil}, then mode lines are displayed in inverse video. -Otherwise, mode lines are displayed normally, just like text. The -default is @code{t}. - -For X window frames, this displays mode lines using the face named -@code{modeline}, which is normally the inverse of the default face -unless you change it. -@end defopt - -@node Usual Display -@section Usual Display Conventions - - The usual display conventions define how to display each character -code. You can override these conventions by setting up a display table -(@pxref{Display Tables}). Here are the usual display conventions: - -@itemize @bullet -@item -Character codes 32 through 126 map to glyph codes 32 through 126. -Normally this means they display as themselves. - -@item -Character code 9 is a horizontal tab. It displays as whitespace -up to a position determined by @code{tab-width}. - -@item -Character code 10 is a newline. - -@item -All other codes in the range 0 through 31, and code 127, display in one -of two ways according to the value of @code{ctl-arrow}. If it is -non-@code{nil}, these codes map to sequences of two glyphs, where the -first glyph is the @sc{ASCII} code for @samp{^}. (A display table can -specify a glyph to use instead of @samp{^}.) Otherwise, these codes map -just like the codes in the range 128 to 255. - -@item -Character codes 128 through 255 map to sequences of four glyphs, where -the first glyph is the @sc{ASCII} code for @samp{\}, and the others are -digit characters representing the code in octal. (A display table can -specify a glyph to use instead of @samp{\}.) -@end itemize - - The usual display conventions apply even when there is a display -table, for any character whose entry in the active display table is -@code{nil}. Thus, when you set up a display table, you need only -specify the characters for which you want unusual behavior. - - These variables affect the way certain characters are displayed on the -screen. Since they change the number of columns the characters occupy, -they also affect the indentation functions. - -@defopt ctl-arrow -@cindex control characters in display -This buffer-local variable controls how control characters are -displayed. If it is non-@code{nil}, they are displayed as a caret -followed by the character: @samp{^A}. If it is @code{nil}, they are -displayed as a backslash followed by three octal digits: @samp{\001}. -@end defopt - -@c Following may have overfull hbox. -@defvar default-ctl-arrow -The value of this variable is the default value for @code{ctl-arrow} in -buffers that do not override it. @xref{Default Value}. -@end defvar - -@defopt tab-width -The value of this variable is the spacing between tab stops used for -displaying tab characters in Emacs buffers. The default is 8. Note -that this feature is completely independent from the user-settable tab -stops used by the command @code{tab-to-tab-stop}. @xref{Indent Tabs}. -@end defopt - -@node Display Tables -@section Display Tables - -@cindex display table -You can use the @dfn{display table} feature to control how all 256 -possible character codes display on the screen. This is useful for -displaying European languages that have letters not in the @sc{ASCII} -character set. - -The display table maps each character code into a sequence of -@dfn{glyphs}, each glyph being an image that takes up one character -position on the screen. You can also define how to display each glyph -on your terminal, using the @dfn{glyph table}. - -@menu -* Display Table Format:: What a display table consists of. -* Active Display Table:: How Emacs selects a display table to use. -* Glyphs:: How to define a glyph, and what glyphs mean. -* ISO Latin 1:: How to use display tables - to support the ISO Latin 1 character set. -@end menu - -@node Display Table Format -@subsection Display Table Format - - A display table is actually an array of 262 elements. - -@defun make-display-table -This creates and returns a display table. The table initially has -@code{nil} in all elements. -@end defun - - The first 256 elements correspond to character codes; the @var{n}th -element says how to display the character code @var{n}. The value -should be @code{nil} or a vector of glyph values (@pxref{Glyphs}). If -an element is @code{nil}, it says to display that character according to -the usual display conventions (@pxref{Usual Display}). - - If you use the display table to change the display of newline -characters, the whole buffer will be displayed as one long ``line.'' - - The remaining six elements of a display table serve special purposes, -and @code{nil} means use the default stated below. - -@table @asis -@item 256 -The glyph for the end of a truncated screen line (the default for this -is @samp{$}). @xref{Glyphs}. -@item 257 -The glyph for the end of a continued line (the default is @samp{\}). -@item 258 -The glyph for indicating a character displayed as an octal character -code (the default is @samp{\}). -@item 259 -The glyph for indicating a control character (the default is @samp{^}). -@item 260 -A vector of glyphs for indicating the presence of invisible lines (the -default is @samp{...}). @xref{Selective Display}. -@item 261 -The glyph used to draw the border between side-by-side windows (the -default is @samp{|}). @xref{Splitting Windows}. -@end table - - For example, here is how to construct a display table that mimics the -effect of setting @code{ctl-arrow} to a non-@code{nil} value: - -@example -(setq disptab (make-display-table)) -(let ((i 0)) - (while (< i 32) - (or (= i ?\t) (= i ?\n) - (aset disptab i (vector ?^ (+ i 64)))) - (setq i (1+ i))) - (aset disptab 127 (vector ?^ ??))) -@end example - -@node Active Display Table -@subsection Active Display Table -@cindex active display table - - Each window can specify a display table, and so can each buffer. When -a buffer @var{b} is displayed in window @var{w}, display uses the -display table for window @var{w} if it has one; otherwise, the display -table for buffer @var{b} if it has one; otherwise, the standard display -table if any. The display table chosen is called the @dfn{active} -display table. - -@defun window-display-table window -This function returns @var{window}'s display table, or @code{nil} -if @var{window} does not have an assigned display table. -@end defun - -@defun set-window-display-table window table -This function sets the display table of @var{window} to @var{table}. -The argument @var{table} should be either a display table or -@code{nil}. -@end defun - -@defvar buffer-display-table -This variable is automatically local in all buffers; its value in a -particular buffer is the display table for that buffer, or @code{nil} if -the buffer does not have an assigned display table. -@end defvar - -@defvar standard-display-table -This variable's value is the default display table, used whenever a -window has no display table and neither does the buffer displayed in -that window. This variable is @code{nil} by default. -@end defvar - - If there is no display table to use for a particular window---that is, -if the window has none, its buffer has none, and -@code{standard-display-table} has none---then Emacs uses the usual -display conventions for all character codes in that window. @xref{Usual -Display}. - -@node Glyphs -@subsection Glyphs - -@cindex glyph - A @dfn{glyph} is a generalization of a character; it stands for an -image that takes up a single character position on the screen. Glyphs -are represented in Lisp as integers, just as characters are. - -@cindex glyph table - The meaning of each integer, as a glyph, is defined by the glyph -table, which is the value of the variable @code{glyph-table}. - -@defvar glyph-table -The value of this variable is the current glyph table. It should be a -vector; the @var{g}th element defines glyph code @var{g}. If the value -is @code{nil} instead of a vector, then all glyphs are simple (see -below). -@end defvar - - Here are the possible types of elements in the glyph table: - -@table @var -@item string -Send the characters in @var{string} to the terminal to output -this glyph. This alternative is available on character terminals, -but not under X. - -@item integer -Define this glyph code as an alias for code @var{integer}. You can use -an alias to specify a face code for the glyph; see below. - -@item @code{nil} -This glyph is simple. On an ordinary terminal, the glyph code mod 256 -is the character to output. With X, the glyph code mod 256 is the -character to output, and the glyph code divided by 256 specifies the -@dfn{face id number} to use while outputting it. @xref{Faces}. -@end table - - If a glyph code is greater than or equal to the length of the glyph -table, that code is automatically simple. - -@node ISO Latin 1 -@subsection ISO Latin 1 - -If you have a terminal that can handle the entire ISO Latin 1 character -set, you can arrange to use that character set as follows: - -@example -(require 'disp-table) -;; @r{Set char codes 160--255 to display as themselves.} -;; @r{(Codes 128--159 are the additional control characters.)} -(standard-display-8bit 160 255) -@end example - -If you are editing buffers written in the ISO Latin 1 character set and -your terminal doesn't handle anything but @sc{ASCII}, you can load the -file @file{iso-ascii} to set up a display table that displays the other -ISO characters as explanatory sequences of @sc{ASCII} characters. For -example, the character ``o with umlaut'' displays as @samp{@{"o@}}. - -Some European countries have terminals that don't support ISO Latin 1 -but do support the special characters for that country's language. You -can define a display table to work one language using such terminals. -For an example, see @file{lisp/iso-swed.el}, which handles certain -Swedish terminals. - -You can load the appropriate display table for your terminal -automatically by writing a terminal-specific Lisp file for the terminal -type. - -@node Beeping -@section Beeping -@cindex beeping -@cindex bell - - You can make Emacs ring a bell (or blink the screen) to attract the -user's attention. Be conservative about how often you do this; frequent -bells can become irritating. Also be careful not to use beeping alone -when signaling an error is appropriate. (@xref{Errors}.) - -@defun ding &optional dont-terminate -@cindex keyboard macro termination -This function beeps, or flashes the screen (see @code{visible-bell} below). -It also terminates any keyboard macro currently executing unless -@var{dont-terminate} is non-@code{nil}. -@end defun - -@defun beep &optional dont-terminate -This is a synonym for @code{ding}. -@end defun - -@defvar visible-bell -This variable determines whether Emacs should flash the screen to -represent a bell. Non-@code{nil} means yes, @code{nil} means no. This -is effective under X windows, and on a character-only terminal provided -the terminal's Termcap entry defines the visible bell capability -(@samp{vb}). -@end defvar - -@node Window Systems -@section Window Systems - - Emacs works with several window systems, most notably the X Window -System. Both Emacs and X use the term ``window'', but use it -differently. An Emacs frame is a single window as far as X is -concerned; the individual Emacs windows are not known to X at all. - -@defvar window-system -@cindex X Window System -This variable tells Lisp programs what window system Emacs is running -under. Its value should be a symbol such as @code{x} (if Emacs is -running under X) or @code{nil} (if Emacs is running on an ordinary -terminal). -@end defvar - -@defvar window-setup-hook -This variable is a normal hook which Emacs runs after loading your -@file{.emacs} file and the default initialization file (if any), after -loading terminal-specific Lisp code, and after running the hook -@code{term-setup-hook}. - -This hook is used for internal purposes: setting up communication with -the window system, and creating the initial window. Users should not -interfere with it. -@end defvar diff --git a/lispref/edebug.texi b/lispref/edebug.texi deleted file mode 100644 index 0f95fa9fb0c..00000000000 --- a/lispref/edebug.texi +++ /dev/null @@ -1,1545 +0,0 @@ -@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,, Compilation Errors, Debugging -@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, to invoke Edebug at the proper places. - -@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 that never instrument them: from a file with -@code{load}, and from the minibuffer with @code{eval-expression} -(@kbd{M-:}). - - 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 execution 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 than the modes later in the list. - -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 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, @kbd{o} 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, and stops at its first stop 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 current 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 following point, within the same -function, 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 - The condition expression is stored in -@code{edebug-global-break-condition}. You can specify a new expression -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}). - -@c Edebug should be changed for the following: -- dan -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. - -@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. The outside window -configuration is the collection of windows and contents that were in -effect outside of Edebug. - -@table @kbd -@item v -Temporarily 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 -@c Its function is not simply to forget the saved configuration -- dan -Toggle whether Edebug saves and restores the outside window -configuration (@code{edebug-toggle-save-windows}). - -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 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. - -Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the -saved outside window configuration---so that even if you turn saving -back @emph{on}, the current window configuration remains unchanged when -you next exit Edebug (by continuing the program). 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. - -@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-: @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 the 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. (The idea is that the second expression of the group is the -value previously computed and displayed.) - -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. - -Each entry to Edebug redisplays the evaluation list 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, storing it 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 appends 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. - -@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 as comment lines after each line of code, and -you can undo all insertions with one @code{undo} command. The counts -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} was called 6 times. The -first @code{if} statement 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} did not return 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. - -@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, it needs to save and restore certain data -before even deciding whether to make trace information or stop the -program. - -@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 - -@c This paragraph is not filled, because LaLiberte's conversion script -@c needs an xref to be on just one line. -When Edebug needs to display something (e.g., in trace mode), it saves -the current window configuration from ``outside'' Edebug -(@pxref{Window Configurations}). 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 -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. - -Edebug cannot save and restore the value of -@code{unread-command-events}. Entering Edebug while this variable has a -nontrivial value can interfere with execution of the program you are -debugging. - -@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-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 @asis -@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. -* 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 Lisp object, not unevaluated. -@c "unevaluated expression" is not meaningful, because -@c an expression is a Lisp object intended for evaluation. - -@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. - -Some suitable predicates include @code{symbolp}, @code{integerp}, -@code{stringp}, @code{vectorp}, and @code{atom}. - -@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. - -@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 written as @code{(specs . nil)} -is equivalent to @code{(specs)}, and @code{(specs . -(sublist-elements@dots{}))} is equivalent to @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. - -@item lambda-list -@cindex lambda-list (Edebug) -This matches a lambda list---the argument list of a lambda expression. - -@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. - -@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. - -@smallexample -(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 smallexample - -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.) - -@smallexample -(def-edebug-spec ` (backquote-form)) ; @r{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 smallexample - - -@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}, @code{eval-buffer}, -and @code{eval-current-buffer}. - -Use the command @kbd{M-x edebug-all-defs} to toggle the value of this -option. @xref{Instrumenting}. -@end defopt - -@defopt edebug-all-forms -If this is non-@code{nil}, the commands @code{eval-defun}, -@code{eval-region}, @code{eval-buffer}, and @code{eval-current-buffer} -instrument all forms, even those that don't define anything. -This doesn't apply to loading or evaluations in the minibuffer. - -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 this is non-@code{nil}, Edebug saves and restores point in all -displayed 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, -point in that buffer will move to the window's value of 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}, in @xref{Trace Buffer}. -@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 via a new command. -@c Not necessarily a deeper command level. -@c A new command is not precisely true, but that is close enough -- dan - -@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 diff --git a/lispref/elisp-covers.texi b/lispref/elisp-covers.texi deleted file mode 100644 index aa9d23b8444..00000000000 --- a/lispref/elisp-covers.texi +++ /dev/null @@ -1,248 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename covers.info -@settitle GNU Emacs Lisp Reference Manual -@comment %**end of header - -@titlepage -@c ================ Volume 1 ================ -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 2 ================ -@w{ } -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, -@center Dan LaLiberte, and -@center the GNU Manual Group - -@page -@c ================ Volume 1 with baseline skip 16pt ================ - -@tex -\global\baselineskip = 16pt -@end tex - -16 pts baseline skip: - -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 1 with baseline skip 18pt ================ - -@tex -\global\baselineskip = 18pt -@end tex - -18 pts baseline skip, with 15pts between sections - -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@tex -\global\baselineskip = 15pt -@end tex - -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, -@center Dan LaLiberte, and -@center the GNU Manual Group - -@page -@c ================ Volume 1 with more baseline skip 24 pts ================ - -@tex -\global\baselineskip = 24pt -@end tex - -24 pts baseline skip: - -@w{ } -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 2 with more baseline skip 18 pts ================ - -@tex -\global\baselineskip = 18pt -@end tex - -18 pts baseline skip: - -@w{ } -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@page -@c ================ Volume 2 with more baseline skip 24 pts ================ - -@tex -\global\baselineskip = 24pt -@end tex - -24 pts baseline skip: - -@w{ } -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - - -@page -@c ================ Spine 1 ================ - -@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 1}} -@sp 4 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 4 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@sp 4 -@author The GNU Emacs Lisp Reference Manual --- Vol. 1 -@sp 3 -@author FSF - -@author - -@page -@c ================ Spine 2 ================ - -@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 2}} -@sp 4 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 4 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - - -@sp 4 -@author The GNU Emacs Lisp Reference Manual --- Vol. 2 -@sp 3 -@author FSF - -@end titlepage -@bye diff --git a/lispref/elisp-vol1.texi b/lispref/elisp-vol1.texi deleted file mode 100644 index 2d9e96311c5..00000000000 --- a/lispref/elisp-vol1.texi +++ /dev/null @@ -1,1047 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename elisp -@settitle GNU Emacs Lisp Reference Manual: Volume 1 -@smallbook -@c %**end of header - - -@tex -%%%% Experiment with smaller skip before sections and subsections. -%%%% --rjc 30mar92 - -\global\secheadingskip = 17pt plus 6pt minus 3pt -\global\subsecheadingskip = 14pt plus 6pt minus 3pt - -% The defaults are: -% \secheadingskip = 21pt plus 8pt minus 4pt -% \subsecheadingskip = 17pt plus 8pt minus 4pt -@end tex - -@finalout -@c tex -@c \overfullrule=0pt -@c end tex - -@c Start volume 1 chapter numbering on chapter 1; -@c this must be listed as chapno 0. -@tex -\global\chapno=0 -@end tex - -@c ================================================================ -@c Note: I was unable to figure out how to get .aux files copied -@c properly in the time I had. Hence need to copy .aux file before -@c running Tex. --rjc - -@tex - -\message{} -\message{Redefining contents commands...} -\message{} - -% Special @contents command - -% This inputs fixed up table of contents file rather than create new one. -\global\def\contents{% - \startcontents{Table of Contents}% - \input elisp1-toc-ready.toc - \endgroup - \vfill \eject -} - -% Special @summarycontents command -% This inputs fixed up table of contents file rather than create new one. -\global\def\summarycontents{% - \startcontents{Short Contents}% - % - \let\chapentry = \shortchapentry - \let\unnumbchapentry = \shortunnumberedentry - % We want a true roman here for the page numbers. - \secfonts - \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl - \rm - \advance\baselineskip by 1pt % Open it up a little. - \def\secentry ##1##2##3##4{} - \def\unnumbsecentry ##1##2{} - \def\subsecentry ##1##2##3##4##5{} - \def\unnumbsubsecentry ##1##2{} - \def\subsubsecentry ##1##2##3##4##5##6{} - \def\unnumbsubsubsecentry ##1##2{} - \input elisp1-toc-ready.toc - \endgroup - \vfill \eject -} - -\message{} -\message{Formatting special two volume edition...Volume 1...} -\message{} -@end tex -@c ================================================================ - - -@c ==> This `elisp-small.texi' is a `smallbook' version of the manual. - -@c ==== Following are acceptable over and underfull hboxes in TeX ==== - -@c ----- -@c [163] [164] [165] [166]) (loading.texi Chapter 13 [167] [168] [169] -@c Overfull \hbox (20.5428pt too wide) in paragraph at lines 131--131 -@c []@ninett -@c setenv EMAC-SLOAD-PATH .:/user/bil/emacs:/usr/local/lib/emacs/lisp[] -@c ----- -@c (minibuf.texi Chapter 17 [206] [207] [208] [209] [210] [211] [212] [213] -@c [214] [215] -@c Overfull \hbox (2.09094pt too wide) in paragraph at lines 550--560 -@c @texttt map[] @textrm if @textsl require-match @textrm is -@c @texttt nil[]@textrm , or else with the keymap @texttt minibuffer- -@c ----- -@c (locals.texi Appendix @char 68 [533] [534] -@c Underfull \hbox (badness 2512) in paragraph at lines 4--4 -@c []@chaprm Appendix DStandard Buffer-Local - -@c ------------------------------------------------------------------- - -@c -@c Combine indices. -@synindex cp fn -@syncodeindex vr fn -@syncodeindex ky fn -@syncodeindex pg fn -@syncodeindex tp fn -@c oops: texinfo-format-buffer ignores synindex -@c - -@ifinfo -This file documents GNU Emacs Lisp. - -@c The edition number appears in several places in this file -@c and also in the file intro.texi. -This is edition 2.4 of the GNU Emacs Lisp Reference -Manual. It corresponds to Emacs Version 19.29. -@c Please REMEMBER to update edition number in *four* places in this file -@c and also in *one* place in ==> intro.texi <== -@c huh? i only found three real places where the edition is stated, and -@c one place where it is not stated explicitly ("this info file is newer -@c than the foobar edition"). --mew 13sep93 - -Published by the Free Software Foundation -59 Temple Place, Suite 330 -Boston, MA 02111-1307 USA - -Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission notice -identical to this one except for the removal of this paragraph (this -paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation -approved by the Foundation. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU General Public License'' is included exactly as -in the original, and provided that the entire resulting derived work is -distributed under the terms of a permission notice identical to this -one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU General Public License'' may be -included in a translation approved by the Free Software Foundation -instead of in the original English. -@end ifinfo - -@setchapternewpage odd - -@iftex -@shorttitlepage The GNU Emacs Lisp Reference Manual: Volume 1 -@end iftex -@titlepage -@sp 1 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU Emacs Lisp} -@sp 1 -@center @titlefont{Reference Manual} -@sp 2 -@center GNU Emacs Version 19.29 -@center for Unix Users -@sp 1 -@center Edition 2.4, June 1995 -@sp 2 -@center @titlefont{Volume 1} -@sp 3 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. - -@sp 2 -Edition 2.4 @* -Revised for Emacs Version 19.29,@* -June, 1995.@* -@sp 2 -ISBN 1-882114-71-X - -@sp 2 -Published by the Free Software Foundation @* -59 Temple Place, Suite 330 @* -Boston, MA 02111-1307 USA - -@sp 1 -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU General Public License'' is included -exactly as in the original, and provided that the entire resulting -derived work is distributed under the terms of a permission notice -identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU General Public License'' may be -included in a translation approved by the Free Software Foundation -instead of in the original English. - -@sp 2 -Cover art by Etienne Suvasa. -@end titlepage -@page - -@node Top, Copying, (dir), (dir) - -@ifinfo -This Info file contains edition 2.4 of the GNU Emacs Lisp Reference -Manual, corresponding to GNU Emacs version 19.29. -@end ifinfo - -@menu -* Copying:: Conditions for copying and changing GNU Emacs. -* Introduction:: Introduction and conventions used. - -* Lisp Data Types:: Data types of objects in Emacs Lisp. -* Numbers:: Numbers and arithmetic functions. -* Strings and Characters:: Strings, and functions that work on them. -* Lists:: Lists, cons cells, and related functions. -* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. - Certain functions act on any kind of sequence. - The description of vectors is here as well. -* Symbols:: Symbols represent names, uniquely. - -* Evaluation:: How Lisp expressions are evaluated. -* Control Structures:: Conditionals, loops, nonlocal exits. -* Variables:: Using symbols in programs to stand for values. -* Functions:: A function is a Lisp program - that can be invoked from other functions. -* Macros:: Macros are a way to extend the Lisp language. - -* Loading:: Reading files of Lisp code into Lisp. -* Byte Compilation:: Compilation makes programs run faster. -* Debugging:: Tools and tips for debugging Lisp programs. - -* Read and Print:: Converting Lisp objects to text and back. -* Minibuffers:: Using the minibuffer to read input. -* Command Loop:: How the editor command loop works, - and how you can call its subroutines. -* Keymaps:: Defining the bindings from keys to commands. -* Modes:: Defining major and minor modes. -* Documentation:: Writing and using documentation strings. - -* Files:: Accessing files. -* Backups and Auto-Saving:: Controlling how backups and auto-save - files are made. -* Buffers:: Creating and using buffer objects. -* Windows:: Manipulating windows and displaying buffers. -* Frames:: Making multiple X windows. -* Positions:: Buffer positions and motion functions. -* Markers:: Markers represent positions and update - automatically when the text is changed. - -* Text:: Examining and changing text in buffers. -* Searching and Matching:: Searching buffers for strings or regexps. -* Syntax Tables:: The syntax table controls word and list parsing. -* Abbrevs:: How Abbrev mode works, and its data structures. - -* Processes:: Running and communicating with subprocesses. -* System Interface:: Getting the user id, system type, environment - variables, and other such things. -* Display:: Parameters controlling screen usage. - The bell. Waiting for input. -* Calendar:: Customizing the calendar and diary. - -Appendices - -* Tips:: Advice for writing Lisp programs. -* GNU Emacs Internals:: Building and dumping Emacs; - internal data structures. -* Standard Errors:: List of all error symbols. -* Standard Buffer-Local Variables:: List of variables local in all buffers. -* Standard Keymaps:: List of standard keymaps. -* Standard Hooks:: List of standard hook variables. - -* Index:: Index including concepts, functions, variables, - and other terms. - - --- The Detailed Node Listing --- - -Here are other nodes that are inferiors of those already listed, -mentioned here so you can get to them in one step: - -Introduction - -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Acknowledgements:: The authors, editors, and sponsors of this manual. - -Conventions - -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use for examples that print output. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. - -Format of Descriptions - -* A Sample Function Description:: -* A Sample Variable Description:: - -Lisp Data Types - -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. - -Programming Types - -* Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Symbol Type:: A multi-use object that refers to a function, - variable, property list, or itself. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. - -List Type - -* Dotted Pair Notation:: An alternative syntax for lists. -* Association List Type:: A specially constructed list. - -Editing Types - -* Buffer Type:: The basic object of editing. -* Window Type:: What makes buffers visible. -* Window Configuration Type::Save what the screen looks like. -* Marker Type:: A position in a buffer. -* Process Type:: A process running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Syntax Table Type:: What a character means. - -Numbers - -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Bitwise Operations:: Logical and, or, not, shifting. -* Numeric Conversions:: Converting float to integer and vice versa. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. - -Strings and Characters - -* String Basics:: Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting characters or strings and vice versa. -* Formatting Strings:: @code{format}: Emacs's analog of @code{printf}. -* Character Case:: Case conversion functions. - -Lists - -* 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. - -Modifying Existing List Structure - -* 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. - -Sequences, Arrays, and Vectors - -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Functions specifically for vectors. - -Symbols - -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Property Lists:: Each symbol has a property list - for recording miscellaneous information. - -Evaluation - -* 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). - -Kinds of Forms - -* 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 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. - -Control Structures - -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. - -Nonlocal Exits - -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an - error happens. - -Errors - -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. - -Variables - -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. - -Scoping Rules for Variable Bindings - -* Scope:: Scope means where in the program a value - is visible. Comparison with other languages. -* Extent:: Extent means how long in time a value exists. -* Impl of Scope:: Two ways to implement dynamic scoping. -* Using Scoping:: How to use dynamic scoping carefully and - avoid problems. - -Buffer-Local Variables - -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own local values. - -Functions - -* What Is a Function:: Lisp functions vs primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda-expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how - functions work. - -Lambda Expressions - -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. - -Macros - -* 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. - -Loading - -* How Programs Do Loading:: The @code{load} function and others. -* Autoload:: Setting up a function to autoload. -* Named Features:: Loading a library if it isn't already loaded. -* Repeated Loading:: Precautions about loading a file twice. - -Byte Compilation - -* Compilation Functions:: Byte compilation functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. - -Debugging Lisp Programs - -* 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. - -The Lisp Debugger - -* Error Debugging:: Entering the debugger when an error happens. -* 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. - -Debugging Invalid Lisp Syntax - -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. - -Reading and Printing Lisp Objects - -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as - input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as - output streams. -* Output Functions:: Functions to print Lisp objects as text. - -Minibuffers - -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Minibuffer Misc:: Various customization hooks and variables. - -Completion - -* Basic Completion:: Low-level functions for completing strings. - (These are too low level to use the minibuffer.) -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer name, file name, etc.) -* Reading File Names:: Using completion to read file names. -* Programmed Completion:: Finding the completions for a given file name. - -Command Loop - -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. - -Defining Commands - -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. - -Keymaps - -* 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 for X windows - or for use from the terminal. -* Active Keymaps:: Each buffer has a local keymap - to override the standard (global) bindings. - Each 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. - -Major and Minor Modes - -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Hooks:: How to use hooks; how to write code that - provides hooks. - -Major Modes - -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Example Major Modes:: Text mode and Lisp modes. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. - -Minor Modes - -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. - -Mode Line Format - -* Mode Line Data:: The data structure that controls the mode line. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. - -Documentation - -* Documentation Basics:: Good style for doc strings. - Where to put them. How Emacs stores them. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. - -Files - -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into other buffers. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Contents of Directories:: Getting a list of the files in a directory. -* Changing File Attributes:: Renaming files, changing protection, etc. -* File Names:: Decomposing and expanding file names. - -Visiting Files - -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. - -Information about Files - -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A link? -* File Attributes:: How large is it? Any other names? Etc. - -File Names - -* File Name Components:: The directory part of a file name, and the rest. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* Relative File Names:: Some file names are relative to a - current directory. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. - -Backups and Auto-Saving - -* Backup Files:: How backup files are made; how their names - are chosen. -* Auto-Saving:: How auto-save files are made; how their - names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize - what it does. - -Backup Files - -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file - or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. - -Buffers - -* Buffer Basics:: What is a buffer? -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file - is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. -* Read Only Buffers:: Modifying text is not allowed in a - read-only buffer. -* The Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Current Buffer:: Designating a buffer as current - so primitives will access its contents. - -Windows - -* Basic Windows:: Basic information on using windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Displaying Buffers:: Higher-lever functions for displaying a buffer - and choosing a window for it. -* Window Point:: Each window has its own location of point. -* Window Start:: The display-start position controls which text - is on-screen in the window. -* Vertical Scrolling:: Moving text up and down in the window. -* Horizontal Scrolling:: Moving text sideways on the window. -* Size of Window:: Accessing the size of a window. -* Resizing Windows:: Changing the size of a window. -* Window Configurations:: Saving and restoring the state of the screen. - -Frames - -* Creating Frames:: Creating additional frames. -* Multiple Displays:: Creating frames on other X displays. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Frames and Windows:: A frame contains windows; - display of text always works through windows. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other X windows; - lowering it makes the others hide them. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shapes:: Specifying the shape of the mouse pointer. -* X Selections:: Transferring text to and from other X clients. -* Color Names:: Getting the definitions of color names. -* Resources:: Getting resource values from the server. -* Server Data:: Getting info about the X server. - -Positions - -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. - -Motion - -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. - -Markers - -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers:: Finding the marker's buffer or character - position. -* Changing Markers:: Moving the marker to a new buffer or position. -* The Mark:: How ``the mark'' is implemented with a marker. -* The Region:: How to access ``the region''. - -Text - -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* 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. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Sorting:: Functions for sorting parts of the buffer. -* Indentation:: Functions to insert or adjust indentation. -* Columns:: Computing horizontal positions, and using them. -* Case Changes:: Case conversion of parts of the buffer. -* Substitution:: Replacing a given character wherever it appears. -* Registers:: How registers are implemented. Accessing - the text or position stored in a register. - -The Kill Ring - -* 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. - -Indentation - -* 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. - -Searching and Matching - -* String Search:: Search for an exact match. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* Match Data:: Finding out which part of the text matched - various parts of a regexp, after regexp search. -* Saving Match Data:: Saving and restoring this information. -* Standard Regexps:: Useful regexps for finding sentences, pages,... -* Searching and Case:: Case-independent or case-significant searching. - -Regular Expressions - -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. - -Syntax Tables - -* Syntax Descriptors:: How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Standard Syntax Tables:: Syntax tables used by various major modes. -* Syntax Table Internals:: How syntax table information is stored. - -Syntax Descriptors - -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. - -Abbrevs And Abbrev Expansion - -* Abbrev Mode:: Setting up Emacs for abbreviation. -* Tables: Abbrev Tables. Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Files: Abbrev Files. Saving abbrevs in files. -* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. - -Processes - -* 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. -* Network:: Opening network connections. - -Receiving Output from Processes - -* Process Buffers:: If no filter, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Accepting Output:: How to wait until process output arrives. - -Operating System Interface - -* Starting Up:: Customizing Emacs start-up processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* Terminal Input:: Recording terminal input for debugging. -* Terminal Output:: Recording terminal output for debugging. -* Flow Control:: How to turn output flow control on or off. -* Batch Mode:: Running Emacs without terminal interaction. - -Starting Up Emacs - -* 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. - -Getting out of Emacs - -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. - -Emacs Display - -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Where messages are displayed. -* Selective Display:: Hiding part of the buffer text. -* Overlay Arrow:: Display of an arrow to indicate position. -* Temporary Displays:: Displays that go away automatically. -* Waiting:: Forcing display update and waiting for user. -* Blinking:: How Emacs shows the matching open parenthesis. -* Usual Display:: How control characters are displayed. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. - -GNU Emacs Internals - -* Building Emacs:: How to preload Lisp libraries into Emacs. -* Pure Storage:: A kludge to make preloaded Lisp functions sharable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Object Internals:: Data formats of buffers, windows, processes. -* Writing Emacs Primitives:: Writing C code for Emacs. - -Object Internals - -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end menu - -@c ================ Volume 1 ================ - -@include intro.texi -@include objects.texi -@include numbers.texi -@include strings.texi - -@include lists.texi -@include sequences.texi -@include symbols.texi -@include eval.texi - -@include control.texi -@include variables.texi -@include functions.texi -@include macros.texi - -@include loading.texi -@include compile.texi -@include debugging.texi -@include streams.texi - -@include minibuf.texi -@include commands.texi -@include keymaps.texi -@include modes.texi - -@c ================ Beginning of Volume 2 ================ - -@c include help.texi -@c include files.texi -@c include backups.texi -@c include buffers.texi - -@c include windows.texi -@c include frames.texi -@c include positions.texi -@c include markers.texi -@c include text.texi - -@c include searching.texi -@c include syntax.texi -@c include abbrevs.texi - -@c include processes.texi -@c include os.texi -@c include display.texi -@c include calendar.texi - -@c MOVE to Emacs Manual: include misc-modes.texi - -@c appendices - -@c REMOVE this: include non-hacker.texi - -@c include tips.texi -@c include internals.texi -@c include errors.texi -@c include locals.texi -@c include maps.texi -@c include hooks.texi -@c include anti.texi - -@include index-vol1.texi - -@page -@c Print the tables of contents -@summarycontents -@contents -@c That's all - -@bye - - -These words prevent "local variables" above from confusing Emacs. diff --git a/lispref/elisp-vol2.texi b/lispref/elisp-vol2.texi deleted file mode 100644 index d0aaba76925..00000000000 --- a/lispref/elisp-vol2.texi +++ /dev/null @@ -1,1046 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename elisp -@settitle GNU Emacs Lisp Reference Manual: Volume 2 -@smallbook -@c %**end of header - - -@tex -%%%% Experiment with smaller skip before sections and subsections. -%%%% --rjc 30mar92 - -\global\secheadingskip = 17pt plus 6pt minus 3pt -\global\subsecheadingskip = 14pt plus 6pt minus 3pt - -% The defaults are: -% \secheadingskip = 21pt plus 8pt minus 4pt -% \subsecheadingskip = 17pt plus 8pt minus 4pt -@end tex - -@finalout -@c tex -@c \overfullrule=0pt -@c end tex - -@c Start volume 2 chapter numbering on chapter 21; -@c this must be listed as chapno 20. -@tex -\global\chapno=20 -@end tex - -@c ================================================================ -@c Note: I was unable to figure out how to get .aux files copied -@c properly in the time I had. Hence need to copy .aux file before -@c running Tex. --rjc - -@tex - -\message{} -\message{Redefining contents commands...} -\message{} - -% Special @contents command - -% This inputs fixed up table of contents file rather than create new one. -\global\def\contents{% - \startcontents{Table of Contents}% - \input elisp2-toc-ready.toc - \endgroup - \vfill \eject -} - -% Special @summarycontents command -% This inputs fixed up table of contents file rather than create new one. -\global\def\summarycontents{% - \startcontents{Short Contents}% - % - \let\chapentry = \shortchapentry - \let\unnumbchapentry = \shortunnumberedentry - % We want a true roman here for the page numbers. - \secfonts - \let\rm=\shortcontrm \let\bf=\shortcontbf \let\sl=\shortcontsl - \rm - \advance\baselineskip by 1pt % Open it up a little. - \def\secentry ##1##2##3##4{} - \def\unnumbsecentry ##1##2{} - \def\subsecentry ##1##2##3##4##5{} - \def\unnumbsubsecentry ##1##2{} - \def\subsubsecentry ##1##2##3##4##5##6{} - \def\unnumbsubsubsecentry ##1##2{} - \input elisp2-toc-ready.toc - \endgroup - \vfill \eject -} - -\message{} -\message{Formatting special two volume edition...Volume 2...} -\message{} -@end tex -@c ================================================================ - - -@c ==> This `elisp-small.texi' is a `smallbook' version of the manual. - -@c ==== Following are acceptable over and underfull hboxes in TeX ==== - -@c ----- -@c [163] [164] [165] [166]) (loading.texi Chapter 13 [167] [168] [169] -@c Overfull \hbox (20.5428pt too wide) in paragraph at lines 131--131 -@c []@ninett -@c setenv EMAC-SLOAD-PATH .:/user/bil/emacs:/usr/local/lib/emacs/lisp[] -@c ----- -@c (minibuf.texi Chapter 17 [206] [207] [208] [209] [210] [211] [212] [213] -@c [214] [215] -@c Overfull \hbox (2.09094pt too wide) in paragraph at lines 550--560 -@c @texttt map[] @textrm if @textsl require-match @textrm is -@c @texttt nil[]@textrm , or else with the keymap @texttt minibuffer- -@c ----- -@c (locals.texi Appendix @char 68 [533] [534] -@c Underfull \hbox (badness 2512) in paragraph at lines 4--4 -@c []@chaprm Appendix DStandard Buffer-Local - -@c ------------------------------------------------------------------- - -@c -@c Combine indices. -@synindex cp fn -@syncodeindex vr fn -@syncodeindex ky fn -@syncodeindex pg fn -@syncodeindex tp fn -@c oops: texinfo-format-buffer ignores synindex -@c - -@ifinfo -This file documents GNU Emacs Lisp. - -@c The edition number appears in several places in this file -@c and also in the file intro.texi. -This is edition 2.4 of the GNU Emacs Lisp Reference -Manual. It corresponds to Emacs Version 19.29. -@c Please REMEMBER to update edition number in *four* places in this file -@c and also in *one* place in ==> intro.texi <== -@c huh? i only found three real places where the edition is stated, and -@c one place where it is not stated explicitly ("this info file is newer -@c than the foobar edition"). --mew 13sep93 - -Published by the Free Software Foundation -59 Temple Place, Suite 330 -Boston, MA 02111-1307 USA - -Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission notice -identical to this one except for the removal of this paragraph (this -paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation -approved by the Foundation. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU General Public License'' is included exactly as -in the original, and provided that the entire resulting derived work is -distributed under the terms of a permission notice identical to this -one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU General Public License'' may be -included in a translation approved by the Free Software Foundation -instead of in the original English. -@end ifinfo - -@setchapternewpage odd - -@iftex -@shorttitlepage The GNU Emacs Lisp Reference Manual: Volume 2 -@end iftex -@titlepage -@sp 1 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU Emacs Lisp} -@sp 1 -@center @titlefont{Reference Manual} -@sp 2 -@center GNU Emacs Version 19.29 -@center for Unix Users -@sp 1 -@center Edition 2.4, June 1995 -@sp 2 -@center @titlefont{Volume 2} -@sp 3 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. - -@sp 2 -Edition 2.4 @* -Revised for Emacs Version 19.29,@* -June, 1995.@* -@sp 2 -ISBN 1-882114-71-X - -@sp 2 -Published by the Free Software Foundation @* -59 Temple Place, Suite 330 @* -Boston, MA 02111-1307 USA - -@sp 1 -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU General Public License'' is included -exactly as in the original, and provided that the entire resulting -derived work is distributed under the terms of a permission notice -identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU General Public License'' may be -included in a translation approved by the Free Software Foundation -instead of in the original English. - -@sp 2 -Cover art by Etienne Suvasa. -@end titlepage -@page - -@node Top, Copying, (dir), (dir) - -@ifinfo -This Info file contains edition 2.4 of the GNU Emacs Lisp Reference -Manual, corresponding to GNU Emacs version 19.29. -@end ifinfo - -@menu -* Copying:: Conditions for copying and changing GNU Emacs. -* Introduction:: Introduction and conventions used. - -* Lisp Data Types:: Data types of objects in Emacs Lisp. -* Numbers:: Numbers and arithmetic functions. -* Strings and Characters:: Strings, and functions that work on them. -* Lists:: Lists, cons cells, and related functions. -* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. - Certain functions act on any kind of sequence. - The description of vectors is here as well. -* Symbols:: Symbols represent names, uniquely. - -* Evaluation:: How Lisp expressions are evaluated. -* Control Structures:: Conditionals, loops, nonlocal exits. -* Variables:: Using symbols in programs to stand for values. -* Functions:: A function is a Lisp program - that can be invoked from other functions. -* Macros:: Macros are a way to extend the Lisp language. - -* Loading:: Reading files of Lisp code into Lisp. -* Byte Compilation:: Compilation makes programs run faster. -* Debugging:: Tools and tips for debugging Lisp programs. - -* Read and Print:: Converting Lisp objects to text and back. -* Minibuffers:: Using the minibuffer to read input. -* Command Loop:: How the editor command loop works, - and how you can call its subroutines. -* Keymaps:: Defining the bindings from keys to commands. -* Modes:: Defining major and minor modes. -* Documentation:: Writing and using documentation strings. - -* Files:: Accessing files. -* Backups and Auto-Saving:: Controlling how backups and auto-save - files are made. -* Buffers:: Creating and using buffer objects. -* Windows:: Manipulating windows and displaying buffers. -* Frames:: Making multiple X windows. -* Positions:: Buffer positions and motion functions. -* Markers:: Markers represent positions and update - automatically when the text is changed. - -* Text:: Examining and changing text in buffers. -* Searching and Matching:: Searching buffers for strings or regexps. -* Syntax Tables:: The syntax table controls word and list parsing. -* Abbrevs:: How Abbrev mode works, and its data structures. - -* Processes:: Running and communicating with subprocesses. -* System Interface:: Getting the user id, system type, environment - variables, and other such things. -* Display:: Parameters controlling screen usage. - The bell. Waiting for input. -* Calendar:: Customizing the calendar and diary. - -Appendices - -* Tips:: Advice for writing Lisp programs. -* GNU Emacs Internals:: Building and dumping Emacs; - internal data structures. -* Standard Errors:: List of all error symbols. -* Standard Buffer-Local Variables:: List of variables local in all buffers. -* Standard Keymaps:: List of standard keymaps. -* Standard Hooks:: List of standard hook variables. - -* Index:: Index including concepts, functions, variables, - and other terms. - - --- The Detailed Node Listing --- - -Here are other nodes that are inferiors of those already listed, -mentioned here so you can get to them in one step: - -Introduction - -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Acknowledgements:: The authors, editors, and sponsors of this manual. - -Conventions - -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use for examples that print output. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. - -Format of Descriptions - -* A Sample Function Description:: -* A Sample Variable Description:: - -Lisp Data Types - -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. - -Programming Types - -* Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Symbol Type:: A multi-use object that refers to a function, - variable, property list, or itself. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. - -List Type - -* Dotted Pair Notation:: An alternative syntax for lists. -* Association List Type:: A specially constructed list. - -Editing Types - -* Buffer Type:: The basic object of editing. -* Window Type:: What makes buffers visible. -* Window Configuration Type::Save what the screen looks like. -* Marker Type:: A position in a buffer. -* Process Type:: A process running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Syntax Table Type:: What a character means. - -Numbers - -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Bitwise Operations:: Logical and, or, not, shifting. -* Numeric Conversions:: Converting float to integer and vice versa. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. - -Strings and Characters - -* String Basics:: Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting characters or strings and vice versa. -* Formatting Strings:: @code{format}: Emacs's analog of @code{printf}. -* Character Case:: Case conversion functions. - -Lists - -* 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. - -Modifying Existing List Structure - -* 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. - -Sequences, Arrays, and Vectors - -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Functions specifically for vectors. - -Symbols - -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Property Lists:: Each symbol has a property list - for recording miscellaneous information. - -Evaluation - -* 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). - -Kinds of Forms - -* 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 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. - -Control Structures - -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. - -Nonlocal Exits - -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an - error happens. - -Errors - -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. - -Variables - -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. - -Scoping Rules for Variable Bindings - -* Scope:: Scope means where in the program a value - is visible. Comparison with other languages. -* Extent:: Extent means how long in time a value exists. -* Impl of Scope:: Two ways to implement dynamic scoping. -* Using Scoping:: How to use dynamic scoping carefully and - avoid problems. - -Buffer-Local Variables - -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own local values. - -Functions - -* What Is a Function:: Lisp functions vs primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda-expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how - functions work. - -Lambda Expressions - -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. - -Macros - -* 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. - -Loading - -* How Programs Do Loading:: The @code{load} function and others. -* Autoload:: Setting up a function to autoload. -* Named Features:: Loading a library if it isn't already loaded. -* Repeated Loading:: Precautions about loading a file twice. - -Byte Compilation - -* Compilation Functions:: Byte compilation functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. - -Debugging Lisp Programs - -* 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. - -The Lisp Debugger - -* Error Debugging:: Entering the debugger when an error happens. -* 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. - -Debugging Invalid Lisp Syntax - -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. - -Reading and Printing Lisp Objects - -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as - input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as - output streams. -* Output Functions:: Functions to print Lisp objects as text. - -Minibuffers - -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Minibuffer Misc:: Various customization hooks and variables. - -Completion - -* Basic Completion:: Low-level functions for completing strings. - (These are too low level to use the minibuffer.) -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer name, file name, etc.) -* Reading File Names:: Using completion to read file names. -* Programmed Completion:: Finding the completions for a given file name. - -Command Loop - -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. - -Defining Commands - -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. - -Keymaps - -* 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 for X windows - or for use from the terminal. -* Active Keymaps:: Each buffer has a local keymap - to override the standard (global) bindings. - Each 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. - -Major and Minor Modes - -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Hooks:: How to use hooks; how to write code that - provides hooks. - -Major Modes - -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Example Major Modes:: Text mode and Lisp modes. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. - -Minor Modes - -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. - -Mode Line Format - -* Mode Line Data:: The data structure that controls the mode line. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. - -Documentation - -* Documentation Basics:: Good style for doc strings. - Where to put them. How Emacs stores them. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. - -Files - -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into other buffers. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Contents of Directories:: Getting a list of the files in a directory. -* Changing File Attributes:: Renaming files, changing protection, etc. -* File Names:: Decomposing and expanding file names. - -Visiting Files - -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. - -Information about Files - -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A link? -* File Attributes:: How large is it? Any other names? Etc. - -File Names - -* File Name Components:: The directory part of a file name, and the rest. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* Relative File Names:: Some file names are relative to a - current directory. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. - -Backups and Auto-Saving - -* Backup Files:: How backup files are made; how their names - are chosen. -* Auto-Saving:: How auto-save files are made; how their - names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize - what it does. - -Backup Files - -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file - or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. - -Buffers - -* Buffer Basics:: What is a buffer? -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file - is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. -* Read Only Buffers:: Modifying text is not allowed in a - read-only buffer. -* The Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Current Buffer:: Designating a buffer as current - so primitives will access its contents. - -Windows - -* Basic Windows:: Basic information on using windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Displaying Buffers:: Higher-lever functions for displaying a buffer - and choosing a window for it. -* Window Point:: Each window has its own location of point. -* Window Start:: The display-start position controls which text - is on-screen in the window. -* Vertical Scrolling:: Moving text up and down in the window. -* Horizontal Scrolling:: Moving text sideways on the window. -* Size of Window:: Accessing the size of a window. -* Resizing Windows:: Changing the size of a window. -* Window Configurations:: Saving and restoring the state of the screen. - -Frames - -* Creating Frames:: Creating additional frames. -* Multiple Displays:: Creating frames on other X displays. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Frames and Windows:: A frame contains windows; - display of text always works through windows. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other X windows; - lowering it makes the others hide them. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shapes:: Specifying the shape of the mouse pointer. -* X Selections:: Transferring text to and from other X clients. -* Color Names:: Getting the definitions of color names. -* Resources:: Getting resource values from the server. -* Server Data:: Getting info about the X server. - -Positions - -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. - -Motion - -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. - -Markers - -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers:: Finding the marker's buffer or character - position. -* Changing Markers:: Moving the marker to a new buffer or position. -* The Mark:: How ``the mark'' is implemented with a marker. -* The Region:: How to access ``the region''. - -Text - -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* 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. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Sorting:: Functions for sorting parts of the buffer. -* Indentation:: Functions to insert or adjust indentation. -* Columns:: Computing horizontal positions, and using them. -* Case Changes:: Case conversion of parts of the buffer. -* Substitution:: Replacing a given character wherever it appears. -* Registers:: How registers are implemented. Accessing - the text or position stored in a register. - -The Kill Ring - -* 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. - -Indentation - -* 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. - -Searching and Matching - -* String Search:: Search for an exact match. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* Match Data:: Finding out which part of the text matched - various parts of a regexp, after regexp search. -* Saving Match Data:: Saving and restoring this information. -* Standard Regexps:: Useful regexps for finding sentences, pages,... -* Searching and Case:: Case-independent or case-significant searching. - -Regular Expressions - -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. - -Syntax Tables - -* Syntax Descriptors:: How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Standard Syntax Tables:: Syntax tables used by various major modes. -* Syntax Table Internals:: How syntax table information is stored. - -Syntax Descriptors - -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. - -Abbrevs And Abbrev Expansion - -* Abbrev Mode:: Setting up Emacs for abbreviation. -* Tables: Abbrev Tables. Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Files: Abbrev Files. Saving abbrevs in files. -* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. - -Processes - -* 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. -* Network:: Opening network connections. - -Receiving Output from Processes - -* Process Buffers:: If no filter, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Accepting Output:: How to wait until process output arrives. - -Operating System Interface - -* Starting Up:: Customizing Emacs start-up processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* Terminal Input:: Recording terminal input for debugging. -* Terminal Output:: Recording terminal output for debugging. -* Flow Control:: How to turn output flow control on or off. -* Batch Mode:: Running Emacs without terminal interaction. - -Starting Up Emacs - -* 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. - -Getting out of Emacs - -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. - -Emacs Display - -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Where messages are displayed. -* Selective Display:: Hiding part of the buffer text. -* Overlay Arrow:: Display of an arrow to indicate position. -* Temporary Displays:: Displays that go away automatically. -* Waiting:: Forcing display update and waiting for user. -* Blinking:: How Emacs shows the matching open parenthesis. -* Usual Display:: How control characters are displayed. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. - -GNU Emacs Internals - -* Building Emacs:: How to preload Lisp libraries into Emacs. -* Pure Storage:: A kludge to make preloaded Lisp functions sharable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Object Internals:: Data formats of buffers, windows, processes. -* Writing Emacs Primitives:: Writing C code for Emacs. - -Object Internals - -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end menu - -@c ================ Volume 1 ================ - -@c include intro.texi -@c include objects.texi -@c include numbers.texi -@c include strings.texi - -@c include lists.texi -@c include sequences.texi -@c include symbols.texi -@c include eval.texi - -@c include control.texi -@c include variables.texi -@c include functions.texi -@c include macros.texi - -@c include loading.texi -@c include compile.texi -@c include debugging.texi -@c include streams.texi - -@c include minibuf.texi -@c include commands.texi -@c include keymaps.texi -@c include modes.texi - -@c ================ Beginning of Volume 2 ================ - -@include help.texi -@include files.texi -@include backups.texi -@include buffers.texi - -@include windows.texi -@include frames.texi -@include positions.texi -@include markers.texi -@include text.texi - -@include searching.texi -@include syntax.texi -@include abbrevs.texi - -@include processes.texi -@include os.texi -@include display.texi -@include calendar.texi - -@c MOVE to Emacs Manual: include misc-modes.texi - -@c appendices - -@c REMOVE this: include non-hacker.texi - -@include tips.texi -@include internals.texi -@include errors.texi -@include locals.texi -@include maps.texi -@include hooks.texi - -@include index-vol2.texi - -@page -@c Print the tables of contents -@summarycontents -@contents -@c That's all - -@bye - - -These words prevent "local variables" above from confusing Emacs. diff --git a/lispref/elisp.texi b/lispref/elisp.texi deleted file mode 100644 index adb16771ebf..00000000000 --- a/lispref/elisp.texi +++ /dev/null @@ -1,942 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename elisp -@settitle GNU Emacs Lisp Reference Manual -@c %**end of header - -@ifinfo -This version is the edition 2.4.2 of the GNU Emacs Lisp -Reference Manual. It corresponds to Emacs Version 19.34. -@c Please REMEMBER to update edition number in *four* places in this file -@c and also in *one* place in intro.texi - -Published by the Free Software Foundation -59 Temple Place, Suite 330 -Boston, MA 02111-1307 USA - -Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission notice -identical to this one except for the removal of this paragraph (this -paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that this permission notice may be stated in a translation -approved by the Foundation. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU General Public License'' is included exactly as -in the original, and provided that the entire resulting derived work is -distributed under the terms of a permission notice identical to this -one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU General Public License'' may be -included in a translation approved by the Free Software Foundation -instead of in the original English. -@end ifinfo - -@c Combine indices. -@synindex cp fn -@syncodeindex vr fn -@syncodeindex ky fn -@syncodeindex pg fn -@syncodeindex tp fn - -@setchapternewpage odd -@finalout - -@titlepage -@title GNU Emacs Lisp Reference Manual -@subtitle GNU Emacs Version 19 -@subtitle for Unix Users -@c The edition number appears in several places in this file -@c and also in the file intro.texi. -@subtitle Revision 2.4.2, December 1996 - -@author by Bil Lewis, Dan LaLiberte, Richard Stallman -@author and the GNU Manual Group -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996 Free Software Foundation, Inc. - -@sp 2 -Edition 2.4.2 @* -Revised for Emacs Version 19.34,@* -July 1996.@* -@sp 2 -ISBN 1-882114-71-X - -@sp 2 -Published by the Free Software Foundation @* -59 Temple Place, Suite 330@* -Boston, MA 02111-1307 USA - -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU General Public License'' is included -exactly as in the original, and provided that the entire resulting -derived work is distributed under the terms of a permission notice -identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU General Public License'' may be -included in a translation approved by the Free Software Foundation -instead of in the original English. - -Cover art by Etienne Suvasa. -@end titlepage -@page - -@node Top, Copying, (dir), (dir) - -@ifinfo -This Info file contains edition 2.4.2 of the GNU Emacs Lisp -Reference Manual, corresponding to GNU Emacs version 19.34. -@end ifinfo - -@menu -* Copying:: Conditions for copying and changing GNU Emacs. -* Introduction:: Introduction and conventions used. - -* Lisp Data Types:: Data types of objects in Emacs Lisp. -* Numbers:: Numbers and arithmetic functions. -* Strings and Characters:: Strings, and functions that work on them. -* Lists:: Lists, cons cells, and related functions. -* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences. - Certain functions act on any kind of sequence. - The description of vectors is here as well. -* Symbols:: Symbols represent names, uniquely. - -* Evaluation:: How Lisp expressions are evaluated. -* Control Structures:: Conditionals, loops, nonlocal exits. -* Variables:: Using symbols in programs to stand for values. -* Functions:: A function is a Lisp program - that can be invoked from other functions. -* Macros:: Macros are a way to extend the Lisp language. - -* Loading:: Reading files of Lisp code into Lisp. -* Byte Compilation:: Compilation makes programs run faster. -* Debugging:: Tools and tips for debugging Lisp programs. - -* Read and Print:: Converting Lisp objects to text and back. -* Minibuffers:: Using the minibuffer to read input. -* Command Loop:: How the editor command loop works, - and how you can call its subroutines. -* Keymaps:: Defining the bindings from keys to commands. -* Modes:: Defining major and minor modes. -* Documentation:: Writing and using documentation strings. - -* Files:: Accessing files. -* Backups and Auto-Saving:: Controlling how backups and auto-save - files are made. -* Buffers:: Creating and using buffer objects. -* Windows:: Manipulating windows and displaying buffers. -* Frames:: Making multiple X windows. -* Positions:: Buffer positions and motion functions. -* Markers:: Markers represent positions and update - automatically when the text is changed. - -* Text:: Examining and changing text in buffers. -* Searching and Matching:: Searching buffers for strings or regexps. -* Syntax Tables:: The syntax table controls word and list parsing. -* Abbrevs:: How Abbrev mode works, and its data structures. - -* Processes:: Running and communicating with subprocesses. -* System Interface:: Getting the user id, system type, environment - variables, and other such things. -* Display:: Parameters controlling screen usage. - The bell. Waiting for input. -* Calendar:: Customizing the calendar and diary. - -Appendices - -* Tips:: Advice for writing Lisp programs. -* GNU Emacs Internals:: Building and dumping Emacs; - internal data structures. -* Standard Errors:: List of all error symbols. -* Standard Buffer-Local Variables:: List of variables local in all buffers. -* Standard Keymaps:: List of standard keymaps. -* Standard Hooks:: List of standard hook variables. - -* Index:: Index including concepts, functions, variables, - and other terms. - - --- The Detailed Node Listing --- - -Here are other nodes that are inferiors of those already listed, -mentioned here so you can get to them in one step: - -Introduction - -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Acknowledgements:: The authors, editors, and sponsors of this manual. - -Conventions - -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use for examples that print output. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. - -Format of Descriptions - -* A Sample Function Description:: -* A Sample Variable Description:: - -Lisp Data Types - -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. - -Programming Types - -* Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Symbol Type:: A multi-use object that refers to a function, - variable, property list, or itself. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. - -List Type - -* Dotted Pair Notation:: An alternative syntax for lists. -* Association List Type:: A specially constructed list. - -Editing Types - -* Buffer Type:: The basic object of editing. -* Window Type:: What makes buffers visible. -* Window Configuration Type::Save what the screen looks like. -* Marker Type:: A position in a buffer. -* Process Type:: A process running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Syntax Table Type:: What a character means. - -Numbers - -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Bitwise Operations:: Logical and, or, not, shifting. -* Numeric Conversions:: Converting float to integer and vice versa. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. - -Strings and Characters - -* String Basics:: Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting characters or strings and vice versa. -* Formatting Strings:: @code{format}: Emacs's analog of @code{printf}. -* Character Case:: Case conversion functions. - -Lists - -* 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. - -Modifying Existing List Structure - -* 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. - -Sequences, Arrays, and Vectors - -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Functions specifically for vectors. - -Symbols - -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Property Lists:: Each symbol has a property list - for recording miscellaneous information. - -Evaluation - -* 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). - -Kinds of Forms - -* 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 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. - -Control Structures - -* Sequencing:: Evaluation in textual order. -* Conditionals:: @code{if}, @code{cond}. -* Combining Conditions:: @code{and}, @code{or}, @code{not}. -* Iteration:: @code{while} loops. -* Nonlocal Exits:: Jumping out of a sequence. - -Nonlocal Exits - -* Catch and Throw:: Nonlocal exits for the program's own purposes. -* Examples of Catch:: Showing how such nonlocal exits can be written. -* Errors:: How errors are signaled and handled. -* Cleanups:: Arranging to run a cleanup form if an - error happens. - -Errors - -* Signaling Errors:: How to report an error. -* Processing of Errors:: What Emacs does when you report an error. -* Handling Errors:: How you can trap errors and continue execution. -* Error Symbols:: How errors are classified for trapping them. - -Variables - -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. - -Scoping Rules for Variable Bindings - -* Scope:: Scope means where in the program a value - is visible. Comparison with other languages. -* Extent:: Extent means how long in time a value exists. -* Impl of Scope:: Two ways to implement dynamic scoping. -* Using Scoping:: How to use dynamic scoping carefully and - avoid problems. - -Buffer-Local Variables - -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own local values. - -Functions - -* What Is a Function:: Lisp functions vs primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda-expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how - functions work. - -Lambda Expressions - -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. - -Macros - -* 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. - -Loading - -* How Programs Do Loading:: The @code{load} function and others. -* Autoload:: Setting up a function to autoload. -* Named Features:: Loading a library if it isn't already loaded. -* Repeated Loading:: Precautions about loading a file twice. - -Byte Compilation - -* Compilation Functions:: Byte compilation functions. -* Disassembly:: Disassembling byte-code; how to read byte-code. - -Debugging Lisp Programs - -* 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. - -The Lisp Debugger - -* Error Debugging:: Entering the debugger when an error happens. -* 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. - -Debugging Invalid Lisp Syntax - -* Excess Open:: How to find a spurious open paren or missing close. -* Excess Close:: How to find a spurious close paren or missing open. - -Reading and Printing Lisp Objects - -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as - input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as - output streams. -* Output Functions:: Functions to print Lisp objects as text. - -Minibuffers - -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Minibuffer Misc:: Various customization hooks and variables. - -Completion - -* Basic Completion:: Low-level functions for completing strings. - (These are too low level to use the minibuffer.) -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer name, file name, etc.) -* Reading File Names:: Using completion to read file names. -* Programmed Completion:: Finding the completions for a given file name. - -Command Loop - -* Command Overview:: How the command loop reads commands. -* Defining Commands:: Specifying how a function should read arguments. -* Interactive Call:: Calling a command, so that it will read arguments. -* Command Loop Info:: Variables set by the command loop for you to examine. -* Input Events:: What input looks like when you read it. -* Reading Input:: How to read input events from the keyboard or mouse. -* Waiting:: Waiting for user input or elapsed time. -* Quitting:: How @kbd{C-g} works. How to catch or defer quitting. -* Prefix Command Arguments:: How the commands to set prefix args work. -* Recursive Editing:: Entering a recursive edit, - and why you usually shouldn't. -* Disabling Commands:: How the command loop handles disabled commands. -* Command History:: How the command history is set up, and how accessed. -* Keyboard Macros:: How keyboard macros are implemented. - -Defining Commands - -* Using Interactive:: General rules for @code{interactive}. -* Interactive Codes:: The standard letter-codes for reading arguments - in various ways. -* Interactive Examples:: Examples of how to read interactive arguments. - -Keymaps - -* 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 for X windows - or for use from the terminal. -* Active Keymaps:: Each buffer has a local keymap - to override the standard (global) bindings. - Each 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. - -Major and Minor Modes - -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Hooks:: How to use hooks; how to write code that - provides hooks. - -Major Modes - -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Example Major Modes:: Text mode and Lisp modes. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. - -Minor Modes - -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. - -Mode Line Format - -* Mode Line Data:: The data structure that controls the mode line. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. - -Documentation - -* Documentation Basics:: Good style for doc strings. - Where to put them. How Emacs stores them. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. - -Files - -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into other buffers. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Contents of Directories:: Getting a list of the files in a directory. -* Changing File Attributes:: Renaming files, changing protection, etc. -* File Names:: Decomposing and expanding file names. - -Visiting Files - -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. - -Information about Files - -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A link? -* File Attributes:: How large is it? Any other names? Etc. - -File Names - -* File Name Components:: The directory part of a file name, and the rest. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* Relative File Names:: Some file names are relative to a - current directory. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. - -Backups and Auto-Saving - -* Backup Files:: How backup files are made; how their names - are chosen. -* Auto-Saving:: How auto-save files are made; how their - names are chosen. -* Reverting:: @code{revert-buffer}, and how to customize - what it does. - -Backup Files - -* Making Backups:: How Emacs makes backup files, and when. -* Rename or Copy:: Two alternatives: renaming the old file - or copying it. -* Numbered Backups:: Keeping multiple backups for each source file. -* Backup Names:: How backup file names are computed; customization. - -Buffers - -* Buffer Basics:: What is a buffer? -* Buffer Names:: Accessing and changing buffer names. -* Buffer File Name:: The buffer file name indicates which file - is visited. -* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. -* Modification Time:: Determining whether the visited file was changed - ``behind Emacs's back''. -* Read Only Buffers:: Modifying text is not allowed in a - read-only buffer. -* The Buffer List:: How to look at all the existing buffers. -* Creating Buffers:: Functions that create buffers. -* Killing Buffers:: Buffers exist until explicitly killed. -* Current Buffer:: Designating a buffer as current - so primitives will access its contents. - -Windows - -* Basic Windows:: Basic information on using windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Displaying Buffers:: Higher-lever functions for displaying a buffer - and choosing a window for it. -* Window Point:: Each window has its own location of point. -* Window Start:: The display-start position controls which text - is on-screen in the window. -* Vertical Scrolling:: Moving text up and down in the window. -* Scrolling Hooks:: Hooks that run when you scroll a window. -* Horizontal Scrolling:: Moving text sideways on the window. -* Size of Window:: Accessing the size of a window. -* Resizing Windows:: Changing the size of a window. -* Window Configurations:: Saving and restoring the state of the screen. - -Frames - -* Creating Frames:: Creating additional frames. -* Multiple Displays:: Creating frames on other X displays. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Frames and Windows:: A frame contains windows; - display of text always works through windows. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other X windows; - lowering it makes the others hide them. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shapes:: Specifying the shape of the mouse pointer. -* X Selections:: Transferring text to and from other X clients. -* Color Names:: Getting the definitions of color names. -* Resources:: Getting resource values from the server. -* Server Data:: Getting info about the X server. - -Positions - -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. - -Motion - -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. - -Markers - -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers:: Finding the marker's buffer or character - position. -* Changing Markers:: Moving the marker to a new buffer or position. -* The Mark:: How ``the mark'' is implemented with a marker. -* The Region:: How to access ``the region''. - -Text - -* Near Point:: Examining text in the vicinity of point. -* Buffer Contents:: Examining text in a general fashion. -* 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. -* Auto Filling:: How auto-fill mode is implemented to break lines. -* Filling:: Functions for explicit filling. -* Margins:: How to specify margins for filling commands. -* Sorting:: Functions for sorting parts of the buffer. -* Indentation:: Functions to insert or adjust indentation. -* Columns:: Computing horizontal positions, and using them. -* 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. -* Transposition:: Swapping two portions of a buffer. -* 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. - -The Kill Ring - -* 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. - -Indentation - -* 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. - -Text Properties - -* 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. -* Format Properties:: Properties for representing formatting of text. -* Sticky Properties:: How inserted text gets properties from - neighboring text. -* Saving Properties:: Saving text properties in files, and reading - them back. -* Lazy Properties:: Computing text properties in a lazy fashion - only when text is examined. -* Not Intervals:: Why text properties do not use - Lisp-visible text intervals. - -Searching and Matching - -* String Search:: Search for an exact match. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* Match Data:: Finding out which part of the text matched - various parts of a regexp, after regexp search. -* Saving Match Data:: Saving and restoring this information. -* Standard Regexps:: Useful regexps for finding sentences, pages,... -* Searching and Case:: Case-independent or case-significant searching. - -Regular Expressions - -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. - -Syntax Tables - -* Syntax Descriptors:: How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Standard Syntax Tables:: Syntax tables used by various major modes. -* Syntax Table Internals:: How syntax table information is stored. - -Syntax Descriptors - -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. - -Abbrevs And Abbrev Expansion - -* Abbrev Mode:: Setting up Emacs for abbreviation. -* Tables: Abbrev Tables. Creating and working with abbrev tables. -* Defining Abbrevs:: Specifying abbreviations and their expansions. -* Files: Abbrev Files. Saving abbrevs in files. -* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines. -* Standard Abbrev Tables:: Abbrev tables used by various major modes. - -Processes - -* 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. -* Network:: Opening network connections. - -Receiving Output from Processes - -* Process Buffers:: If no filter, output is put in a buffer. -* Filter Functions:: Filter functions accept output from the process. -* Accepting Output:: How to wait until process output arrives. - -Operating System Interface - -* Starting Up:: Customizing Emacs start-up processing. -* Getting Out:: How exiting works (permanent or temporary). -* System Environment:: Distinguish the name and kind of system. -* Terminal Input:: Recording terminal input for debugging. -* Terminal Output:: Recording terminal output for debugging. -* Flow Control:: How to turn output flow control on or off. -* Batch Mode:: Running Emacs without terminal interaction. - -Starting Up Emacs - -* 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. - -Getting out of Emacs - -* Killing Emacs:: Exiting Emacs irreversibly. -* Suspending Emacs:: Exiting Emacs reversibly. - -Emacs Display - -* Refresh Screen:: Clearing the screen and redrawing everything on it. -* Truncation:: Folding or wrapping long text lines. -* The Echo Area:: Where messages are displayed. -* Selective Display:: Hiding part of the buffer text. -* Overlay Arrow:: Display of an arrow to indicate position. -* Temporary Displays:: Displays that go away automatically. -* Waiting:: Forcing display update and waiting for user. -* Blinking:: How Emacs shows the matching open parenthesis. -* Usual Display:: How control characters are displayed. -* Beeping:: Audible signal to the user. -* Window Systems:: Which window system is being used. - -GNU Emacs Internals - -* Building Emacs:: How to preload Lisp libraries into Emacs. -* Pure Storage:: A kludge to make preloaded Lisp functions sharable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Object Internals:: Data formats of buffers, windows, processes. -* Writing Emacs Primitives:: Writing C code for Emacs. - -Object Internals - -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end menu - -@include intro.texi -@include objects.texi -@include numbers.texi -@include strings.texi - -@include lists.texi -@include sequences.texi -@include symbols.texi -@include eval.texi - -@include control.texi -@include variables.texi -@include functions.texi -@include macros.texi - -@include loading.texi -@include compile.texi -@include debugging.texi -@include streams.texi - -@include minibuf.texi -@include commands.texi -@include keymaps.texi -@include modes.texi - -@include help.texi -@include files.texi -@include backups.texi -@include buffers.texi - -@include windows.texi -@include frames.texi -@include positions.texi -@include markers.texi -@include text.texi - -@include searching.texi -@include syntax.texi -@include abbrevs.texi - -@include processes.texi -@include os.texi -@include display.texi -@include calendar.texi - -@c MOVE to Emacs Manual: include misc-modes.texi - -@c appendices - -@c REMOVE this: include non-hacker.texi - -@include tips.texi -@include internals.texi -@include errors.texi -@include locals.texi -@include maps.texi -@include hooks.texi - -@include index.texi - -@c Print the tables of contents -@summarycontents -@contents -@c That's all - -@bye - - -These words prevent "local variables" above from confusing Emacs. diff --git a/lispref/errors.texi b/lispref/errors.texi deleted file mode 100644 index aa3dde754d6..00000000000 --- a/lispref/errors.texi +++ /dev/null @@ -1,158 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/errors -@node Standard Errors, Standard Buffer-Local Variables, GNU Emacs Internals, Top -@appendix Standard Errors - - Here is the complete list of the error symbols in standard Emacs, -grouped by concept. The list includes each symbol's message (on the -@code{error-message} property of the symbol) and a cross reference to a -description of how the error can occur. - - Each error symbol has an @code{error-conditions} property that is a -list of symbols. Normally this list includes the error symbol itself -and the symbol @code{error}. Occasionally it includes additional -symbols, which are intermediate classifications, narrower than -@code{error} but broader than a single error symbol. For example, all -the errors in accessing files have the condition @code{file-error}. - - As a special exception, the error symbol @code{quit} does not have the -condition @code{error}, because quitting is not considered an error. - - @xref{Errors}, for an explanation of how errors are generated and -handled. - -@table @code -@item @var{symbol} -@var{string}; @var{reference}. - -@item error -@code{"error"}@* -@xref{Errors}. - -@item quit -@code{"Quit"}@* -@xref{Quitting}. - -@item args-out-of-range -@code{"Args out of range"}@* -@xref{Sequences Arrays Vectors}. - -@item arith-error -@code{"Arithmetic error"}@* -See @code{/} and @code{%} in @ref{Numbers}. - -@item beginning-of-buffer -@code{"Beginning of buffer"}@* -@xref{Motion}. - -@item buffer-read-only -@code{"Buffer is read-only"}@* -@xref{Read Only Buffers}. - -@item cyclic-function-indirection -@code{"Symbol's chain of function indirections contains a@* -loop"}@* -@xref{Function Indirection}. - -@item end-of-buffer -@code{"End of buffer"}@* -@xref{Motion}. - -@item end-of-file -@code{"End of file during parsing"}@* -This is not a @code{file-error}.@* -@xref{Input Functions}. - -@item file-error -This error and its subcategories do not have error-strings, because the -error message is constructed from the data items alone when the error -condition @code{file-error} is present.@* -@xref{Files}. - -@item file-locked -This is a @code{file-error}.@* -@xref{File Locks}. - -@item file-already-exists -This is a @code{file-error}.@* -@xref{Writing to Files}. - -@item file-supersession -This is a @code{file-error}.@* -@xref{Modification Time}. - -@item invalid-function -@code{"Invalid function"}@* -@xref{Classifying Lists}. - -@item invalid-read-syntax -@code{"Invalid read syntax"}@* -@xref{Input Functions}. - -@item invalid-regexp -@code{"Invalid regexp"}@* -@xref{Regular Expressions}. - -@item no-catch -@code{"No catch for tag"}@* -@xref{Catch and Throw}. - -@item search-failed -@code{"Search failed"}@* -@xref{Searching and Matching}. - -@item setting-constant -@code{"Attempt to set a constant symbol"}@* -The values of the symbols @code{nil} and @code{t} -may not be changed.@* -@xref{Constant Variables, , Variables that Never Change}. - -@item undefined-color -@code{"Undefined color"}@* -@xref{Color Names}. - -@item void-function -@code{"Symbol's function definition is void"}@* -@xref{Function Cells}. - -@item void-variable -@code{"Symbol's value as variable is void"}@* -@xref{Accessing Variables}. - -@item wrong-number-of-arguments -@code{"Wrong number of arguments"}@* -@xref{Classifying Lists}. - -@item wrong-type-argument -@code{"Wrong type argument"}@* -@xref{Type Predicates}. -@end table - - These error types, which are all classified as special cases of -@code{arith-error}, can occur on certain systems for invalid use of -mathematical functions. - -@table @code -@item domain-error -@code{"Arithmetic domain error"}@* -@xref{Math Functions}. - -@item overflow-error -@code{"Arithmetic overflow error"}@* -@xref{Math Functions}. - -@item range-error -@code{"Arithmetic range error"}@* -@xref{Math Functions}. - -@item singularity-error -@code{"Arithmetic singularity error"}@* -@xref{Math Functions}. - -@item underflow-error -@code{"Arithmetic underflow error"}@* -@xref{Math Functions}. -@end table diff --git a/lispref/eval.texi b/lispref/eval.texi deleted file mode 100644 index 494a8145baf..00000000000 --- a/lispref/eval.texi +++ /dev/null @@ -1,706 +0,0 @@ -@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 that computes -the value of an expression that 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 that 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}. - - Evaluation of a function call ultimately calls the function specified -in it. @xref{Functions}. The execution of the function may itself work -by evaluating the function definition; or the function may be a Lisp -primitive implemented in C, or it may be a byte-compiled function -(@pxref{Byte Compilation}). - -@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 that 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)}. - - The details of what evaluation means for each kind of form are -described below (@pxref{Forms}). - -@node Eval -@section Eval -@c ??? Perhaps this should be the last section in the chapter. - - 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. - - @strong{Note:} it is generally cleaner and more flexible to call -functions that are stored in data structures, rather than to evaluate -expressions stored in data structures. Using functions provides the -ability to pass information to them as arguments. - - 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 -(eval 'foo) - @result{} bar -@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 - -@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 -during the evaluation. - -You can use the variable @code{load-read-function} to specify a function -for @code{eval-region} to use instead of @code{read} for reading -expressions. @xref{How Programs Do Loading}. - -@code{eval-region} always returns @code{nil}. -@end deffn - -@cindex evaluation of buffer contents -@deffn Command eval-current-buffer &optional stream -This is like @code{eval-region} except that it operates on the whole -buffer. -@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 -internal uses of those functions, such as for calling the functions -mentioned in Lisp expressions, 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 that 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-most-recent} -;; @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. 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}; you cannot set or bind them to any other values. 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 -Executing the function itself evaluates its body; 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 in evaluating a function call is to evaluate the -remaining elements of the list from left to right. 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. - - Ordinary evaluation of a macro call finishes by evaluating the -expansion. However, the macro expansion is not necessarily evaluated -right away, or at all, because other programs also expand macro calls, -and they may or may not evaluate the expansions. - - 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 computed when the expansion is computed. - - 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, as written, -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.) - -@defspec quote object -This special form returns @var{object}, without evaluating it. -@end defspec - -@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 - - Other quoting constructs include @code{function} (@pxref{Anonymous -Functions}), which causes an anonymous lambda expression written in Lisp -to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote -only part of a list, while computing and substituting other parts. diff --git a/lispref/files.texi b/lispref/files.texi deleted file mode 100644 index db196c8f7ee..00000000000 --- a/lispref/files.texi +++ /dev/null @@ -1,2254 +0,0 @@ -@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/files -@node Files, Backups and Auto-Saving, Documentation, Top -@comment node-name, next, previous, up -@chapter Files - - In Emacs, you can find, create, view, save, and otherwise work with -files and file directories. This chapter describes most of the -file-related functions of Emacs Lisp, but a few others are described in -@ref{Buffers}, and those related to backups and auto-saving are -described in @ref{Backups and Auto-Saving}. - - Many of the file functions take one or more arguments that are file -names. A file name is actually a string. Most of these functions -expand file name arguments using @code{expand-file-name}, so that -@file{~} is handled correctly, as are relative file names (including -@samp{../}). These functions don't recognize environment variable -substitutions such as @samp{$HOME}. @xref{File Name Expansion}. - -@menu -* Visiting Files:: Reading files into Emacs buffers for editing. -* Saving Buffers:: Writing changed buffers back into files. -* Reading from Files:: Reading files into buffers without visiting. -* Writing to Files:: Writing new files from parts of buffers. -* File Locks:: Locking and unlocking files, to prevent - simultaneous editing by two people. -* Information about Files:: Testing existence, accessibility, size of files. -* Changing File Attributes:: Renaming files, changing protection, etc. -* File Names:: Decomposing and expanding file names. -* Contents of Directories:: Getting a list of the files in a directory. -* Create/Delete Dirs:: Creating and Deleting Directories. -* Magic File Names:: Defining "magic" special handling - for certain file names. -* Format Conversion:: Conversion to and from various file formats. -* Files and MS-DOS:: Distinguishing text and binary files on MS-DOS. -@end menu - -@node Visiting Files -@section Visiting Files -@cindex finding files -@cindex visiting files - - Visiting a file means reading a file into a buffer. Once this is -done, we say that the buffer is @dfn{visiting} that file, and call the -file ``the visited file'' of the buffer. - - A file and a buffer are two different things. A file is information -recorded permanently in the computer (unless you delete it). A buffer, -on the other hand, is information inside of Emacs that will vanish at -the end of the editing session (or when you kill the buffer). Usually, -a buffer contains information that you have copied from a file; then we -say the buffer is visiting that file. The copy in the buffer is what -you modify with editing commands. Such changes to the buffer do not -change the file; therefore, to make the changes permanent, you must -@dfn{save} the buffer, which means copying the altered buffer contents -back into the file. - - In spite of the distinction between files and buffers, people often -refer to a file when they mean a buffer and vice-versa. Indeed, we say, -``I am editing a file,'' rather than, ``I am editing a buffer that I -will soon save as a file of the same name.'' Humans do not usually need -to make the distinction explicit. When dealing with a computer program, -however, it is good to keep the distinction in mind. - -@menu -* Visiting Functions:: The usual interface functions for visiting. -* Subroutines of Visiting:: Lower-level subroutines that they use. -@end menu - -@node Visiting Functions -@subsection Functions for Visiting Files - - This section describes the functions normally used to visit files. -For historical reasons, these functions have names starting with -@samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for -functions and variables that access the visited file name of a buffer or -that find an existing buffer by its visited file name. - - In a Lisp program, if you want to look at the contents of a file but -not alter it, the fastest way is to use @code{insert-file-contents} in a -temporary buffer. Visiting the file is not necessary and takes longer. -@xref{Reading from Files}. - -@deffn Command find-file filename -This command selects a buffer visiting the file @var{filename}, -using an existing buffer if there is one, and otherwise creating a -new buffer and reading the file into it. It also returns that buffer. - -The body of the @code{find-file} function is very simple and looks -like this: - -@example -(switch-to-buffer (find-file-noselect filename)) -@end example - -@noindent -(See @code{switch-to-buffer} in @ref{Displaying Buffers}.) - -When @code{find-file} is called interactively, it prompts for -@var{filename} in the minibuffer. -@end deffn - -@defun find-file-noselect filename -This function is the guts of all the file-visiting functions. It finds -or creates a buffer visiting the file @var{filename}, and returns it. -It uses an existing buffer if there is one, and otherwise creates a new -buffer and reads the file into it. You may make the buffer current or -display it in a window if you wish, but this function does not do so. - -When @code{find-file-noselect} uses an existing buffer, it first -verifies that the file has not changed since it was last visited or -saved in that buffer. If the file has changed, then this function asks -the user whether to reread the changed file. If the user says -@samp{yes}, any changes previously made in the buffer are lost. - -If @code{find-file-noselect} needs to create a buffer, and there is no -file named @var{filename}, it displays the message @samp{New file} in -the echo area, and leaves the buffer empty. - -The @code{find-file-noselect} function calls @code{after-find-file} -after reading the file (@pxref{Subroutines of Visiting}). That function -sets the buffer major mode, parses local variables, warns the user if -there exists an auto-save file more recent than the file just visited, -and finishes by running the functions in @code{find-file-hooks}. - -The @code{find-file-noselect} function returns the buffer that is -visiting the file @var{filename}. - -@example -@group -(find-file-noselect "/etc/fstab") - @result{} #<buffer fstab> -@end group -@end example -@end defun - -@deffn Command find-file-other-window filename -This command selects a buffer visiting the file @var{filename}, but -does so in a window other than the selected window. It may use another -existing window or split a window; see @ref{Displaying Buffers}. - -When this command is called interactively, it prompts for -@var{filename}. -@end deffn - -@deffn Command find-file-read-only filename -This command selects a buffer visiting the file @var{filename}, like -@code{find-file}, but it marks the buffer as read-only. @xref{Read Only -Buffers}, for related functions and variables. - -When this command is called interactively, it prompts for -@var{filename}. -@end deffn - -@deffn Command view-file filename -This command visits @var{filename} in View mode, and displays it in a -recursive edit, returning to the previous buffer when done. View mode -is a mode that allows you to skim rapidly through the file but does not -let you modify it. Entering View mode runs the normal hook -@code{view-mode-hook}. @xref{Hooks}. - -When @code{view-file} is called interactively, it prompts for -@var{filename}. -@end deffn - -@defvar find-file-hooks -The value of this variable is a list of functions to be called after a -file is visited. The file's local-variables specification (if any) will -have been processed before the hooks are run. The buffer visiting the -file is current when the hook functions are run. - -This variable works just like a normal hook, but we think that renaming -it would not be advisable. -@end defvar - -@defvar find-file-not-found-hooks -The value of this variable is a list of functions to be called when -@code{find-file} or @code{find-file-noselect} is passed a nonexistent -file name. @code{find-file-noselect} calls these functions as soon as -it detects a nonexistent file. It calls them in the order of the list, -until one of them returns non-@code{nil}. @code{buffer-file-name} is -already set up. - -This is not a normal hook because the values of the functions are -used and they may not all be called. -@end defvar - -@node Subroutines of Visiting -@comment node-name, next, previous, up -@subsection Subroutines of Visiting - - The @code{find-file-noselect} function uses the -@code{create-file-buffer} and @code{after-find-file} functions as -subroutines. Sometimes it is useful to call them directly. - -@defun create-file-buffer filename -This function creates a suitably named buffer for visiting -@var{filename}, and returns it. It uses @var{filename} (sans directory) -as the name if that name is free; otherwise, it appends a string such as -@samp{<2>} to get an unused name. See also @ref{Creating Buffers}. - -@strong{Please note:} @code{create-file-buffer} does @emph{not} -associate the new buffer with a file and does not select the buffer. -It also does not use the default major mode. - -@example -@group -(create-file-buffer "foo") - @result{} #<buffer foo> -@end group -@group -(create-file-buffer "foo") - @result{} #<buffer foo<2>> -@end group -@group -(create-file-buffer "foo") - @result{} #<buffer foo<3>> -@end group -@end example - -This function is used by @code{find-file-noselect}. -It uses @code{generate-new-buffer} (@pxref{Creating Buffers}). -@end defun - -@defun after-find-file &optional error warn -This function sets the buffer major mode, and parses local variables -(@pxref{Auto Major Mode}). It is called by @code{find-file-noselect} -and by the default revert function (@pxref{Reverting}). - -@cindex new file message -@cindex file open error -If reading the file got an error because the file does not exist, but -its directory does exist, the caller should pass a non-@code{nil} value -for @var{error}. In that case, @code{after-find-file} issues a warning: -@samp{(New File)}. For more serious errors, the caller should usually not -call @code{after-find-file}. - -If @var{warn} is non-@code{nil}, then this function issues a warning -if an auto-save file exists and is more recent than the visited file. - -The last thing @code{after-find-file} does is call all the functions -in @code{find-file-hooks}. -@end defun - -@node Saving Buffers -@section Saving Buffers - - When you edit a file in Emacs, you are actually working on a buffer -that is visiting that file---that is, the contents of the file are -copied into the buffer and the copy is what you edit. Changes to the -buffer do not change the file until you @dfn{save} the buffer, which -means copying the contents of the buffer into the file. - -@deffn Command save-buffer &optional backup-option -This function saves the contents of the current buffer in its visited -file if the buffer has been modified since it was last visited or saved. -Otherwise it does nothing. - -@code{save-buffer} is responsible for making backup files. Normally, -@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup -file only if this is the first save since visiting the file. Other -values for @var{backup-option} request the making of backup files in -other circumstances: - -@itemize @bullet -@item -With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the -@code{save-buffer} function marks this version of the file to be -backed up when the buffer is next saved. - -@item -With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the -@code{save-buffer} function unconditionally backs up the previous -version of the file before saving it. -@end itemize -@end deffn - -@deffn Command save-some-buffers &optional save-silently-p exiting -This command saves some modified file-visiting buffers. Normally it -asks the user about each buffer. But if @var{save-silently-p} is -non-@code{nil}, it saves all the file-visiting buffers without querying -the user. - -The optional @var{exiting} argument, if non-@code{nil}, requests this -function to offer also to save certain other buffers that are not -visiting files. These are buffers that have a non-@code{nil} local -value of @code{buffer-offer-save}. (A user who says yes to saving one -of these is asked to specify a file name to use.) The -@code{save-buffers-kill-emacs} function passes a non-@code{nil} value -for this argument. -@end deffn - -@defvar buffer-offer-save -When this variable is non-@code{nil} in a buffer, Emacs offers to save -the buffer on exit even if the buffer is not visiting a file. The -variable is automatically local in all buffers. Normally, Mail mode -(used for editing outgoing mail) sets this to @code{t}. -@end defvar - -@deffn Command write-file filename -This function writes the current buffer into file @var{filename}, makes -the buffer visit that file, and marks it not modified. Then it renames -the buffer based on @var{filename}, appending a string like @samp{<2>} -if necessary to make a unique buffer name. It does most of this work by -calling @code{set-visited-file-name} and @code{save-buffer}. -@end deffn - - Saving a buffer runs several hooks. It also performs format -conversion (@pxref{Format Conversion}), and may save text properties in -``annotations'' (@pxref{Saving Properties}). - -@defvar write-file-hooks -The value of this variable is a list of functions to be called before -writing out a buffer to its visited file. If one of them returns -non-@code{nil}, the file is considered already written and the rest of -the functions are not called, nor is the usual code for writing the file -executed. - -If a function in @code{write-file-hooks} returns non-@code{nil}, it -is responsible for making a backup file (if that is appropriate). -To do so, execute the following code: - -@example -(or buffer-backed-up (backup-buffer)) -@end example - -You might wish to save the file modes value returned by -@code{backup-buffer} and use that to set the mode bits of the file that -you write. This is what @code{save-buffer} normally does. - -Even though this is not a normal hook, you can use @code{add-hook} and -@code{remove-hook} to manipulate the list. @xref{Hooks}. -@end defvar - -@c Emacs 19 feature -@defvar local-write-file-hooks -This works just like @code{write-file-hooks}, but it is intended -to be made local to particular buffers. It's not a good idea to make -@code{write-file-hooks} local to a buffer---use this variable instead. - -The variable is marked as a permanent local, so that changing the major -mode does not alter a buffer-local value. This is convenient for -packages that read ``file'' contents in special ways, and set up hooks -to save the data in a corresponding way. -@end defvar - -@c Emacs 19 feature -@defvar write-contents-hooks -This works just like @code{write-file-hooks}, but it is intended for -hooks that pertain to the contents of the file, as opposed to hooks that -pertain to where the file came from. Such hooks are usually set up by -major modes, as buffer-local bindings for this variable. - -This variable automatically becomes buffer-local whenever it is set; -switching to a new major mode always resets this variable. When you use -@code{add-hooks} to add an element to this hook, you should @emph{not} -specify a non-@code{nil} @var{local} argument, since this variable is -used @emph{only} locally. -@end defvar - -@c Emacs 19 feature -@defvar after-save-hook -This normal hook runs after a buffer has been saved in its visited file. -@end defvar - -@defvar file-precious-flag -If this variable is non-@code{nil}, then @code{save-buffer} protects -against I/O errors while saving by writing the new file to a temporary -name instead of the name it is supposed to have, and then renaming it to -the intended name after it is clear there are no errors. This procedure -prevents problems such as a lack of disk space from resulting in an -invalid file. - -As a side effect, backups are necessarily made by copying. @xref{Rename -or Copy}. Yet, at the same time, saving a precious file always breaks -all hard links between the file you save and other file names. - -Some modes set this variable non-@code{nil} locally in particular -buffers. -@end defvar - -@defopt require-final-newline -This variable determines whether files may be written out that do -@emph{not} end with a newline. If the value of the variable is -@code{t}, then @code{save-buffer} silently adds a newline at the end of -the file whenever the buffer being saved does not already end in one. -If the value of the variable is non-@code{nil}, but not @code{t}, then -@code{save-buffer} asks the user whether to add a newline each time the -case arises. - -If the value of the variable is @code{nil}, then @code{save-buffer} -doesn't add newlines at all. @code{nil} is the default value, but a few -major modes set it to @code{t} in particular buffers. -@end defopt - -@deffn Command set-visited-file-name filename &optional no-query -This function changes the visited file name of the current buffer to -@var{filename}. It also renames the buffer based on @var{filename}, -appending a string like @samp{<2>} if necessary to make a unique buffer -name. It marks the buffer as @emph{modified},a since the contents do not -(as far as Emacs knows) match the actual file's contents. - -If the specified file already exists, @code{set-visited-file-name} -asks for confirmation unless @var{no-query} is non-@code{nil}. -@end deffn - -@node Reading from Files -@comment node-name, next, previous, up -@section Reading from Files - - You can copy a file from the disk and insert it into a buffer -using the @code{insert-file-contents} function. Don't use the user-level -command @code{insert-file} in a Lisp program, as that sets the mark. - -@defun insert-file-contents filename &optional visit beg end replace -This function inserts the contents of file @var{filename} into the -current buffer after point. It returns a list of the absolute file name -and the length of the data inserted. An error is signaled if -@var{filename} is not the name of a file that can be read. - -The function @code{insert-file-contents} checks the file contents -against the defined file formats, and converts the file contents if -appropriate. @xref{Format Conversion}. It also calls the functions in -the list @code{after-insert-file-functions}; see @ref{Saving -Properties}. - -If @var{visit} is non-@code{nil}, this function additionally marks the -buffer as unmodified and sets up various fields in the buffer so that it -is visiting the file @var{filename}: these include the buffer's visited -file name and its last save file modtime. This feature is used by -@code{find-file-noselect} and you probably should not use it yourself. - -If @var{beg} and @var{end} are non-@code{nil}, they should be integers -specifying the portion of the file to insert. In this case, @var{visit} -must be @code{nil}. For example, - -@example -(insert-file-contents filename nil 0 500) -@end example - -@noindent -inserts the first 500 characters of a file. - -If the argument @var{replace} is non-@code{nil}, it means to replace the -contents of the buffer (actually, just the accessible portion) with the -contents of the file. This is better than simply deleting the buffer -contents and inserting the whole file, because (1) it preserves some -marker positions and (2) it puts less data in the undo list. -@end defun - -If you want to pass a file name to another process so that another -program can read the file, use the function @code{file-local-copy}; see -@ref{Magic File Names}. - -@node Writing to Files -@comment node-name, next, previous, up -@section Writing to Files - - You can write the contents of a buffer, or part of a buffer, directly -to a file on disk using the @code{append-to-file} and -@code{write-region} functions. Don't use these functions to write to -files that are being visited; that could cause confusion in the -mechanisms for visiting. - -@deffn Command append-to-file start end filename -This function appends the contents of the region delimited by -@var{start} and @var{end} in the current buffer to the end of file -@var{filename}. If that file does not exist, it is created. This -function returns @code{nil}. - -An error is signaled if @var{filename} specifies a nonwritable file, -or a nonexistent file in a directory where files cannot be created. -@end deffn - -@deffn Command write-region start end filename &optional append visit -This function writes the region delimited by @var{start} and @var{end} -in the current buffer into the file specified by @var{filename}. - -@c Emacs 19 feature -If @var{start} is a string, then @code{write-region} writes or appends -that string, rather than text from the buffer. - -If @var{append} is non-@code{nil}, then the specified text is appended -to the existing file contents (if any). - -If @var{visit} is @code{t}, then Emacs establishes an association -between the buffer and the file: the buffer is then visiting that file. -It also sets the last file modification time for the current buffer to -@var{filename}'s modtime, and marks the buffer as not modified. This -feature is used by @code{save-buffer}, but you probably should not use -it yourself. - -@c Emacs 19 feature -If @var{visit} is a string, it specifies the file name to visit. This -way, you can write the data to one file (@var{filename}) while recording -the buffer as visiting another file (@var{visit}). The argument -@var{visit} is used in the echo area message and also for file locking; -@var{visit} is stored in @code{buffer-file-name}. This feature is used -to implement @code{file-precious-flag}; don't use it yourself unless you -really know what you're doing. - -The function @code{write-region} converts the data which it writes to -the appropriate file formats specified by @code{buffer-file-format}. -@xref{Format Conversion}. It also calls the functions in the list -@code{write-region-annotate-functions}; see @ref{Saving Properties}. - -Normally, @code{write-region} displays a message @samp{Wrote file -@var{filename}} in the echo area. If @var{visit} is neither @code{t} -nor @code{nil} nor a string, then this message is inhibited. This -feature is useful for programs that use files for internal purposes, -files that the user does not need to know about. -@end deffn - -@node File Locks -@section File Locks -@cindex file locks - - When two users edit the same file at the same time, they are likely to -interfere with each other. Emacs tries to prevent this situation from -arising by recording a @dfn{file lock} when a file is being modified. -Emacs can then detect the first attempt to modify a buffer visiting a -file that is locked by another Emacs job, and ask the user what to do. - - File locks do not work properly when multiple machines can share -file systems, such as with NFS. Perhaps a better file locking system -will be implemented in the future. When file locks do not work, it is -possible for two users to make changes simultaneously, but Emacs can -still warn the user who saves second. Also, the detection of -modification of a buffer visiting a file changed on disk catches some -cases of simultaneous editing; see @ref{Modification Time}. - -@defun file-locked-p filename - This function returns @code{nil} if the file @var{filename} is not -locked by this Emacs process. It returns @code{t} if it is locked by -this Emacs, and it returns the name of the user who has locked it if it -is locked by someone else. - -@example -@group -(file-locked-p "foo") - @result{} nil -@end group -@end example -@end defun - -@defun lock-buffer &optional filename - This function locks the file @var{filename}, if the current buffer is -modified. The argument @var{filename} defaults to the current buffer's -visited file. Nothing is done if the current buffer is not visiting a -file, or is not modified. -@end defun - -@defun unlock-buffer -This function unlocks the file being visited in the current buffer, -if the buffer is modified. If the buffer is not modified, then -the file should not be locked, so this function does nothing. It also -does nothing if the current buffer is not visiting a file. -@end defun - -@defun ask-user-about-lock file other-user -This function is called when the user tries to modify @var{file}, but it -is locked by another user named @var{other-user}. The value it returns -determines what happens next: - -@itemize @bullet -@item -A value of @code{t} says to grab the lock on the file. Then -this user may edit the file and @var{other-user} loses the lock. - -@item -A value of @code{nil} says to ignore the lock and let this -user edit the file anyway. - -@item -@kindex file-locked -This function may instead signal a @code{file-locked} error, in which -case the change that the user was about to make does not take place. - -The error message for this error looks like this: - -@example -@error{} File is locked: @var{file} @var{other-user} -@end example - -@noindent -where @code{file} is the name of the file and @var{other-user} is the -name of the user who has locked the file. -@end itemize - - The default definition of this function asks the user to choose what -to do. If you wish, you can replace the @code{ask-user-about-lock} -function with your own version that decides in another way. The code -for its usual definition is in @file{userlock.el}. -@end defun - -@node Information about Files -@section Information about Files - - The functions described in this section all operate on strings that -designate file names. All the functions have names that begin with the -word @samp{file}. These functions all return information about actual -files or directories, so their arguments must all exist as actual files -or directories unless otherwise noted. - -@menu -* Testing Accessibility:: Is a given file readable? Writable? -* Kinds of Files:: Is it a directory? A symbolic link? -* Truenames:: Eliminating symbolic links from a file name. -* File Attributes:: How large is it? Any other names? Etc. -@end menu - -@node Testing Accessibility -@comment node-name, next, previous, up -@subsection Testing Accessibility -@cindex accessibility of a file -@cindex file accessibility - - These functions test for permission to access a file in specific ways. - -@defun file-exists-p filename -This function returns @code{t} if a file named @var{filename} appears -to exist. This does not mean you can necessarily read the file, only -that you can find out its attributes. (On Unix, this is true if the -file exists and you have execute permission on the containing -directories, regardless of the protection of the file itself.) - -If the file does not exist, or if fascist access control policies -prevent you from finding the attributes of the file, this function -returns @code{nil}. -@end defun - -@defun file-readable-p filename -This function returns @code{t} if a file named @var{filename} exists -and you can read it. It returns @code{nil} otherwise. - -@example -@group -(file-readable-p "files.texi") - @result{} t -@end group -@group -(file-exists-p "/usr/spool/mqueue") - @result{} t -@end group -@group -(file-readable-p "/usr/spool/mqueue") - @result{} nil -@end group -@end example -@end defun - -@c Emacs 19 feature -@defun file-executable-p filename -This function returns @code{t} if a file named @var{filename} exists and -you can execute it. It returns @code{nil} otherwise. If the file is a -directory, execute permission means you can check the existence and -attributes of files inside the directory, and open those files if their -modes permit. -@end defun - -@defun file-writable-p filename -This function returns @code{t} if the file @var{filename} can be written -or created by you, and @code{nil} otherwise. A file is writable if the -file exists and you can write it. It is creatable if it does not exist, -but the specified directory does exist and you can write in that -directory. - -In the third example below, @file{foo} is not writable because the -parent directory does not exist, even though the user could create such -a directory. - -@example -@group -(file-writable-p "~/foo") - @result{} t -@end group -@group -(file-writable-p "/foo") - @result{} nil -@end group -@group -(file-writable-p "~/no-such-dir/foo") - @result{} nil -@end group -@end example -@end defun - -@c Emacs 19 feature -@defun file-accessible-directory-p dirname -This function returns @code{t} if you have permission to open existing -files in the directory whose name as a file is @var{dirname}; otherwise -(or if there is no such directory), it returns @code{nil}. The value -of @var{dirname} may be either a directory name or the file name of a -directory. - -Example: after the following, - -@example -(file-accessible-directory-p "/foo") - @result{} nil -@end example - -@noindent -we can deduce that any attempt to read a file in @file{/foo/} will -give an error. -@end defun - -@defun file-ownership-preserved-p filename -This function returns @code{t} if deleting the file @var{filename} and -then creating it anew would keep the file's owner unchanged. -@end defun - -@defun file-newer-than-file-p filename1 filename2 -@cindex file age -@cindex file modification time -This function returns @code{t} if the file @var{filename1} is -newer than file @var{filename2}. If @var{filename1} does not -exist, it returns @code{nil}. If @var{filename2} does not exist, -it returns @code{t}. - -In the following example, assume that the file @file{aug-19} was written -on the 19th, @file{aug-20} was written on the 20th, and the file -@file{no-file} doesn't exist at all. - -@example -@group -(file-newer-than-file-p "aug-19" "aug-20") - @result{} nil -@end group -@group -(file-newer-than-file-p "aug-20" "aug-19") - @result{} t -@end group -@group -(file-newer-than-file-p "aug-19" "no-file") - @result{} t -@end group -@group -(file-newer-than-file-p "no-file" "aug-19") - @result{} nil -@end group -@end example - -You can use @code{file-attributes} to get a file's last modification -time as a list of two numbers. @xref{File Attributes}. -@end defun - -@node Kinds of Files -@comment node-name, next, previous, up -@subsection Distinguishing Kinds of Files - - This section describes how to distinguish various kinds of files, such -as directories, symbolic links, and ordinary files. - -@defun file-symlink-p filename -@cindex file symbolic links -If the file @var{filename} is a symbolic link, the @code{file-symlink-p} -function returns the file name to which it is linked. This may be the -name of a text file, a directory, or even another symbolic link, or it -may be a nonexistent file name. - -If the file @var{filename} is not a symbolic link (or there is no such file), -@code{file-symlink-p} returns @code{nil}. - -@example -@group -(file-symlink-p "foo") - @result{} nil -@end group -@group -(file-symlink-p "sym-link") - @result{} "foo" -@end group -@group -(file-symlink-p "sym-link2") - @result{} "sym-link" -@end group -@group -(file-symlink-p "/bin") - @result{} "/pub/bin" -@end group -@end example - -@c !!! file-symlink-p: should show output of ls -l for comparison -@end defun - -@defun file-directory-p filename -This function returns @code{t} if @var{filename} is the name of an -existing directory, @code{nil} otherwise. - -@example -@group -(file-directory-p "~rms") - @result{} t -@end group -@group -(file-directory-p "~rms/lewis/files.texi") - @result{} nil -@end group -@group -(file-directory-p "~rms/lewis/no-such-file") - @result{} nil -@end group -@group -(file-directory-p "$HOME") - @result{} nil -@end group -@group -(file-directory-p - (substitute-in-file-name "$HOME")) - @result{} t -@end group -@end example -@end defun - -@defun file-regular-p filename -This function returns @code{t} if the file @var{filename} exists and is -a regular file (not a directory, symbolic link, named pipe, terminal, or -other I/O device). -@end defun - -@node Truenames -@subsection Truenames -@cindex truename (of file) - -@c Emacs 19 features - The @dfn{truename} of a file is the name that you get by following -symbolic links until none remain, then expanding to get rid of @samp{.} -and @samp{..} as components. Strictly speaking, a file need not have a -unique truename; the number of distinct truenames a file has is equal to -the number of hard links to the file. However, truenames are useful -because they eliminate symbolic links as a cause of name variation. - -@defun file-truename filename -The function @code{file-truename} returns the true name of the file -@var{filename}. This is the name that you get by following symbolic -links until none remain. The argument must be an absolute file name. -@end defun - - @xref{Buffer File Name}, for related information. - -@node File Attributes -@comment node-name, next, previous, up -@subsection Other Information about Files - - This section describes the functions for getting detailed information -about a file, other than its contents. This information includes the -mode bits that control access permission, the owner and group numbers, -the number of names, the inode number, the size, and the times of access -and modification. - -@defun file-modes filename -@cindex permission -@cindex file attributes -This function returns the mode bits of @var{filename}, as an integer. -The mode bits are also called the file permissions, and they specify -access control in the usual Unix fashion. If the low-order bit is 1, -then the file is executable by all users, if the second-lowest-order bit -is 1, then the file is writable by all users, etc. - -The highest value returnable is 4095 (7777 octal), meaning that -everyone has read, write, and execute permission, that the @sc{suid} bit -is set for both others and group, and that the sticky bit is set. - -@example -@group -(file-modes "~/junk/diffs") - @result{} 492 ; @r{Decimal integer.} -@end group -@group -(format "%o" 492) - @result{} "754" ; @r{Convert to octal.} -@end group - -@group -(set-file-modes "~/junk/diffs" 438) - @result{} nil -@end group - -@group -(format "%o" 438) - @result{} "666" ; @r{Convert to octal.} -@end group - -@group -% ls -l diffs - -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs -@end group -@end example -@end defun - -@defun file-nlinks filename -This functions returns the number of names (i.e., hard links) that -file @var{filename} has. If the file does not exist, then this function -returns @code{nil}. Note that symbolic links have no effect on this -function, because they are not considered to be names of the files they -link to. - -@example -@group -% ls -l foo* --rw-rw-rw- 2 rms 4 Aug 19 01:27 foo --rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1 -@end group - -@group -(file-nlinks "foo") - @result{} 2 -@end group -@group -(file-nlinks "doesnt-exist") - @result{} nil -@end group -@end example -@end defun - -@defun file-attributes filename -This function returns a list of attributes of file @var{filename}. If -the specified file cannot be opened, it returns @code{nil}. - -The elements of the list, in order, are: - -@enumerate 0 -@item -@code{t} for a directory, a string for a symbolic link (the name -linked to), or @code{nil} for a text file. - -@c Wordy so as to prevent an overfull hbox. --rjc 15mar92 -@item -The number of names the file has. Alternate names, also known as hard -links, can be created by using the @code{add-name-to-file} function -(@pxref{Changing File Attributes}). - -@item -The file's @sc{uid}. - -@item -The file's @sc{gid}. - -@item -The time of last access, as a list of two integers. -The first integer has the high-order 16 bits of time, -the second has the low 16 bits. (This is similar to the -value of @code{current-time}; see @ref{Time of Day}.) - -@item -The time of last modification as a list of two integers (as above). - -@item -The time of last status change as a list of two integers (as above). - -@item -The size of the file in bytes. - -@item -The file's modes, as a string of ten letters or dashes, -as in @samp{ls -l}. - -@item -@code{t} if the file's @sc{gid} would change if file were -deleted and recreated; @code{nil} otherwise. - -@item -The file's inode number. - -@item -The file system number of the file system that the file is in. This -element and the file's inode number together give enough information to -distinguish any two files on the system---no two files can have the same -values for both of these numbers. -@end enumerate - -For example, here are the file attributes for @file{files.texi}: - -@example -@group -(file-attributes "files.texi") - @result{} (nil - 1 - 2235 - 75 - (8489 20284) - (8489 20284) - (8489 20285) - 14906 - "-rw-rw-rw-" - nil - 129500 - -32252) -@end group -@end example - -@noindent -and here is how the result is interpreted: - -@table @code -@item nil -is neither a directory nor a symbolic link. - -@item 1 -has only one name (the name @file{files.texi} in the current default -directory). - -@item 2235 -is owned by the user with @sc{uid} 2235. - -@item 75 -is in the group with @sc{gid} 75. - -@item (8489 20284) -was last accessed on Aug 19 00:09. - -@item (8489 20284) -was last modified on Aug 19 00:09. - -@item (8489 20285) -last had its inode changed on Aug 19 00:09. - -@item 14906 -is 14906 characters long. - -@item "-rw-rw-rw-" -has a mode of read and write access for the owner, group, and world. - -@item nil -would retain the same @sc{gid} if it were recreated. - -@item 129500 -has an inode number of 129500. -@item -32252 -is on file system number -32252. -@end table -@end defun - -@node Changing File Attributes -@section Changing File Names and Attributes -@cindex renaming files -@cindex copying files -@cindex deleting files -@cindex linking files -@cindex setting modes of files - - The functions in this section rename, copy, delete, link, and set the -modes of files. - - In the functions that have an argument @var{newname}, if a file by the -name of @var{newname} already exists, the actions taken depend on the -value of the argument @var{ok-if-already-exists}: - -@itemize @bullet -@item -Signal a @code{file-already-exists} error if -@var{ok-if-already-exists} is @code{nil}. - -@item -Request confirmation if @var{ok-if-already-exists} is a number. - -@item -Replace the old file without confirmation if @var{ok-if-already-exists} -is any other value. -@end itemize - -@defun add-name-to-file oldname newname &optional ok-if-already-exists -@cindex file with multiple names -@cindex file hard link -This function gives the file named @var{oldname} the additional name -@var{newname}. This means that @var{newname} becomes a new ``hard -link'' to @var{oldname}. - -In the first part of the following example, we list two files, -@file{foo} and @file{foo3}. - -@example -@group -% ls -l fo* --rw-rw-rw- 1 rms 29 Aug 18 20:32 foo --rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 -@end group -@end example - -Now we create a hard link, by calling @code{add-name-to-file}, then list -the files again. This shows two names for one file, @file{foo} and -@file{foo2}. - -@example -@group -(add-name-to-file "~/lewis/foo1" "~/lewis/foo2") - @result{} nil -@end group - -@group -% ls -l fo* --rw-rw-rw- 2 rms 29 Aug 18 20:32 foo --rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2 --rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3 -@end group -@end example - -@c !!! Check whether this set of examples is consistent. --rjc 15mar92 - Finally, we evaluate the following: - -@example -(add-name-to-file "~/lewis/foo" "~/lewis/foo3" t) -@end example - -@noindent -and list the files again. Now there are three names -for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old -contents of @file{foo3} are lost. - -@example -@group -(add-name-to-file "~/lewis/foo1" "~/lewis/foo3") - @result{} nil -@end group - -@group -% ls -l fo* --rw-rw-rw- 3 rms 29 Aug 18 20:32 foo --rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2 --rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3 -@end group -@end example - - This function is meaningless on VMS, where multiple names for one file -are not allowed. - - See also @code{file-nlinks} in @ref{File Attributes}. -@end defun - -@deffn Command rename-file filename newname &optional ok-if-already-exists -This command renames the file @var{filename} as @var{newname}. - -If @var{filename} has additional names aside from @var{filename}, it -continues to have those names. In fact, adding the name @var{newname} -with @code{add-name-to-file} and then deleting @var{filename} has the -same effect as renaming, aside from momentary intermediate states. - -In an interactive call, this function prompts for @var{filename} and -@var{newname} in the minibuffer; also, it requests confirmation if -@var{newname} already exists. -@end deffn - -@deffn Command copy-file oldname newname &optional ok-if-exists time -This command copies the file @var{oldname} to @var{newname}. An -error is signaled if @var{oldname} does not exist. - -If @var{time} is non-@code{nil}, then this functions gives the new -file the same last-modified time that the old one has. (This works on -only some operating systems.) - -In an interactive call, this function prompts for @var{filename} and -@var{newname} in the minibuffer; also, it requests confirmation if -@var{newname} already exists. -@end deffn - -@deffn Command delete-file filename -@pindex rm -This command deletes the file @var{filename}, like the shell command -@samp{rm @var{filename}}. If the file has multiple names, it continues -to exist under the other names. - -A suitable kind of @code{file-error} error is signaled if the file -does not exist, or is not deletable. (On Unix, a file is deletable if -its directory is writable.) - -See also @code{delete-directory} in @ref{Create/Delete Dirs}. -@end deffn - -@deffn Command make-symbolic-link filename newname &optional ok-if-exists -@pindex ln -@kindex file-already-exists -This command makes a symbolic link to @var{filename}, named -@var{newname}. This is like the shell command @samp{ln -s -@var{filename} @var{newname}}. - -In an interactive call, this function prompts for @var{filename} and -@var{newname} in the minibuffer; also, it requests confirmation if -@var{newname} already exists. -@end deffn - -@defun define-logical-name varname string -This function defines the logical name @var{name} to have the value -@var{string}. It is available only on VMS. -@end defun - -@defun set-file-modes filename mode -This function sets mode bits of @var{filename} to @var{mode} (which must -be an integer). Only the low 12 bits of @var{mode} are used. -@end defun - -@c Emacs 19 feature -@defun set-default-file-modes mode -This function sets the default file protection for new files created by -Emacs and its subprocesses. Every file created with Emacs initially has -this protection. On Unix, the default protection is the bitwise -complement of the ``umask'' value. - -The argument @var{mode} must be an integer. Only the low 9 bits of -@var{mode} are used. - -Saving a modified version of an existing file does not count as creating -the file; it does not change the file's mode, and does not use the -default file protection. -@end defun - -@defun default-file-modes -This function returns the current default protection value. -@end defun - -@cindex MS-DOS and file modes -@cindex file modes and MS-DOS - On MS-DOS, there is no such thing as an ``executable'' file mode bit. -So Emacs considers a file executable if its name ends in @samp{.com}, -@samp{.bat} or @samp{.exe}. This is reflected in the values returned -by @code{file-modes} and @code{file-attributes}. - -@node File Names -@section File Names -@cindex file names - - Files are generally referred to by their names, in Emacs as elsewhere. -File names in Emacs are represented as strings. The functions that -operate on a file all expect a file name argument. - - In addition to operating on files themselves, Emacs Lisp programs -often need to operate on the names; i.e., to take them apart and to use -part of a name to construct related file names. This section describes -how to manipulate file names. - - The functions in this section do not actually access files, so they -can operate on file names that do not refer to an existing file or -directory. - - On VMS, all these functions understand both VMS file-name syntax and -Unix syntax. This is so that all the standard Lisp libraries can -specify file names in Unix syntax and work properly on VMS without -change. On MS-DOS, these functions understand MS-DOS file-name syntax -as well as Unix syntax. - -@menu -* File Name Components:: The directory part of a file name, and the rest. -* Directory Names:: A directory's name as a directory - is different from its name as a file. -* Relative File Names:: Some file names are relative to a current directory. -* File Name Expansion:: Converting relative file names to absolute ones. -* Unique File Names:: Generating names for temporary files. -* File Name Completion:: Finding the completions for a given file name. -* Standard File Names:: If your package uses a fixed file name, - how to handle various operating systems simply. -@end menu - -@node File Name Components -@subsection File Name Components -@cindex directory part (of file name) -@cindex nondirectory part (of file name) -@cindex version number (in file name) - - The operating system groups files into directories. To specify a -file, you must specify the directory and the file's name within that -directory. Therefore, Emacs considers a file name as having two main -parts: the @dfn{directory name} part, and the @dfn{nondirectory} part -(or @dfn{file name within the directory}). Either part may be empty. -Concatenating these two parts reproduces the original file name. - - On Unix, the directory part is everything up to and including the last -slash; the nondirectory part is the rest. The rules in VMS syntax are -complicated. - - For some purposes, the nondirectory part is further subdivided into -the name proper and the @dfn{version number}. On Unix, only backup -files have version numbers in their names; on VMS, every file has a -version number, but most of the time the file name actually used in -Emacs omits the version number. Version numbers are found mostly in -directory lists. - -@defun file-name-directory filename - This function returns the directory part of @var{filename} (or -@code{nil} if @var{filename} does not include a directory part). On -Unix, the function returns a string ending in a slash. On VMS, it -returns a string ending in one of the three characters @samp{:}, -@samp{]}, or @samp{>}. - -@example -@group -(file-name-directory "lewis/foo") ; @r{Unix example} - @result{} "lewis/" -@end group -@group -(file-name-directory "foo") ; @r{Unix example} - @result{} nil -@end group -@group -(file-name-directory "[X]FOO.TMP") ; @r{VMS example} - @result{} "[X]" -@end group -@end example -@end defun - -@defun file-name-nondirectory filename - This function returns the nondirectory part of @var{filename}. - -@example -@group -(file-name-nondirectory "lewis/foo") - @result{} "foo" -@end group -@group -(file-name-nondirectory "foo") - @result{} "foo" -@end group -@group -;; @r{The following example is accurate only on VMS.} -(file-name-nondirectory "[X]FOO.TMP") - @result{} "FOO.TMP" -@end group -@end example -@end defun - -@defun file-name-sans-versions filename - This function returns @var{filename} without any file version numbers, -backup version numbers, or trailing tildes. - -@example -@group -(file-name-sans-versions "~rms/foo.~1~") - @result{} "~rms/foo" -@end group -@group -(file-name-sans-versions "~rms/foo~") - @result{} "~rms/foo" -@end group -@group -(file-name-sans-versions "~rms/foo") - @result{} "~rms/foo" -@end group -@group -;; @r{The following example applies to VMS only.} -(file-name-sans-versions "foo;23") - @result{} "foo" -@end group -@end example -@end defun - -@defun file-name-sans-extension filename -This function returns @var{filename} minus its ``extension,'' if any. -The extension, in a file name, is the part that starts with the last -@samp{.} in the last name component. For example, - -@example -(file-name-sans-extension "foo.lose.c") - @result{} "foo.lose" -(file-name-sans-extension "big.hack/foo") - @result{} "big.hack/foo" -@end example -@end defun - -@node Directory Names -@comment node-name, next, previous, up -@subsection Directory Names -@cindex directory name -@cindex file name of directory - - A @dfn{directory name} is the name of a directory. A directory is a -kind of file, and it has a file name, which is related to the directory -name but not identical to it. (This is not quite the same as the usual -Unix terminology.) These two different names for the same entity are -related by a syntactic transformation. On Unix, this is simple: a -directory name ends in a slash, whereas the directory's name as a file -lacks that slash. On VMS, the relationship is more complicated. - - The difference between a directory name and its name as a file is -subtle but crucial. When an Emacs variable or function argument is -described as being a directory name, a file name of a directory is not -acceptable. - - The following two functions convert between directory names and file -names. They do nothing special with environment variable substitutions -such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}. - -@defun file-name-as-directory filename -This function returns a string representing @var{filename} in a form -that the operating system will interpret as the name of a directory. In -Unix, this means appending a slash to the string. On VMS, the function -converts a string of the form @file{[X]Y.DIR.1} to the form -@file{[X.Y]}. - -@example -@group -(file-name-as-directory "~rms/lewis") - @result{} "~rms/lewis/" -@end group -@end example -@end defun - -@defun directory-file-name dirname -This function returns a string representing @var{dirname} in a form -that the operating system will interpret as the name of a file. On -Unix, this means removing a final slash from the string. On VMS, the -function converts a string of the form @file{[X.Y]} to -@file{[X]Y.DIR.1}. - -@example -@group -(directory-file-name "~lewis/") - @result{} "~lewis" -@end group -@end example -@end defun - -@cindex directory name abbreviation - Directory name abbreviations are useful for directories that are -normally accessed through symbolic links. Sometimes the users recognize -primarily the link's name as ``the name'' of the directory, and find it -annoying to see the directory's ``real'' name. If you define the link -name as an abbreviation for the ``real'' name, Emacs shows users the -abbreviation instead. - -@defvar directory-abbrev-alist -The variable @code{directory-abbrev-alist} contains an alist of -abbreviations to use for file directories. Each element has the form -@code{(@var{from} . @var{to})}, and says to replace @var{from} with -@var{to} when it appears in a directory name. The @var{from} string is -actually a regular expression; it should always start with @samp{^}. -The function @code{abbreviate-file-name} performs these substitutions. - -You can set this variable in @file{site-init.el} to describe the -abbreviations appropriate for your site. - -Here's an example, from a system on which file system @file{/home/fsf} -and so on are normally accessed through symbolic links named @file{/fsf} -and so on. - -@example -(("^/home/fsf" . "/fsf") - ("^/home/gp" . "/gp") - ("^/home/gd" . "/gd")) -@end example -@end defvar - - To convert a directory name to its abbreviation, use this -function: - -@defun abbreviate-file-name dirname -This function applies abbreviations from @code{directory-abbrev-alist} -to its argument, and substitutes @samp{~} for the user's home -directory. -@end defun - -@node Relative File Names -@subsection Absolute and Relative File Names -@cindex absolute file name -@cindex relative file name - - All the directories in the file system form a tree starting at the -root directory. A file name can specify all the directory names -starting from the root of the tree; then it is called an @dfn{absolute} -file name. Or it can specify the position of the file in the tree -relative to a default directory; then it is called a @dfn{relative} -file name. On Unix, an absolute file name starts with a slash or a -tilde (@samp{~}), and a relative one does not. The rules on VMS are -complicated. - -@defun file-name-absolute-p filename -This function returns @code{t} if file @var{filename} is an absolute -file name, @code{nil} otherwise. On VMS, this function understands both -Unix syntax and VMS syntax. - -@example -@group -(file-name-absolute-p "~rms/foo") - @result{} t -@end group -@group -(file-name-absolute-p "rms/foo") - @result{} nil -@end group -@group -(file-name-absolute-p "/user/rms/foo") - @result{} t -@end group -@end example -@end defun - -@node File Name Expansion -@subsection Functions that Expand Filenames -@cindex expansion of file names - - @dfn{Expansion} of a file name means converting a relative file name -to an absolute one. Since this is done relative to a default directory, -you must specify the default directory name as well as the file name to -be expanded. Expansion also simplifies file names by eliminating -redundancies such as @file{./} and @file{@var{name}/../}. - -@defun expand-file-name filename &optional directory -This function converts @var{filename} to an absolute file name. If -@var{directory} is supplied, it is the directory to start with if -@var{filename} is relative. (The value of @var{directory} should itself -be an absolute directory name; it may start with @samp{~}.) -Otherwise, the current buffer's value of @code{default-directory} is -used. For example: - -@example -@group -(expand-file-name "foo") - @result{} "/xcssun/users/rms/lewis/foo" -@end group -@group -(expand-file-name "../foo") - @result{} "/xcssun/users/rms/foo" -@end group -@group -(expand-file-name "foo" "/usr/spool/") - @result{} "/usr/spool/foo" -@end group -@group -(expand-file-name "$HOME/foo") - @result{} "/xcssun/users/rms/lewis/$HOME/foo" -@end group -@end example - -Filenames containing @samp{.} or @samp{..} are simplified to their -canonical form: - -@example -@group -(expand-file-name "bar/../foo") - @result{} "/xcssun/users/rms/lewis/foo" -@end group -@end example - -@samp{~/} is expanded into the user's home directory. A @samp{/} or -@samp{~} following a @samp{/} is taken to be the start of an absolute -file name that overrides what precedes it, so everything before that -@samp{/} or @samp{~} is deleted. For example: - -@example -@group -(expand-file-name - "/a1/gnu//usr/local/lib/emacs/etc/MACHINES") - @result{} "/usr/local/lib/emacs/etc/MACHINES" -@end group -@group -(expand-file-name "/a1/gnu/~/foo") - @result{} "/xcssun/users/rms/foo" -@end group -@end example - -@noindent -In both cases, @file{/a1/gnu/} is discarded because an absolute file -name follows it. - -Note that @code{expand-file-name} does @emph{not} expand environment -variables; only @code{substitute-in-file-name} does that. -@end defun - -@c Emacs 19 feature -@defun file-relative-name filename directory -This function does the inverse of expansion---it tries to return a -relative name that is equivalent to @var{filename} when interpreted -relative to @var{directory}. (If such a relative name would be longer -than the absolute name, it returns the absolute name instead.) - -@example -(file-relative-name "/foo/bar" "/foo/") - @result{} "bar") -(file-relative-name "/foo/bar" "/hack/") - @result{} "/foo/bar") -@end example -@end defun - -@defvar default-directory -The value of this buffer-local variable is the default directory for the -current buffer. It should be an absolute directory name; it may start -with @samp{~}. This variable is local in every buffer. - -@code{expand-file-name} uses the default directory when its second -argument is @code{nil}. - -On Unix systems, the value is always a string ending with a slash. - -@example -@group -default-directory - @result{} "/user/lewis/manual/" -@end group -@end example -@end defvar - -@defun substitute-in-file-name filename -This function replaces environment variables references in -@var{filename} with the environment variable values. Following standard -Unix shell syntax, @samp{$} is the prefix to substitute an environment -variable value. - -The environment variable name is the series of alphanumeric characters -(including underscores) that follow the @samp{$}. If the character following -the @samp{$} is a @samp{@{}, then the variable name is everything up to the -matching @samp{@}}. - -@c Wordy to avoid overfull hbox. --rjc 15mar92 -Here we assume that the environment variable @code{HOME}, which holds -the user's home directory name, has value @samp{/xcssun/users/rms}. - -@example -@group -(substitute-in-file-name "$HOME/foo") - @result{} "/xcssun/users/rms/foo" -@end group -@end example - -If a @samp{~} or a @samp{/} appears following a @samp{/}, after -substitution, everything before the following @samp{/} is discarded: - -@example -@group -(substitute-in-file-name "bar/~/foo") - @result{} "~/foo" -@end group -@group -(substitute-in-file-name "/usr/local/$HOME/foo") - @result{} "/xcssun/users/rms/foo" -@end group -@end example - -On VMS, @samp{$} substitution is not done, so this function does nothing -on VMS except discard superfluous initial components as shown above. -@end defun - -@node Unique File Names -@subsection Generating Unique File Names - - Some programs need to write temporary files. Here is the usual way to -construct a name for such a file: - -@example -(make-temp-name (concat "/tmp/" @var{name-of-application})) -@end example - -@noindent -Here we use the directory @file{/tmp/} because that is the standard -place on Unix for temporary files. The job of @code{make-temp-name} is -to prevent two different users or two different jobs from trying to use -the same name. - -@defun make-temp-name string -This function generates string that can be used as a unique name. The -name starts with @var{string}, and ends with a number that is different -in each Emacs job. - -@example -@group -(make-temp-name "/tmp/foo") - @result{} "/tmp/foo021304" -@end group -@end example - -To prevent conflicts among different libraries running in the same -Emacs, each Lisp program that uses @code{make-temp-name} should have its -own @var{string}. The number added to the end of the name distinguishes -between the same application running in different Emacs jobs. -@end defun - -@node File Name Completion -@subsection File Name Completion -@cindex file name completion subroutines -@cindex completion, file name - - This section describes low-level subroutines for completing a file -name. For other completion functions, see @ref{Completion}. - -@defun file-name-all-completions partial-filename directory -This function returns a list of all possible completions for a file -whose name starts with @var{partial-filename} in directory -@var{directory}. The order of the completions is the order of the files -in the directory, which is unpredictable and conveys no useful -information. - -The argument @var{partial-filename} must be a file name containing no -directory part and no slash. The current buffer's default directory is -prepended to @var{directory}, if @var{directory} is not absolute. - -In the following example, suppose that @file{~rms/lewis} is the current -default directory, and has five files whose names begin with @samp{f}: -@file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and -@file{file.c.~2~}.@refill - -@example -@group -(file-name-all-completions "f" "") - @result{} ("foo" "file~" "file.c.~2~" - "file.c.~1~" "file.c") -@end group - -@group -(file-name-all-completions "fo" "") - @result{} ("foo") -@end group -@end example -@end defun - -@defun file-name-completion filename directory -This function completes the file name @var{filename} in directory -@var{directory}. It returns the longest prefix common to all file names -in directory @var{directory} that start with @var{filename}. - -If only one match exists and @var{filename} matches it exactly, the -function returns @code{t}. The function returns @code{nil} if directory -@var{directory} contains no name starting with @var{filename}. - -In the following example, suppose that the current default directory -has five files whose names begin with @samp{f}: @file{foo}, -@file{file~}, @file{file.c}, @file{file.c.~1~}, and -@file{file.c.~2~}.@refill - -@example -@group -(file-name-completion "fi" "") - @result{} "file" -@end group - -@group -(file-name-completion "file.c.~1" "") - @result{} "file.c.~1~" -@end group - -@group -(file-name-completion "file.c.~1~" "") - @result{} t -@end group - -@group -(file-name-completion "file.c.~3" "") - @result{} nil -@end group -@end example -@end defun - -@defopt completion-ignored-extensions -@code{file-name-completion} usually ignores file names that end in any -string in this list. It does not ignore them when all the possible -completions end in one of these suffixes or when a buffer showing all -possible completions is displayed.@refill - -A typical value might look like this: - -@example -@group -completion-ignored-extensions - @result{} (".o" ".elc" "~" ".dvi") -@end group -@end example -@end defopt - -@node Standard File Names -@subsection Standard File Names - - Most of the file names used in Lisp programs are entered by the user. -But occasionally a Lisp program needs to specify a standard file name -for a particular use---typically, to hold customization information -about each user. For example, abbrev definitions are stored (by -default) in the file @file{~/.abbrev_defs}; the @code{completion} -package stores completions in the file @file{~/.completions}. These are -two of the many standard file names used by parts of Emacs for certain -purposes. - - Various operating systems have their own conventions for valid file -names and for which file names to use for user profile data. A Lisp -program which reads a file using a standard file name ought to use, on -each type of system, a file name suitable for that system. The function -@code{convert-standard-filename} makes this easy to do. - -@defun convert-standard-filename filename -This function alters the file name @var{filename} to fit the conventions -of the operating system in use, and returns the result as a new string. -@end defun - - The recommended way to specify a standard file name in a Lisp program -is to choose a name which fits the conventions of GNU and Unix systems, -usually with a nondirectory part that starts with a period, and pass it -to @code{convert-standard-filename} instead of using it directly. Here -is an example from the @code{completion} package: - -@example -(defvar save-completions-file-name - (convert-standard-filename "~/.completions") - "*The file name to save completions to.") -@end example - - On GNU and Unix systems, and on some other systems as well, -@code{convert-standard-filename} returns its argument unchanged. On -some other systems, it alters the name to fit the systems's conventions. - - For example, on MS-DOS the alterations made by this function include -converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the -middle of the name to @samp{.} if there is no other @samp{.}, inserting -a @samp{.} after eight characters if there is none, and truncating to -three characters after the @samp{.}. (It makes other changes as well.) -Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and -@file{.completions} becomes @file{_complet.ion}. - -@node Contents of Directories -@section Contents of Directories -@cindex directory-oriented functions -@cindex file names in directory - - A directory is a kind of file that contains other files entered under -various names. Directories are a feature of the file system. - - Emacs can list the names of the files in a directory as a Lisp list, -or display the names in a buffer using the @code{ls} shell command. In -the latter case, it can optionally display information about each file, -depending on the options passed to the @code{ls} command. - -@defun directory-files directory &optional full-name match-regexp nosort -This function returns a list of the names of the files in the directory -@var{directory}. By default, the list is in alphabetical order. - -If @var{full-name} is non-@code{nil}, the function returns the files' -absolute file names. Otherwise, it returns the names relative to -the specified directory. - -If @var{match-regexp} is non-@code{nil}, this function returns only -those file names that contain a match for that regular expression---the -other file names are excluded from the list. - -@c Emacs 19 feature -If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort -the list, so you get the file names in no particular order. Use this if -you want the utmost possible speed and don't care what order the files -are processed in. If the order of processing is visible to the user, -then the user will probably be happier if you do sort the names. - -@example -@group -(directory-files "~lewis") - @result{} ("#foo#" "#foo.el#" "." ".." - "dired-mods.el" "files.texi" - "files.texi.~1~") -@end group -@end example - -An error is signaled if @var{directory} is not the name of a directory -that can be read. -@end defun - -@defun file-name-all-versions file dirname -This function returns a list of all versions of the file named -@var{file} in directory @var{dirname}. -@end defun - -@defun insert-directory file switches &optional wildcard full-directory-p -This function inserts (in the current buffer) a directory listing for -directory @var{file}, formatted with @code{ls} according to -@var{switches}. It leaves point after the inserted text. - -The argument @var{file} may be either a directory name or a file -specification including wildcard characters. If @var{wildcard} is -non-@code{nil}, that means treat @var{file} as a file specification with -wildcards. - -If @var{full-directory-p} is non-@code{nil}, that means @var{file} is a -directory and switches do not contain @samp{-d}, so that the listing -should show the full contents of the directory. (The @samp{-d} option -to @code{ls} says to describe a directory itself rather than its -contents.) - -This function works by running a directory listing program whose name is -in the variable @code{insert-directory-program}. If @var{wildcard} is -non-@code{nil}, it also runs the shell specified by -@code{shell-file-name}, to expand the wildcards. -@end defun - -@defvar insert-directory-program -This variable's value is the program to run to generate a directory listing -for the function @code{insert-directory}. -@end defvar - -@node Create/Delete Dirs -@section Creating and Deleting Directories -@c Emacs 19 features - - Most Emacs Lisp file-manipulation functions get errors when used on -files that are directories. For example, you cannot delete a directory -with @code{delete-file}. These special functions exist to create and -delete directories. - -@defun make-directory dirname -This function creates a directory named @var{dirname}. -@end defun - -@defun delete-directory dirname -This function deletes the directory named @var{dirname}. The function -@code{delete-file} does not work for files that are directories; you -must use @code{delete-directory} for them. If the directory contains -any files, @code{delete-directory} signals an error. -@end defun - -@node Magic File Names -@section Making Certain File Names ``Magic'' -@cindex magic file names - -@c Emacs 19 feature -You can implement special handling for certain file names. This is -called making those names @dfn{magic}. You must supply a regular -expression to define the class of names (all those that match the -regular expression), plus a handler that implements all the primitive -Emacs file operations for file names that do match. - -The variable @code{file-name-handler-alist} holds a list of handlers, -together with regular expressions that determine when to apply each -handler. Each element has this form: - -@example -(@var{regexp} . @var{handler}) -@end example - -@noindent -All the Emacs primitives for file access and file name transformation -check the given file name against @code{file-name-handler-alist}. If -the file name matches @var{regexp}, the primitives handle that file by -calling @var{handler}. - -The first argument given to @var{handler} is the name of the primitive; -the remaining arguments are the arguments that were passed to that -operation. (The first of these arguments is typically the file name -itself.) For example, if you do this: - -@example -(file-exists-p @var{filename}) -@end example - -@noindent -and @var{filename} has handler @var{handler}, then @var{handler} is -called like this: - -@example -(funcall @var{handler} 'file-exists-p @var{filename}) -@end example - -Here are the operations that a magic file name handler gets to handle: - -@noindent -@code{add-name-to-file}, @code{copy-file}, @code{delete-directory}, -@code{delete-file},@* -@code{diff-latest-backup-file}, -@code{directory-file-name}, -@code{directory-files},@* -@code{dired-call-process}, -@code{dired-compress-file}, @code{dired-uncache}, -@code{expand-file-name},@* -@code{file-accessible-directory-p}, -@code{file-attributes}, @code{file-directory-p},@* -@code{file-executable-p}, @code{file-exists-p}, @code{file-local-copy}, -@code{file-modes}, @code{file-name-all-completions}, -@code{file-name-as-directory}, @code{file-name-completion},@* -@code{file-name-directory}, -@code{file-name-nondirectory}, -@code{file-name-sans-versions}, @code{file-newer-than-file-p}, -@code{file-ownership-preserved-p}, -@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p}, -@code{file-truename}, @code{file-writable-p}, -@code{find-backup-file-name}, -@code{get-file-buffer}, -@code{insert-directory},@* -@code{insert-file-contents}, -@code{load}, @code{make-directory}, -@code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes}, -@code{set-visited-file-modtime}, @code{shell-command}. -@code{unhandled-file-name-directory},@* -@code{vc-registered}, -@code{verify-visited-file-modtime}, @code{write-region}. - -Handlers for @code{insert-file-contents} typically need to clear the -buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the -@var{visit} argument is non-@code{nil}. This also has the effect of -unlocking the buffer if it is locked. - -The handler function must handle all of the above operations, and -possibly others to be added in the future. It need not implement all -these operations itself---when it has nothing special to do for a -certain operation, it can reinvoke the primitive, to handle the -operation ``in the usual way''. It should always reinvoke the primitive -for an operation it does not recognize. Here's one way to do this: - -@smallexample -(defun my-file-handler (operation &rest args) - ;; @r{First check for the specific operations} - ;; @r{that we have special handling for.} - (cond ((eq operation 'insert-file-contents) @dots{}) - ((eq operation 'write-region) @dots{}) - @dots{} - ;; @r{Handle any operation we don't know about.} - (t (let ((inhibit-file-name-handlers - (cons 'my-file-handler - (and (eq inhibit-file-name-operation operation) - inhibit-file-name-handlers))) - (inhibit-file-name-operation operation)) - (apply operation args))))) -@end smallexample - -When a handler function decides to call the ordinary Emacs primitive for -the operation at hand, it needs to prevent the primitive from calling -the same handler once again, thus leading to an infinite recursion. The -example above shows how to do this, with the variables -@code{inhibit-file-name-handlers} and -@code{inhibit-file-name-operation}. Be careful to use them exactly as -shown above; the details are crucial for proper behavior in the case of -multiple handlers, and for operations that have two file names that may -each have handlers. - -@defvar inhibit-file-name-handlers -This variable holds a list of handlers whose use is presently inhibited -for a certain operation. -@end defvar - -@defvar inhibit-file-name-operation -The operation for which certain handlers are presently inhibited. -@end defvar - -@defun find-file-name-handler file operation -This function returns the handler function for file name @var{file}, or -@code{nil} if there is none. The argument @var{operation} should be the -operation to be performed on the file---the value you will pass to the -handler as its first argument when you call it. The operation is needed -for comparison with @code{inhibit-file-name-operation}. -@end defun - -@defun file-local-copy filename -This function copies file @var{filename} to an ordinary non-magic file, -if it isn't one already. - -If @var{filename} specifies a ``magic'' file name, which programs -outside Emacs cannot directly read or write, this copies the contents to -an ordinary file and returns that file's name. - -If @var{filename} is an ordinary file name, not magic, then this function -does nothing and returns @code{nil}. -@end defun - -@defun unhandled-file-name-directory filename -This function returns the name of a directory that is not magic. -It uses the directory part of @var{filename} if that is not magic. -Otherwise, it asks the handler what to do. - -This is useful for running a subprocess; every subprocess must have a -non-magic directory to serve as its current directory, and this function -is a good way to come up with one. -@end defun - -@node Format Conversion -@section File Format Conversion - -@cindex file format conversion -@cindex encoding file formats -@cindex decoding file formats - The variable @code{format-alist} defines a list of @dfn{file formats}, -which describe textual representations used in files for the data (text, -text-properties, and possibly other information) in an Emacs buffer. -Emacs performs format conversion if appropriate when reading and writing -files. - -@defvar format-alist -This list contains one format definition for each defined file format. -@end defvar - -@cindex format definition -Each format definition is a list of this form: - -@example -(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn}) -@end example - -Here is what the elements in a format definition mean: - -@table @var -@item name -The name of this format. - -@item doc-string -A documentation string for the format. - -@item regexp -A regular expression which is used to recognize files represented in -this format. - -@item from-fn -A function to call to decode data in this format (to convert file data into -the usual Emacs data representation). - -The @var{from-fn} is called with two args, @var{begin} and @var{end}, -which specify the part of the buffer it should convert. It should convert -the text by editing it in place. Since this can change the length of the -text, @var{from-fn} should return the modified end position. - -One responsibility of @var{from-fn} is to make sure that the beginning -of the file no longer matches @var{regexp}. Otherwise it is likely to -get called again. - -@item to-fn -A function to call to encode data in this format (to convert -the usual Emacs data representation into this format). - -The @var{to-fn} is called with two args, @var{begin} and @var{end}, -which specify the part of the buffer it should convert. There are -two ways it can do the conversion: - -@itemize @bullet -@item -By editing the buffer in place. In this case, @var{to-fn} should -return the end-position of the range of text, as modified. - -@item -By returning a list of annotations. This is 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. The list must be sorted in -order of position when @var{to-fn} returns it. - -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 itemize - -@item modify -A flag, @code{t} if the encoding function modifies the buffer, and -@code{nil} if it works by returning a list of annotations. - -@item mode -A mode function to call after visiting a file converted from this -format. -@end table - -The function @code{insert-file-contents} automatically recognizes file -formats when it reads the specified file. It checks the text of the -beginning of the file against the regular expressions of the format -definitions, and if it finds a match, it calls the decoding function for -that format. Then it checks all the known formats over again. -It keeps checking them until none of them is applicable. - -Visiting a file, with @code{find-file-noselect} or the commands that use -it, performs conversion likewise (because it calls -@code{insert-file-contents}); it also calls the mode function for each -format that it decodes. It stores a list of the format names in the -buffer-local variable @code{buffer-file-format}. - -@defvar buffer-file-format -This variable states the format of the visited file. More precisely, -this is a list of the file format names that were decoded in the course -of visiting the current buffer's file. It is always local in all -buffers. -@end defvar - -When @code{write-region} writes data into a file, it first calls the -encoding functions for the formats listed in @code{buffer-file-format}, -in the order of appearance in the list. - -@defun format-write-file file format -This command writes the current buffer contents into the file @var{file} -in format @var{format}, and makes that format the default for future -saves of the buffer. The argument @var{format} is a list of format -names. -@end defun - -@defun format-find-file file format -This command finds the file @var{file}, converting it according to -format @var{format}. It also makes @var{format} the default if the -buffer is saved later. - -The argument @var{format} is a list of format names. If @var{format} is -@code{nil}, no conversion takes place. Interactively, typing just -@key{RET} for @var{format} specifies @code{nil}. -@end defun - -@defun format-insert-file file format %optional beg end -This command inserts the contents of file @var{file}, converting it -according to format @var{format}. If @var{beg} and @var{end} are -non-@code{nil}, they specify which part of the file to read, as in -@code{insert-file-contents} (@pxref{Reading from Files}). - -The return value is like what @code{insert-file-contents} returns: a -list of the absolute file name and the length of the data inserted -(after conversion). - -The argument @var{format} is a list of format names. If @var{format} is -@code{nil}, no conversion takes place. Interactively, typing just -@key{RET} for @var{format} specifies @code{nil}. -@end defun - -@defvar auto-save-file-format -This variable specifies the format to use for auto-saving. Its value is -a list of format names, just like the value of -@code{buffer-file-format}; but it is used instead of -@code{buffer-file-format} for writing auto-save files. This variable -is always local in all buffers. -@end defvar - -@node Files and MS-DOS -@section Files and MS-DOS -@cindex MS-DOS file types -@cindex file types on MS-DOS -@cindex text files and binary files -@cindex binary files and text files -@cindex Windows file types - - Emacs on MS-DOS and on Windows NT or 95 makes a distinction between -text files and binary files. This is necessary because ordinary text -files on MS-DOS use a two character sequence between lines: -carriage-return and linefeed (@sc{crlf}). Emacs expects just a newline -character (a linefeed) between lines. When Emacs reads or writes a text -file on MS-DOS, it needs to convert the line separators. This means it -needs to know which files are text files and which are binary. It makes -this decision when visiting a file, and records the decision in the -variable @code{buffer-file-type} for use when the file is saved. - - @xref{MS-DOS Subprocesses}, for a related feature for subprocesses. - -@defvar buffer-file-type -This variable, automatically local in each buffer, records the file type -of the buffer's visited file. The value is @code{nil} for text, -@code{t} for binary. -@end defvar - -@defun find-buffer-file-type filename -This function determines whether file @var{filename} is a text file -or a binary file. It returns @code{nil} for text, @code{t} for binary. -@end defun - -@defopt file-name-buffer-file-type-alist -This variable holds an alist for distinguishing text files from binary -files. Each element has the form (@var{regexp} . @var{type}), where -@var{regexp} is matched against the file name, and @var{type} may be is -@code{nil} for text, @code{t} for binary, or a function to call to -compute which. If it is a function, then it is called with a single -argument (the file name) and should return @code{t} or @code{nil}. -@end defopt - -@defopt default-buffer-file-type -This variable specifies the default file type for files whose names -don't indicate anything in particular. Its value should be @code{nil} -for text, or @code{t} for binary. -@end defopt - -@deffn Command find-file-text filename -Like @code{find-file}, but treat the file as text regardless of its name. -@end deffn - -@deffn Command find-file-binary filename -Like @code{find-file}, but treat the file as binary regardless of its -name. -@end deffn diff --git a/lispref/frames.texi b/lispref/frames.texi deleted file mode 100644 index f75b8a3b5eb..00000000000 --- a/lispref/frames.texi +++ /dev/null @@ -1,1363 +0,0 @@ -@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/frames -@node Frames, Positions, Windows, Top -@chapter Frames -@cindex frame - - A @dfn{frame} is a rectangle on the screen that contains one or more -Emacs windows. A frame initially contains a single main window (plus -perhaps a minibuffer window), which you can subdivide vertically or -horizontally into smaller windows. - -@cindex terminal frame -@cindex X window frame - When Emacs runs on a text-only terminal, it starts with one -@dfn{terminal frame}. If you create additional ones, Emacs displays -one and only one at any given time---on the terminal screen, of course. - - When Emacs communicates directly with an X server, it does not have a -terminal frame; instead, it starts with a single @dfn{X window frame}. -It can display multiple X window frames at the same time, each in its -own X window. - -@defun framep object -This predicate returns @code{t} if @var{object} is a frame, and -@code{nil} otherwise. -@end defun - -@menu -* Creating Frames:: Creating additional frames. -* Multiple Displays:: Creating frames on other X displays. -* Frame Parameters:: Controlling frame size, position, font, etc. -* Frame Titles:: Automatic updating of frame titles. -* Deleting Frames:: Frames last until explicitly deleted. -* Finding All Frames:: How to examine all existing frames. -* Frames and Windows:: A frame contains windows; - display of text always works through windows. -* Minibuffers and Frames:: How a frame finds the minibuffer to use. -* Input Focus:: Specifying the selected frame. -* Visibility of Frames:: Frames may be visible or invisible, or icons. -* Raising and Lowering:: Raising a frame makes it hide other X windows; - lowering it makes the others hide them. -* Frame Configurations:: Saving the state of all frames. -* Mouse Tracking:: Getting events that say when the mouse moves. -* Mouse Position:: Asking where the mouse is, or moving it. -* Pop-Up Menus:: Displaying a menu for the user to select from. -* Dialog Boxes:: Displaying a box to ask yes or no. -* Pointer Shapes:: Specifying the shape of the mouse pointer. -* X Selections:: Transferring text to and from other X clients. -* Color Names:: Getting the definitions of color names. -* Resources:: Getting resource values from the server. -* Server Data:: Getting info about the X server. -@end menu - - @xref{Display}, for related information. - -@node Creating Frames -@section Creating Frames - -To create a new frame, call the function @code{make-frame}. - -@defun make-frame &optional alist -This function creates a new frame. If you are using X, it makes -an X window frame; otherwise, it makes a terminal frame. - -The argument is an alist specifying frame parameters. Any parameters -not mentioned in @var{alist} default according to the value of the -variable @code{default-frame-alist}; parameters not specified even there -default from the standard X defaults file and X resources. - -The set of possible parameters depends in principle on what kind of -window system Emacs uses to display its frames. @xref{X Frame -Parameters}, for documentation of individual parameters you can specify. -@end defun - -@defvar before-make-frame-hook -A normal hook run by @code{make-frame} before it actually creates the -frame. -@end defvar - -@defvar after-make-frame-hook -A normal hook run by @code{make-frame} after it creates the frame. -@end defvar - -@node Multiple Displays -@section Multiple Displays -@cindex multiple displays -@cindex multiple X terminals -@cindex displays, multiple - - A single Emacs can talk to more than one X Windows display. -Initially, Emacs uses just one display---the one chosen with the -@code{DISPLAY} environment variable or with the @samp{--display} option -(@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to -another display, use the command @code{make-frame-on-display} or specify -the @code{display} frame parameter when you create the frame. - - Emacs treats each X server as a separate terminal, giving each one its -own selected frame and its own minibuffer windows. A few Lisp variables -have values local to the current terminal (that is, the terminal -corresponding to the currently selected frame): these are -@code{default-minibuffer-frame}, @code{defining-kbd-macro}, -@code{last-kbd-macro}, and @code{system-key-alist}. These variables are -always terminal-local and can never be buffer-local. - - A single X server can handle more than one screen. A display name -@samp{@var{host}.@var{server}.@var{screen}} has three parts; the last -part specifies the screen number for a given server. When you use two -screens belonging to one server, Emacs knows by the similarity in their -names that they share a single keyboard, and it treats them as a single -terminal. - -@deffn Command make-frame-on-display display &optional parameters -This creates a new frame on display @var{display}, taking the other -frame parameters from @var{parameters}. Aside from the @var{display} -argument, it is like @code{make-frame} (@pxref{Creating Frames}). -@end deffn - -@defun x-display-list -This returns a list that indicates which X displays Emacs has a -connection to. The elements of the list are strings, and each one is -a display name. -@end defun - -@defun x-open-connection display &optional xrm-string -This function opens a connection to the X display @var{display}. It -does not create a frame on that display, but it permits you to check -that communication can be established with that display. - -The optional argument @var{resource-string}, if not @code{nil}, is a -string of resource names and values, in the same format used in the -@file{.Xresources} file. The values you specify override the resource -values recorded in the X server itself; they apply to all Emacs frames -created on this display. Here's an example of what this string might -look like: - -@example -"*BorderWidth: 3\n*InternalBorder: 2\n" -@end example - -@xref{Resources}. -@end defun - -@defun x-close-connection display -This function closes the connection to display @var{display}. Before -you can do this, you must first delete all the frames that were open on -that display (@pxref{Deleting Frames}). -@end defun - -@node Frame Parameters -@section Frame Parameters - -A frame has many parameters that control its appearance and behavior. -Just what parameters a frame has depends on what display mechanism it -uses. - -Frame parameters exist for the sake of window systems. A terminal frame -has a few parameters, mostly for compatibility's sake; only the height, -width and @code{buffer-predicate} parameters really do something. - -@menu -* Parameter Access:: How to change a frame's parameters. -* Initial Parameters:: Specifying frame parameters when you make a frame. -* X Frame Parameters:: List of frame parameters. -* Size and Position:: Changing the size and position of a frame. -@end menu - -@node Parameter Access -@subsection Access to Frame Parameters - -These functions let you read and change the parameter values of a -frame. - -@defun frame-parameters frame -The function @code{frame-parameters} returns an alist listing all the -parameters of @var{frame} and their values. -@end defun - -@defun modify-frame-parameters frame alist -This function alters the parameters of frame @var{frame} based on the -elements of @var{alist}. Each element of @var{alist} has the form -@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a -parameter. If you don't mention a parameter in @var{alist}, its value -doesn't change. -@end defun - -@node Initial Parameters -@subsection Initial Frame Parameters - -You can specify the parameters for the initial startup frame -by setting @code{initial-frame-alist} in your @file{.emacs} file. - -@defvar initial-frame-alist -This variable's value is an alist of parameter values used when creating -the initial X window frame. You can set this variable to specify the -appearance of the initial frame without altering subsequent frames. -Each element has the form: - -@example -(@var{parameter} . @var{value}) -@end example - -Emacs creates the initial frame before it reads your @file{~/.emacs} -file. After reading that file, Emacs checks @code{initial-frame-alist}, -and applies the parameter settings in the altered value to the already -created initial frame. - -If these settings affect the frame geometry and appearance, you'll see -the frame appear with the wrong ones and then change to the specified -ones. If that bothers you, you can specify the same geometry and -appearance with X resources; those do take affect before the frame is -created. @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}. - -X resource settings typically apply to all frames. If you want to -specify some X resources solely for the sake of the initial frame, and -you don't want them to apply to subsequent frames, here's how to achieve -this. Specify parameters in @code{default-frame-alist} to override the -X resources for subsequent frames; then, to prevent these from affecting -the initial frame, specify the same parameters in -@code{initial-frame-alist} with values that match the X resources. -@end defvar - -If these parameters specify a separate minibuffer-only frame with -@code{(minibuffer . nil)}, and you have not created one, Emacs creates -one for you. - -@defvar minibuffer-frame-alist -This variable's value is an alist of parameter values used when creating -an initial minibuffer-only frame---if such a frame is needed, according -to the parameters for the main initial frame. -@end defvar - -@defvar default-frame-alist -This is an alist specifying default values of frame parameters for all -Emacs frames---the first frame, and subsequent frames. In many cases, -you can get the same results by means of X resources. -@end defvar - -See also @code{special-display-frame-alist}, in @ref{Choosing Window}. - -If you use options that specify window appearance when you invoke Emacs, -they take effect by adding elements to @code{default-frame-alist}. One -exception is @samp{-geometry}, which adds the specified position to -@code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs, -The GNU Emacs Manual}. - -@node X Frame Parameters -@subsection X Window Frame Parameters - -Just what parameters a frame has depends on what display mechanism it -uses. Here is a table of the parameters of an X window frame; of these, -@code{name}, @code{height}, @code{width}, and @code{buffer-predicate} -provide meaningful information in non-X frames. - -@table @code -@item name -The name of the frame. Most window managers display the frame's name in -the frame's border, at the top of the frame. If you don't specify a -name, and you have more than one frame, Emacs sets the frame name based -on the buffer displayed in the frame's selected window. - -If you specify the frame name explicitly when you create the frame, the -name is also used (instead of the name of the Emacs executable) when -looking up X resources for the frame. - -@item display -The display on which to open this frame. It should be a string of the -form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the -@code{DISPLAY} environment variable. - -@item left -The screen position of the left edge, in pixels, with respect to the -left edge of the screen. The value may be a positive number @var{pos}, -or a list of the form @code{(+ @var{pos})} which permits specifying a -negative @var{pos} value. - -A negative number @minus{}@var{pos}, or a list of the form @code{(- -@var{pos})}, actually specifies the position of the right edge of the -window with respect to the right edge of the screen. A positive value -of @var{pos} counts toward the left. If the parameter is a negative -integer @minus{}@var{pos} then @var{pos} is positive! - -Some window managers ignore program-specified positions. If you want to -be sure the position you specify is not ignored, specify a -non-@code{nil} value for the @code{user-position} parameter as well. - -@item top -The screen position of the top edge, in pixels, with respect to the -top edge of the screen. The value may be a positive number @var{pos}, -or a list of the form @code{(+ @var{pos})} which permits specifying a -negative @var{pos} value. - -A negative number @minus{}@var{pos}, or a list of the form @code{(- -@var{pos})}, actually specifies the position of the bottom edge of the -window with respect to the bottom edge of the screen. A positive value -of @var{pos} counts toward the top. If the parameter is a negative -integer @minus{}@var{pos} then @var{pos} is positive! - -Some window managers ignore program-specified positions. If you want to -be sure the position you specify is not ignored, specify a -non-@code{nil} value for the @code{user-position} parameter as well. - -@item icon-left -The screen position of the left edge @emph{of the frame's icon}, in -pixels, counting from the left edge of the screen. This takes effect if -and when the frame is iconified. - -@item icon-top -The screen position of the top edge @emph{of the frame's icon}, in -pixels, counting from the top edge of the screen. This takes effect if -and when the frame is iconified. - -@item user-position -When you create a frame and specify its screen position with the -@code{left} and @code{top} parameters, use this parameter to say whether -the specified position was user-specified (explicitly requested in some -way by a human user) or merely program-specified (chosen by a program). -A non-@code{nil} value says the position was user-specified. - -Window managers generally heed user-specified positions, and some heed -program-specified positions too. But many ignore program-specified -positions, placing the window in a default fashion or letting the user -place it with the mouse. Some window managers, including @code{twm}, -let the user specify whether to obey program-specified positions or -ignore them. - -When you call @code{make-frame}, you should specify a non-@code{nil} -value for this parameter if the values of the @code{left} and @code{top} -parameters represent the user's stated preference; otherwise, use -@code{nil}. - -@item height -The height of the frame contents, in characters. (To get the height in -pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.) - -@item width -The width of the frame contents, in characters. (To get the height in -pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.) - -@item window-id -The number of the X window for the frame. - -@item minibuffer -Whether this frame has its own minibuffer. The value @code{t} means -yes, @code{nil} means no, @code{only} means this frame is just a -minibuffer. If the value is a minibuffer window (in some other frame), -the new frame uses that minibuffer. - -@item buffer-predicate -The buffer-predicate function for this frame. The function -@code{other-buffer} uses this predicate (from the selected frame) to -decide which buffers it should consider, if the predicate is not -@code{nil}. It calls the predicate with one arg, a buffer, once for -each buffer; if the predicate returns a non-@code{nil} value, it -considers that buffer. - -@item font -The name of the font for displaying text in the frame. This is a -string. - -@item auto-raise -Whether selecting the frame raises it (non-@code{nil} means yes). - -@item auto-lower -Whether deselecting the frame lowers it (non-@code{nil} means yes). - -@item vertical-scroll-bars -Whether the frame has scroll bars for vertical scrolling -(non-@code{nil} means yes). - -@item horizontal-scroll-bars -Whether the frame has scroll bars for horizontal scrolling -(non-@code{nil} means yes). (Horizontal scroll bars are not currently -implemented.) - -@item scroll-bar-width -The width of the vertical scroll bar, in pixels. - -@item icon-type -The type of icon to use for this frame when it is iconified. If the -value is a string, that specifies a file containing a bitmap to use. -Any other non-@code{nil} value specifies the default bitmap icon (a -picture of a gnu); @code{nil} specifies a text icon. - -@item icon-name -The name to use in the icon for this frame, when and if the icon -appears. If this is @code{nil}, the frame's title is used. - -@item foreground-color -The color to use for the image of a character. This is a string; the X -server defines the meaningful color names. - -@item background-color -The color to use for the background of characters. - -@item mouse-color -The color for the mouse pointer. - -@item cursor-color -The color for the cursor that shows point. - -@item border-color -The color for the border of the frame. - -@item cursor-type -The way to display the cursor. The legitimate values are @code{bar}, -@code{box}, and @code{(bar . @var{width})}. The symbol @code{box} -specifies an ordinary black box overlaying the character after point; -that is the default. The symbol @code{bar} specifies a vertical bar -between characters as the cursor. @code{(bar . @var{width})} specifies -a bar @var{width} pixels wide. - -@item border-width -The width in pixels of the window border. - -@item internal-border-width -The distance in pixels between text and border. - -@item unsplittable -If non-@code{nil}, this frame's window is never split automatically. - -@item visibility -The state of visibility of the frame. There are three possibilities: -@code{nil} for invisible, @code{t} for visible, and @code{icon} for -iconified. @xref{Visibility of Frames}. - -@item menu-bar-lines -The number of lines to allocate at the top of the frame for a menu bar. -The default is 1. @xref{Menu Bar}. (In Emacs versions that use the X -toolkit, there is only one menu bar line; all that matters about the -number you specify is whether it is greater than zero.) - -@item parent-id -@c ??? Not yet working. -The X window number of the window that should be the parent of this one. -Specifying this lets you create an Emacs window inside some other -application's window. (It is not certain this will be implemented; try -it and see if it works.) -@end table - -@node Size and Position -@subsection Frame Size And Position - - You can read or change the size and position of a frame using the -frame parameters @code{left}, @code{top}, @code{height}, and -@code{width}. Whatever geometry parameters you don't specify are chosen -by the window manager in its usual fashion. - - Here are some special features for working with sizes and positions: - -@defun set-frame-position frame left top -This function sets the position of the top left corner of @var{frame} to -@var{left} and @var{top}. These arguments are measured in pixels, and -count from the top left corner of the screen. Negative parameter values -count up or rightward from the top left corner of the screen. -@end defun - -@defun frame-height &optional frame -@defunx frame-width &optional frame -These functions return the height and width of @var{frame}, measured in -characters. If you don't supply @var{frame}, they use the selected -frame. -@end defun - -@defun frame-pixel-height &optional frame -@defunx frame-pixel-width &optional frame -These functions return the height and width of @var{frame}, measured in -pixels. If you don't supply @var{frame}, they use the selected frame. -@end defun - -@defun frame-char-height &optional frame -@defunx frame-char-width &optional frame -These functions return the height and width of a character in -@var{frame}, measured in pixels. The values depend on the choice of -font. If you don't supply @var{frame}, these functions use the selected -frame. -@end defun - -@defun set-frame-size frame cols rows -This function sets the size of @var{frame}, measured in characters; -@var{cols} and @var{rows} specify the new width and height. - -To set the size based on values measured in pixels, use -@code{frame-char-height} and @code{frame-char-width} to convert -them to units of characters. -@end defun - - The old-fashioned functions @code{set-screen-height} and -@code{set-screen-width}, which were used to specify the height and width -of the screen in Emacs versions that did not support multiple frames, -are still usable. They apply to the selected frame. @xref{Screen -Size}. - -@defun x-parse-geometry geom -@cindex geometry specification -The function @code{x-parse-geometry} converts a standard X windows -geometry string to an alist that you can use as part of the argument to -@code{make-frame}. - -The alist describes which parameters were specified in @var{geom}, and -gives the values specified for them. Each element looks like -@code{(@var{parameter} . @var{value})}. The possible @var{parameter} -values are @code{left}, @code{top}, @code{width}, and @code{height}. - -For the size parameters, the value must be an integer. The position -parameter names @code{left} and @code{top} are not totally accurate, -because some values indicate the position of the right or bottom edges -instead. These are the @var{value} possibilities for the position -parameters: - -@table @asis -@item an integer -A positive integer relates the left edge or top edge of the window to -the left or top edge of the screen. A negative integer relates the -right or bottom edge of the window to the right or bottom edge of the -screen. - -@item @code{(+ @var{position})} -This specifies the position of the left or top edge of the window -relative to the left or top edge of the screen. The integer -@var{position} may be positive or negative; a negative value specifies a -position outside the screen. - -@item @code{(- @var{position})} -This specifies the position of the right or bottom edge of the window -relative to the right or bottom edge of the screen. The integer -@var{position} may be positive or negative; a negative value specifies a -position outside the screen. -@end table - -Here is an example: - -@example -(x-parse-geometry "35x70+0-0") - @result{} ((width . 35) (height . 70) - (left . 0) (top - 0)) -@end example -@end defun - -@ignore -New functions @code{set-frame-height} and @code{set-frame-width} set the -size of a specified frame. The frame is the first argument; the size is -the second. -@end ignore - -@node Frame Titles -@section Frame Titles - -Every frame has a title; most window managers display the frame title at -the top of the frame. You can specify an explicit title with the -@code{name} frame property. But normally you don't specify this -explicitly, and Emacs computes the title automatically. - -Emacs computes the frame title based on a template stored in the -variable @code{frame-title-format}. - -@defvar frame-title-format -This variable specifies how to compute a title for a frame -when you have not explicitly specified one. - -The variable's value is actually a mode line construct, just like -@code{mode-line-format}. @xref{Mode Line Data}. -@end defvar - -@defvar icon-title-format -This variable specifies how to compute the title for an iconified frame, -when you have not explicitly specified the frame title. This title -appears in the icon itself. -@end defvar - -@defvar multiple-frames -This variable is set automatically by Emacs. Its value is @code{t} when -there are two or more frames (not counting minibuffer-only frames or -invisible frames). The default value of @code{frame-title-format} uses -@code{multiple-frames} so as to put the buffer name in the frame title -only when there is more than one frame. -@end defvar - -@node Deleting Frames -@section Deleting Frames -@cindex deletion of frames - -Frames remain potentially visible until you explicitly @dfn{delete} -them. A deleted frame cannot appear on the screen, but continues to -exist as a Lisp object until there are no references to it. There is no -way to cancel the deletion of a frame aside from restoring a saved frame -configuration (@pxref{Frame Configurations}); this is similar to the -way windows behave. - -@deffn Command delete-frame &optional frame -This function deletes the frame @var{frame}. By default, @var{frame} is -the selected frame. -@end deffn - -@defun frame-live-p frame -The function @code{frame-live-p} returns non-@code{nil} if the frame -@var{frame} has not been deleted. -@end defun - - Some window managers provide a command to delete a window. These work -by sending a special message to the program that operates the window. -When Emacs gets one of these commands, it generates a -@code{delete-frame} event, whose normal definition is a command that -calls the function @code{delete-frame}. @xref{Misc Events}. - -@node Finding All Frames -@section Finding All Frames - -@defun frame-list -The function @code{frame-list} returns a list of all the frames that -have not been deleted. It is analogous to @code{buffer-list} for -buffers. The list that you get is newly created, so modifying the list -doesn't have any effect on the internals of Emacs. -@end defun - -@defun visible-frame-list -This function returns a list of just the currently visible frames. -@xref{Visibility of Frames}. (Terminal frames always count as -``visible'', even though only the selected one is actually displayed.) -@end defun - -@defun next-frame &optional frame minibuf -The function @code{next-frame} lets you cycle conveniently through all -the frames from an arbitrary starting point. It returns the ``next'' -frame after @var{frame} in the cycle. If @var{frame} is omitted or -@code{nil}, it defaults to the selected frame. - -The second argument, @var{minibuf}, says which frames to consider: - -@table @asis -@item @code{nil} -Exclude minibuffer-only frames. -@item @code{visible} -Consider all visible frames. -@item 0 -Consider all visible or iconified frames. -@item a window -Consider only the frames using that particular window as their -minibuffer. -@item anything else -Consider all frames. -@end table -@end defun - -@defun previous-frame &optional frame minibuf -Like @code{next-frame}, but cycles through all frames in the opposite -direction. -@end defun - - See also @code{next-window} and @code{previous-window}, in @ref{Cyclic -Window Ordering}. - -@node Frames and Windows -@section Frames and Windows - - Each window is part of one and only one frame; you can get the frame -with @code{window-frame}. - -@defun window-frame window -This function returns the frame that @var{window} is on. -@end defun - - All the non-minibuffer windows in a frame are arranged in a cyclic -order. The order runs from the frame's top window, which is at the -upper left corner, down and to the right, until it reaches the window at -the lower right corner (always the minibuffer window, if the frame has -one), and then it moves back to the top. - -@defun frame-top-window frame -This returns the topmost, leftmost window of frame @var{frame}. -@end defun - -At any time, exactly one window on any frame is @dfn{selected within the -frame}. The significance of this designation is that selecting the -frame also selects this window. You can get the frame's current -selected window with @code{frame-selected-window}. - -@defun frame-selected-window frame -This function returns the window on @var{frame} that is selected within -@var{frame}. -@end defun - -Conversely, selecting a window for Emacs with @code{select-window} also -makes that window selected within its frame. @xref{Selecting Windows}. - -Another function that (usually) returns one of the windows in a frame is -@code{minibuffer-window}. @xref{Minibuffer Misc}. - -@node Minibuffers and Frames -@section Minibuffers and Frames - -Normally, each frame has its own minibuffer window at the bottom, which -is used whenever that frame is selected. If the frame has a minibuffer, -you can get it with @code{minibuffer-window} (@pxref{Minibuffer Misc}). - -However, you can also create a frame with no minibuffer. Such a frame -must use the minibuffer window of some other frame. When you create the -frame, you can specify explicitly the minibuffer window to use (in some -other frame). If you don't, then the minibuffer is found in the frame -which is the value of the variable @code{default-minibuffer-frame}. Its -value should be a frame that does have a minibuffer. - -If you use a minibuffer-only frame, you might want that frame to raise -when you enter the minibuffer. If so, set the variable -@code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}. - -@defvar default-minibuffer-frame -This variable specifies the frame to use for the minibuffer window, by -default. It is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Displays}. -@end defvar - -@node Input Focus -@section Input Focus -@cindex input focus -@cindex selected frame - -At any time, one frame in Emacs is the @dfn{selected frame}. The selected -window always resides on the selected frame. - -@defun selected-frame -This function returns the selected frame. -@end defun - -The X server normally directs keyboard input to the X window that the -mouse is in. Some window managers use mouse clicks or keyboard events -to @dfn{shift the focus} to various X windows, overriding the normal -behavior of the server. - -Lisp programs can switch frames ``temporarily'' by calling -the function @code{select-frame}. This does not override the window -manager; rather, it escapes from the window manager's control until -that control is somehow reasserted. - -When using a text-only terminal, there is no window manager; therefore, -@code{switch-frame} is the only way to switch frames, and the effect -lasts until overridden by a subsequent call to @code{switch-frame}. -Only the selected terminal frame is actually displayed on the terminal. -Each terminal screen except for the initial one has a number, and the -number of the selected frame appears in the mode line after the word -@samp{Emacs} (@pxref{Mode Line Variables}). - -@c ??? This is not yet implemented properly. -@defun select-frame frame -This function selects frame @var{frame}, temporarily disregarding the -focus of the X server if any. The selection of @var{frame} lasts until -the next time the user does something to select a different frame, or -until the next time this function is called. -@end defun - -Emacs cooperates with the X server and the window managers by arranging -to select frames according to what the server and window manager ask -for. It does so by generating a special kind of input event, called a -@dfn{focus} event. The command loop handles a focus event by calling -@code{handle-switch-frame}. @xref{Focus Events}. - -@deffn Command handle-switch-frame frame -This function handles a focus event by selecting frame @var{frame}. - -Focus events normally do their job by invoking this command. -Don't call it for any other reason. -@end deffn - -@defun redirect-frame-focus frame focus-frame -This function redirects focus from @var{frame} to @var{focus-frame}. -This means that @var{focus-frame} will receive subsequent keystrokes -intended for @var{frame}. After such an event, the value of -@code{last-event-frame} will be @var{focus-frame}. Also, switch-frame -events specifying @var{frame} will instead select @var{focus-frame}. - -If @var{focus-frame} is @code{nil}, that cancels any existing -redirection for @var{frame}, which therefore once again receives its own -events. - -One use of focus redirection is for frames that don't have minibuffers. -These frames use minibuffers on other frames. Activating a minibuffer -on another frame redirects focus to that frame. This puts the focus on -the minibuffer's frame, where it belongs, even though the mouse remains -in the frame that activated the minibuffer. - -Selecting a frame can also change focus redirections. Selecting frame -@code{bar}, when @code{foo} had been selected, changes any redirections -pointing to @code{foo} so that they point to @code{bar} instead. This -allows focus redirection to work properly when the user switches from -one frame to another using @code{select-window}. - -This means that a frame whose focus is redirected to itself is treated -differently from a frame whose focus is not redirected. -@code{select-frame} affects the former but not the latter. - -The redirection lasts until @code{redirect-frame-focus} is called to -change it. -@end defun - -@node Visibility of Frames -@section Visibility of Frames -@cindex visible frame -@cindex invisible frame -@cindex iconified frame -@cindex frame visibility - -An X window frame may be @dfn{visible}, @dfn{invisible}, or -@dfn{iconified}. If it is visible, you can see its contents. If it is -iconified, the frame's contents do not appear on the screen, but an icon -does. If the frame is invisible, it doesn't show on the screen, not -even as an icon. - -Visibility is meaningless for terminal frames, since only the selected -one is actually displayed in any case. - -@deffn Command make-frame-visible &optional frame -This function makes frame @var{frame} visible. If you omit @var{frame}, -it makes the selected frame visible. -@end deffn - -@deffn Command make-frame-invisible &optional frame -This function makes frame @var{frame} invisible. If you omit -@var{frame}, it makes the selected frame invisible. -@end deffn - -@deffn Command iconify-frame &optional frame -This function iconifies frame @var{frame}. If you omit @var{frame}, it -iconifies the selected frame. -@end deffn - -@defun frame-visible-p frame -This returns the visibility status of frame @var{frame}. The value is -@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and -@code{icon} if it is iconified. -@end defun - - The visibility status of a frame is also available as a frame -parameter. You can read or change it as such. @xref{X Frame -Parameters}. - - The user can iconify and deiconify frames with the window manager. -This happens below the level at which Emacs can exert any control, but -Emacs does provide events that you can use to keep track of such -changes. @xref{Misc Events}. - -@node Raising and Lowering -@section Raising and Lowering Frames - -The X Window System uses a desktop metaphor. Part of this metaphor is -the idea that windows are stacked in a notional third dimension -perpendicular to the screen surface, and thus ordered from ``highest'' -to ``lowest''. Where two windows overlap, the one higher up covers the -one underneath. Even a window at the bottom of the stack can be seen if -no other window overlaps it. - -@cindex raising a frame -@cindex lowering a frame -A window's place in this ordering is not fixed; in fact, users tend to -change the order frequently. @dfn{Raising} a window means moving it -``up'', to the top of the stack. @dfn{Lowering} a window means moving -it to the bottom of the stack. This motion is in the notional third -dimension only, and does not change the position of the window on the -screen. - -You can raise and lower Emacs's X windows with these functions: - -@deffn Command raise-frame frame -This function raises frame @var{frame}. -@end deffn - -@deffn Command lower-frame frame -This function lowers frame @var{frame}. -@end deffn - -@defopt minibuffer-auto-raise -If this is non-@code{nil}, activation of the minibuffer raises the frame -that the minibuffer window is in. -@end defopt - -You can also enable auto-raise (raising automatically when a frame is -selected) or auto-lower (lowering automatically when it is deselected) -for any frame using frame parameters. @xref{X Frame Parameters}. - -@node Frame Configurations -@section Frame Configurations -@cindex frame configuration - - A @dfn{frame configuration} records the current arrangement of frames, -all their properties, and the window configuration of each one. - -@defun current-frame-configuration -This function returns a frame configuration list that describes -the current arrangement of frames and their contents. -@end defun - -@defun set-frame-configuration configuration -This function restores the state of frames described in -@var{configuration}. -@end defun - -@node Mouse Tracking -@section Mouse Tracking -@cindex mouse tracking -@cindex tracking the mouse - -Sometimes it is useful to @dfn{track} the mouse, which means to display -something to indicate where the mouse is and move the indicator as the -mouse moves. For efficient mouse tracking, you need a way to wait until -the mouse actually moves. - -The convenient way to track the mouse is to ask for events to represent -mouse motion. Then you can wait for motion by waiting for an event. In -addition, you can easily handle any other sorts of events that may -occur. That is useful, because normally you don't want to track the -mouse forever---only until some other event, such as the release of a -button. - -@defspec track-mouse body@dots{} -Execute @var{body}, meanwhile generating input events for mouse motion. -The code in @var{body} can read these events with @code{read-event} or -@code{read-key-sequence}. @xref{Motion Events}, for the format of mouse -motion events. - -The value of @code{track-mouse} is that of the last form in @var{body}. -@end defspec - -The usual purpose of tracking mouse motion is to indicate on the screen -the consequences of pushing or releasing a button at the current -position. - -In many cases, you can avoid the need to track the mouse by using -the @code{mouse-face} text property (@pxref{Special Properties}). -That works at a much lower level and runs more smoothly than -Lisp-level mouse tracking. - -@ignore -@c These are not implemented yet. - -These functions change the screen appearance instantaneously. The -effect is transient, only until the next ordinary Emacs redisplay. That -is ok for mouse tracking, since it doesn't make sense for mouse tracking -to change the text, and the body of @code{track-mouse} normally reads -the events itself and does not do redisplay. - -@defun x-contour-region window beg end -This function draws lines to make a box around the text from @var{beg} -to @var{end}, in window @var{window}. -@end defun - -@defun x-uncontour-region window beg end -This function erases the lines that would make a box around the text -from @var{beg} to @var{end}, in window @var{window}. Use it to remove -a contour that you previously made by calling @code{x-contour-region}. -@end defun - -@defun x-draw-rectangle frame left top right bottom -This function draws a hollow rectangle on frame @var{frame} with the -specified edge coordinates, all measured in pixels from the inside top -left corner. It uses the cursor color, the one used for indicating the -location of point. -@end defun - -@defun x-erase-rectangle frame left top right bottom -This function erases a hollow rectangle on frame @var{frame} with the -specified edge coordinates, all measured in pixels from the inside top -left corner. Erasure means redrawing the text and background that -normally belong in the specified rectangle. -@end defun -@end ignore - -@node Mouse Position -@section Mouse Position -@cindex mouse position -@cindex position of mouse - - The functions @code{mouse-position} and @code{set-mouse-position} -give access to the current position of the mouse. - -@defun mouse-position -This function returns a description of the position of the mouse. The -value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x} -and @var{y} are integers giving the position in characters relative to -the top left corner of the inside of @var{frame}. -@end defun - -@defun set-mouse-position frame x y -This function @dfn{warps the mouse} to position @var{x}, @var{y} in -frame @var{frame}. The arguments @var{x} and @var{y} are integers, -giving the position in characters relative to the top left corner of the -inside of @var{frame}. -@end defun - -@defun mouse-pixel-position -This function is like @code{mouse-position} except that it returns -coordinates in units of pixels rather than units of characters. -@end defun - -@defun set-mouse-pixel-position frame x y -This function warps the mouse like @code{set-mouse-position} except that -@var{x} and @var{y} are in units of pixels rather than units of -characters. These coordinates are not required to be within the frame. -@end defun - -@need 3000 - -@node Pop-Up Menus -@section Pop-Up Menus - - When using X windows, a Lisp program can pop up a menu which the -user can choose from with the mouse. - -@defun x-popup-menu position menu -This function displays a pop-up menu and returns an indication of -what selection the user makes. - -The argument @var{position} specifies where on the screen to put the -menu. It can be either a mouse button event (which says to put the menu -where the user actuated the button) or a list of this form: - -@example -((@var{xoffset} @var{yoffset}) @var{window}) -@end example - -@noindent -where @var{xoffset} and @var{yoffset} are coordinates, measured in -pixels, counting from the top left corner of @var{window}'s frame. - -If @var{position} is @code{t}, it means to use the current mouse -position. If @var{position} is @code{nil}, it means to precompute the -key binding equivalents for the keymaps specified in @var{menu}, -without actually displaying or popping up the menu. - -The argument @var{menu} says what to display in the menu. It can be a -keymap or a list of keymaps (@pxref{Menu Keymaps}). Alternatively, it -can have the following form: - -@example -(@var{title} @var{pane1} @var{pane2}...) -@end example - -@noindent -where each pane is a list of form - -@example -(@var{title} (@var{line} . @var{item})...) -@end example - -Each @var{line} should be a string, and each @var{item} should be the -value to return if that @var{line} is chosen. -@end defun - - @strong{Usage note:} Don't use @code{x-popup-menu} to display a menu if -a prefix key with a menu keymap would do the job. If you use a menu -keymap to implement a menu, @kbd{C-h c} and @kbd{C-h a} can see the -individual items in that menu and provide help for them. If instead you -implement the menu by defining a command that calls @code{x-popup-menu}, -the help facilities cannot know what happens inside that command, so -they cannot give any help for the menu's items. - - The menu bar mechanism, which lets you switch between submenus by -moving the mouse, cannot look within the definition of a command to see -that it calls @code{x-popup-menu}. Therefore, if you try to implement a -submenu using @code{x-popup-menu}, it cannot work with the menu bar in -an integrated fashion. This is why all menu bar submenus are -implemented with menu keymaps within the parent menu, and never with -@code{x-popup-menu}. @xref{Menu Bar}, - - If you want a menu bar submenu to have contents that vary, you should -still use a menu keymap to implement it. To make the contents vary, add -a hook function to @code{menu-bar-update-hook} to update the contents of -the menu keymap as necessary. - -@node Dialog Boxes -@section Dialog Boxes -@cindex dialog boxes - - A dialog box is a variant of a pop-up menu. It looks a little -different (if Emacs uses an X toolkit), it always appears in the center -of a frame, and it has just one level and one pane. The main use of -dialog boxes is for asking questions that the user can answer with -``yes'', ``no'', and a few other alternatives. The functions -@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the -keyboard, when called from commands invoked by mouse clicks. - -@defun x-popup-dialog position contents -This function displays a pop-up dialog box and returns an indication of -what selection the user makes. The argument @var{contents} specifies -the alternatives to offer; it has this format: - -@example -(@var{title} (@var{string} . @var{value})@dots{}) -@end example - -@noindent -which looks like the list that specifies a single pane for -@code{x-popup-menu}. - -The return value is @var{value} from the chosen alternative. - -An element of the list may be just a string instead of a cons cell -@code{(@var{string} . @var{value})}. That makes a box that cannot -be selected. - -If @code{nil} appears in the list, it separates the left-hand items from -the right-hand items; items that precede the @code{nil} appear on the -left, and items that follow the @code{nil} appear on the right. If you -don't include a @code{nil} in the list, then approximately half the -items appear on each side. - -Dialog boxes always appear in the center of a frame; the argument -@var{position} specifies which frame. The possible values are as in -@code{x-popup-menu}, but the precise coordinates don't matter; only the -frame matters. - -If your Emacs executable does not use an X toolkit, then it cannot -display a real dialog box; so instead it displays the same items in a -pop-up menu in the center of the frame. -@end defun - -@node Pointer Shapes -@section Pointer Shapes -@cindex pointer shape -@cindex mouse pointer shape - - These variables specify which shape to use for the mouse pointer in -various situations: - -@table @code -@item x-pointer-shape -@vindex x-pointer-shape -This variable specifies the pointer shape to use ordinarily in the Emacs -frame. - -@item x-sensitive-text-pointer-shape -@vindex x-sensitive-text-pointer-shape -This variable specifies the pointer shape to use when the mouse -is over mouse-sensitive text. -@end table - - These variables affect newly created frames. They do not normally -affect existing frames; however, if you set the mouse color of a frame, -that also updates its pointer shapes based on the current values of -these variables. @xref{X Frame Parameters}. - - The values you can use, to specify either of these pointer shapes, are -defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos -@key{RET} x-pointer @key{RET}} to see a list of them. - -@node X Selections -@section X Selections -@cindex selection (for X windows) - -The X server records a set of @dfn{selections} which permit transfer of -data between application programs. The various selections are -distinguished by @dfn{selection types}, represented in Emacs by -symbols. X clients including Emacs can read or set the selection for -any given type. - -@defun x-set-selection type data -This function sets a ``selection'' in the X server. It takes two -arguments: a selection type @var{type}, and the value to assign to it, -@var{data}. If @var{data} is @code{nil}, it means to clear out the -selection. Otherwise, @var{data} may be a string, a symbol, an integer -(or a cons of two integers or list of two integers), an overlay, or a -cons of two markers pointing to the same buffer. An overlay or a pair -of markers stands for text in the overlay or between the markers. - -The data may also be a vector of valid non-vector selection values. - -Each possible @var{type} has its own selection value, which changes -independently. The usual values of @var{type} are @code{PRIMARY} and -@code{SECONDARY}; these are symbols with upper-case names, in accord -with X Window System conventions. The default is @code{PRIMARY}. -@end defun - -@defun x-get-selection &optional type data-type -This function accesses selections set up by Emacs or by other X -clients. It takes two optional arguments, @var{type} and -@var{data-type}. The default for @var{type}, the selection type, is -@code{PRIMARY}. - -The @var{data-type} argument specifies the form of data conversion to -use, to convert the raw data obtained from another X client into Lisp -data. Meaningful values include @code{TEXT}, @code{STRING}, -@code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME}, -@code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER}, -@code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS}, -@code{NAME}, @code{ATOM}, and @code{INTEGER}. (These are symbols with -upper-case names in accord with X conventions.) The default for -@var{data-type} is @code{STRING}. -@end defun - -@cindex cut buffer -The X server also has a set of numbered @dfn{cut buffers} which can -store text or other data being moved between applications. Cut buffers -are considered obsolete, but Emacs supports them for the sake of X -clients that still use them. - -@defun x-get-cut-buffer n -This function returns the contents of cut buffer number @var{n}. -@end defun - -@defun x-set-cut-buffer string -This function stores @var{string} into the first cut buffer (cut buffer -0), moving the other values down through the series of cut buffers, much -like the way successive kills in Emacs move down the kill ring. -@end defun - -@node Color Names -@section Color Names - -@defun x-color-defined-p color &optional frame -This function reports whether a color name is meaningful. It returns -@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says -which frame's display to ask about; if @var{frame} is omitted or -@code{nil}, the selected frame is used. - -Note that this does not tell you whether the display you are using -really supports that color. You can ask for any defined color on any -kind of display, and you will get some result---that is how the X server -works. Here's an approximate way to test whether your display supports -the color @var{color}: - -@example -(defun x-color-supported-p (color &optional frame) - (and (x-color-defined-p color frame) - (or (x-display-color-p frame) - (member color '("black" "white")) - (and (> (x-display-planes frame) 1) - (equal color "gray"))))) -@end example -@end defun - -@defun x-color-values color &optional frame -This function returns a value that describes what @var{color} should -ideally look like. If @var{color} is defined, the value is a list of -three integers, which give the amount of red, the amount of green, and -the amount of blue. Each integer ranges in principle from 0 to 65535, -but in practice no value seems to be above 65280. If @var{color} is not -defined, the value is @code{nil}. - -@example -(x-color-values "black") - @result{} (0 0 0) -(x-color-values "white") - @result{} (65280 65280 65280) -(x-color-values "red") - @result{} (65280 0 0) -(x-color-values "pink") - @result{} (65280 49152 51968) -(x-color-values "hungry") - @result{} nil -@end example - -The color values are returned for @var{frame}'s display. If @var{frame} -is omitted or @code{nil}, the information is return for the selected -frame's display. -@end defun - -@node Resources -@section X Resources - -@defun x-get-resource attribute class &optional component subclass -The function @code{x-get-resource} retrieves a resource value from the X -Windows defaults database. - -Resources are indexed by a combination of a @dfn{key} and a @dfn{class}. -This function searches using a key of the form -@samp{@var{instance}.@var{attribute}} (where @var{instance} is the name -under which Emacs was invoked), and using @samp{Emacs.@var{class}} as -the class. - -The optional arguments @var{component} and @var{subclass} add to the key -and the class, respectively. You must specify both of them or neither. -If you specify them, the key is -@samp{@var{instance}.@var{component}.@var{attribute}}, and the class is -@samp{Emacs.@var{class}.@var{subclass}}. -@end defun - - @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}. - -@node Server Data -@section Data about the X Server - - This section describes functions you can use to get information about -the capabilities and origin of an X display that Emacs is using. Each -of these functions lets you specify the display you are interested in: -the @var{display} argument can be either a display name, or a frame -(meaning use the display that frame is on). If you omit the -@var{display} argument, or specify @code{nil}, that means to use the -selected frame's display. - -@defun x-display-screens &optional display -This function returns the number of screens associated with the display. -@end defun - -@defun x-server-version &optional display -This function returns the list of version numbers of the X server -running the display. -@end defun - -@defun x-server-vendor &optional display -This function returns the vendor that provided the X server software. -@end defun - -@defun x-display-pixel-height &optional display -This function returns the height of the screen in pixels. -@end defun - -@defun x-display-mm-height &optional display -This function returns the height of the screen in millimeters. -@end defun - -@defun x-display-pixel-width &optional display -This function returns the width of the screen in pixels. -@end defun - -@defun x-display-mm-width &optional display -This function returns the width of the screen in millimeters. -@end defun - -@defun x-display-backing-store &optional display -This function returns the backing store capability of the screen. -Values can be the symbols @code{always}, @code{when-mapped}, or -@code{not-useful}. -@end defun - -@defun x-display-save-under &optional display -This function returns non-@code{nil} if the display supports the -SaveUnder feature. -@end defun - -@defun x-display-planes &optional display -This function returns the number of planes the display supports. -@end defun - -@defun x-display-visual-class &optional display -This function returns the visual class for the screen. The value is one -of the symbols @code{static-gray}, @code{gray-scale}, -@code{static-color}, @code{pseudo-color}, @code{true-color}, and -@code{direct-color}. -@end defun - -@defun x-display-grayscale-p &optional display -This function returns @code{t} if the screen can display shades of gray. -@end defun - -@defun x-display-color-p &optional display -This function returns @code{t} if the screen is a color screen. -@end defun - -@defun x-display-color-cells &optional display -This function returns the number of color cells the screen supports. -@end defun - -@ignore -@defvar x-no-window-manager -This variable's value is is @code{t} if no X window manager is in use. -@end defvar -@end ignore - -@ignore -@item -The functions @code{x-pixel-width} and @code{x-pixel-height} return the -width and height of an X Window frame, measured in pixels. -@end ignore diff --git a/lispref/front-cover-1.texi b/lispref/front-cover-1.texi deleted file mode 100644 index cde9f952e9a..00000000000 --- a/lispref/front-cover-1.texi +++ /dev/null @@ -1,52 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@comment %**start of header -@setfilename front1.info -@settitle GNU Emacs Lisp Reference Manual -@smallbook -@comment %**end of header - -@titlepage -. -@sp 2 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 1} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group -@page -. -@sp 5 -@center @titlefont{The} -@sp 1 -@center @titlefont{GNU} -@sp 1 -@center @titlefont{Emacs Lisp} -@sp 1 -@center @titlefont{Reference} -@sp 1 -@center @titlefont{Manual} -@sp 2 -@center GNU Emacs Version 19 -@center for Unix Users -@center Edition 2.3, June 1994 -@sp 2 -@center @titlefont{Volume 2} -@sp 2 -@center by Bil Lewis, Dan LaLiberte, -@center and the GNU Manual Group - -@end titlepage -@bye diff --git a/lispref/functions.texi b/lispref/functions.texi deleted file mode 100644 index 035d231cf48..00000000000 --- a/lispref/functions.texi +++ /dev/null @@ -1,1138 +0,0 @@ -@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/functions -@node Functions, Macros, Variables, Top -@chapter Functions - - A Lisp program is composed mainly of Lisp functions. This chapter -explains what functions are, how they accept arguments, and how to -define them. - -@menu -* What Is a Function:: Lisp functions vs. primitives; terminology. -* Lambda Expressions:: How functions are expressed as Lisp objects. -* Function Names:: A symbol can serve as the name of a function. -* Defining Functions:: Lisp expressions for defining functions. -* Calling Functions:: How to use an existing function. -* Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda expressions are functions with no names. -* Function Cells:: Accessing or setting the function definition - of a symbol. -* Inline Functions:: Defining functions that the compiler will open code. -* Related Topics:: Cross-references to specific Lisp primitives - that have a special bearing on how functions work. -@end menu - -@node What Is a Function -@section What Is a Function? - - In a general sense, a function is a rule for carrying on a computation -given several values called @dfn{arguments}. The result of the -computation is called the value of the function. The computation can -also have side effects: lasting changes in the values of variables or -the contents of data structures. - - Here are important terms for functions in Emacs Lisp and for other -function-like objects. - -@table @dfn -@item function -@cindex function -In Emacs Lisp, a @dfn{function} is anything that can be applied to -arguments in a Lisp program. In some cases, we use it more -specifically to mean a function written in Lisp. Special forms and -macros are not functions. - -@item primitive -@cindex primitive -@cindex subr -@cindex built-in function -A @dfn{primitive} is a function callable from Lisp that is written in C, -such as @code{car} or @code{append}. These functions are also called -@dfn{built-in} functions or @dfn{subrs}. (Special forms are also -considered primitives.) - -Usually the reason that a function is a primitives is because it is -fundamental, because it provides a low-level interface to operating -system services, or because it needs to run fast. Primitives can be -modified or added only by changing the C sources and recompiling the -editor. See @ref{Writing Emacs Primitives}. - -@item lambda expression -A @dfn{lambda expression} is a function written in Lisp. -These are described in the following section. -@ifinfo -@xref{Lambda Expressions}. -@end ifinfo - -@item special form -A @dfn{special form} is a primitive that is like a function but does not -evaluate all of its arguments in the usual way. It may evaluate only -some of the arguments, or may evaluate them in an unusual order, or -several times. Many special forms are described in @ref{Control -Structures}. - -@item macro -@cindex macro -A @dfn{macro} is a construct defined in Lisp by the programmer. It -differs from a function in that it translates a Lisp expression that you -write into an equivalent expression to be evaluated instead of the -original expression. Macros enable Lisp programmers to do the sorts of -things that special forms can do. @xref{Macros}, for how to define and -use macros. - -@item command -@cindex command -A @dfn{command} is an object that @code{command-execute} can invoke; it -is a possible definition for a key sequence. Some functions are -commands; a function written in Lisp is a command if it contains an -interactive declaration (@pxref{Defining Commands}). Such a function -can be called from Lisp expressions like other functions; in this case, -the fact that the function is a command makes no difference. - -Keyboard macros (strings and vectors) are commands also, even though -they are not functions. A symbol is a command if its function -definition is a command; such symbols can be invoked with @kbd{M-x}. -The symbol is a function as well if the definition is a function. -@xref{Command Overview}. - -@item keystroke command -@cindex keystroke command -A @dfn{keystroke command} is a command that is bound to a key sequence -(typically one to three keystrokes). The distinction is made here -merely to avoid confusion with the meaning of ``command'' in non-Emacs -editors; for Lisp programs, the distinction is normally unimportant. - -@item byte-code function -A @dfn{byte-code function} is a function that has been compiled by the -byte compiler. @xref{Byte-Code Type}. -@end table - -@defun subrp object -This function returns @code{t} if @var{object} is a built-in function -(i.e., a Lisp primitive). - -@example -@group -(subrp 'message) ; @r{@code{message} is a symbol,} - @result{} nil ; @r{not a subr object.} -@end group -@group -(subrp (symbol-function 'message)) - @result{} t -@end group -@end example -@end defun - -@defun byte-code-function-p object -This function returns @code{t} if @var{object} is a byte-code -function. For example: - -@example -@group -(byte-code-function-p (symbol-function 'next-line)) - @result{} t -@end group -@end example -@end defun - -@node Lambda Expressions -@section Lambda Expressions -@cindex lambda expression - - A function written in Lisp is a list that looks like this: - -@example -(lambda (@var{arg-variables}@dots{}) - @r{[}@var{documentation-string}@r{]} - @r{[}@var{interactive-declaration}@r{]} - @var{body-forms}@dots{}) -@end example - -@noindent -Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it -actually is valid as an expression---it evaluates to itself. In some -other Lisp dialects, a lambda expression is not a valid expression at -all. In either case, its main use is not to be evaluated as an -expression, but to be called as a function. - -@menu -* Lambda Components:: The parts of a lambda expression. -* Simple Lambda:: A simple example. -* Argument List:: Details and special features of argument lists. -* Function Documentation:: How to put documentation in a function. -@end menu - -@node Lambda Components -@subsection Components of a Lambda Expression - -@ifinfo - - A function written in Lisp (a ``lambda expression'') is a list that -looks like this: - -@example -(lambda (@var{arg-variables}@dots{}) - [@var{documentation-string}] - [@var{interactive-declaration}] - @var{body-forms}@dots{}) -@end example -@end ifinfo - -@cindex lambda list - The first element of a lambda expression is always the symbol -@code{lambda}. This indicates that the list represents a function. The -reason functions are defined to start with @code{lambda} is so that -other lists, intended for other uses, will not accidentally be valid as -functions. - - The second element is a list of symbols--the argument variable names. -This is called the @dfn{lambda list}. When a Lisp function is called, -the argument values are matched up against the variables in the lambda -list, which are given local bindings with the values provided. -@xref{Local Variables}. - - The documentation string is a Lisp string object placed within the -function definition to describe the function for the Emacs help -facilities. @xref{Function Documentation}. - - The interactive declaration is a list of the form @code{(interactive -@var{code-string})}. This declares how to provide arguments if the -function is used interactively. Functions with this declaration are called -@dfn{commands}; they can be called using @kbd{M-x} or bound to a key. -Functions not intended to be called in this way should not have interactive -declarations. @xref{Defining Commands}, for how to write an interactive -declaration. - -@cindex body of function - The rest of the elements are the @dfn{body} of the function: the Lisp -code to do the work of the function (or, as a Lisp programmer would say, -``a list of Lisp forms to evaluate''). The value returned by the -function is the value returned by the last element of the body. - -@node Simple Lambda -@subsection A Simple Lambda-Expression Example - - Consider for example the following function: - -@example -(lambda (a b c) (+ a b c)) -@end example - -@noindent -We can call this function by writing it as the @sc{car} of an -expression, like this: - -@example -@group -((lambda (a b c) (+ a b c)) - 1 2 3) -@end group -@end example - -@noindent -This call evaluates the body of the lambda expression with the variable -@code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3. -Evaluation of the body adds these three numbers, producing the result 6; -therefore, this call to the function returns the value 6. - - Note that the arguments can be the results of other function calls, as in -this example: - -@example -@group -((lambda (a b c) (+ a b c)) - 1 (* 2 3) (- 5 4)) -@end group -@end example - -@noindent -This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5 -4)} from left to right. Then it applies the lambda expression to the -argument values 1, 6 and 1 to produce the value 8. - - It is not often useful to write a lambda expression as the @sc{car} of -a form in this way. You can get the same result, of making local -variables and giving them values, using the special form @code{let} -(@pxref{Local Variables}). And @code{let} is clearer and easier to use. -In practice, lambda expressions are either stored as the function -definitions of symbols, to produce named functions, or passed as -arguments to other functions (@pxref{Anonymous Functions}). - - However, calls to explicit lambda expressions were very useful in the -old days of Lisp, before the special form @code{let} was invented. At -that time, they were the only way to bind and initialize local -variables. - -@node Argument List -@subsection Advanced Features of Argument Lists -@kindex wrong-number-of-arguments -@cindex argument binding -@cindex binding arguments - - Our simple sample function, @code{(lambda (a b c) (+ a b c))}, -specifies three argument variables, so it must be called with three -arguments: if you try to call it with only two arguments or four -arguments, you get a @code{wrong-number-of-arguments} error. - - It is often convenient to write a function that allows certain -arguments to be omitted. For example, the function @code{substring} -accepts three arguments---a string, the start index and the end -index---but the third argument defaults to the @var{length} of the -string if you omit it. It is also convenient for certain functions to -accept an indefinite number of arguments, as the functions @code{list} -and @code{+} do. - -@cindex optional arguments -@cindex rest arguments -@kindex &optional -@kindex &rest - To specify optional arguments that may be omitted when a function -is called, simply include the keyword @code{&optional} before the optional -arguments. To specify a list of zero or more extra arguments, include the -keyword @code{&rest} before one final argument. - - Thus, the complete syntax for an argument list is as follows: - -@example -@group -(@var{required-vars}@dots{} - @r{[}&optional @var{optional-vars}@dots{}@r{]} - @r{[}&rest @var{rest-var}@r{]}) -@end group -@end example - -@noindent -The square brackets indicate that the @code{&optional} and @code{&rest} -clauses, and the variables that follow them, are optional. - - A call to the function requires one actual argument for each of the -@var{required-vars}. There may be actual arguments for zero or more of -the @var{optional-vars}, and there cannot be any actual arguments beyond -that unless the lambda list uses @code{&rest}. In that case, there may -be any number of extra actual arguments. - - If actual arguments for the optional and rest variables are omitted, -then they always default to @code{nil}. There is no way for the -function to distinguish between an explicit argument of @code{nil} and -an omitted argument. However, the body of the function is free to -consider @code{nil} an abbreviation for some other meaningful value. -This is what @code{substring} does; @code{nil} as the third argument to -@code{substring} means to use the length of the string supplied. - -@cindex CL note---default optional arg -@quotation -@b{Common Lisp note:} Common Lisp allows the function to specify what -default value to use when an optional argument is omitted; Emacs Lisp -always uses @code{nil}. -@end quotation - - For example, an argument list that looks like this: - -@example -(a b &optional c d &rest e) -@end example - -@noindent -binds @code{a} and @code{b} to the first two actual arguments, which are -required. If one or two more arguments are provided, @code{c} and -@code{d} are bound to them respectively; any arguments after the first -four are collected into a list and @code{e} is bound to that list. If -there are only two arguments, @code{c} is @code{nil}; if two or three -arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e} -is @code{nil}. - - There is no way to have required arguments following optional -ones---it would not make sense. To see why this must be so, suppose -that @code{c} in the example were optional and @code{d} were required. -Suppose three actual arguments are given; which variable would the third -argument be for? Similarly, it makes no sense to have any more -arguments (either required or optional) after a @code{&rest} argument. - - Here are some examples of argument lists and proper calls: - -@smallexample -((lambda (n) (1+ n)) ; @r{One required:} - 1) ; @r{requires exactly one argument.} - @result{} 2 -((lambda (n &optional n1) ; @r{One required and one optional:} - (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.} - 1 2) - @result{} 3 -((lambda (n &rest ns) ; @r{One required and one rest:} - (+ n (apply '+ ns))) ; @r{1 or more arguments.} - 1 2 3 4 5) - @result{} 15 -@end smallexample - -@node Function Documentation -@subsection Documentation Strings of Functions -@cindex documentation of function - - A lambda expression may optionally have a @dfn{documentation string} just -after the lambda list. This string does not affect execution of the -function; it is a kind of comment, but a systematized comment which -actually appears inside the Lisp world and can be used by the Emacs help -facilities. @xref{Documentation}, for how the @var{documentation-string} is -accessed. - - It is a good idea to provide documentation strings for all the -functions in your program, even those that are only called from within -your program. Documentation strings are like comments, except that they -are easier to access. - - The first line of the documentation string should stand on its own, -because @code{apropos} displays just this first line. It should consist -of one or two complete sentences that summarize the function's purpose. - - The start of the documentation string is usually indented in the source file, -but since these spaces come before the starting double-quote, they are not part of -the string. Some people make a practice of indenting any additional -lines of the string so that the text lines up in the program source. -@emph{This is a mistake.} The indentation of the following lines is -inside the string; what looks nice in the source code will look ugly -when displayed by the help commands. - - You may wonder how the documentation string could be optional, since -there are required components of the function that follow it (the body). -Since evaluation of a string returns that string, without any side effects, -it has no effect if it is not the last form in the body. Thus, in -practice, there is no confusion between the first form of the body and the -documentation string; if the only body form is a string then it serves both -as the return value and as the documentation. - -@node Function Names -@section Naming a Function -@cindex function definition -@cindex named function -@cindex function name - - In most computer languages, every function has a name; the idea of a -function without a name is nonsensical. In Lisp, a function in the -strictest sense has no name. It is simply a list whose first element is -@code{lambda}, or a primitive subr-object. - - However, a symbol can serve as the name of a function. This happens -when you put the function in the symbol's @dfn{function cell} -(@pxref{Symbol Components}). Then the symbol itself becomes a valid, -callable function, equivalent to the list or subr-object that its -function cell refers to. The contents of the function cell are also -called the symbol's @dfn{function definition}. The procedure of using a -symbol's function definition in place of the symbol is called -@dfn{symbol function indirection}; see @ref{Function Indirection}. - - In practice, nearly all functions are given names in this way and -referred to through their names. For example, the symbol @code{car} works -as a function and does what it does because the primitive subr-object -@code{#<subr car>} is stored in its function cell. - - We give functions names because it is convenient to refer to them by -their names in Lisp expressions. For primitive subr-objects such as -@code{#<subr car>}, names are the only way you can refer to them: there -is no read syntax for such objects. For functions written in Lisp, the -name is more convenient to use in a call than an explicit lambda -expression. Also, a function with a name can refer to itself---it can -be recursive. Writing the function's name in its own definition is much -more convenient than making the function definition point to itself -(something that is not impossible but that has various disadvantages in -practice). - - We often identify functions with the symbols used to name them. For -example, we often speak of ``the function @code{car}'', not -distinguishing between the symbol @code{car} and the primitive -subr-object that is its function definition. For most purposes, there -is no need to distinguish. - - Even so, keep in mind that a function need not have a unique name. While -a given function object @emph{usually} appears in the function cell of only -one symbol, this is just a matter of convenience. It is easy to store -it in several symbols using @code{fset}; then each of the symbols is -equally well a name for the same function. - - A symbol used as a function name may also be used as a variable; -these two uses of a symbol are independent and do not conflict. - -@node Defining Functions -@section Defining Functions -@cindex defining a function - - We usually give a name to a function when it is first created. This -is called @dfn{defining a function}, and it is done with the -@code{defun} special form. - -@defspec defun name argument-list body-forms -@code{defun} is the usual way to define new Lisp functions. It -defines the symbol @var{name} as a function that looks like this: - -@example -(lambda @var{argument-list} . @var{body-forms}) -@end example - -@code{defun} stores this lambda expression in the function cell of -@var{name}. It returns the value @var{name}, but usually we ignore this -value. - -As described previously (@pxref{Lambda Expressions}), -@var{argument-list} is a list of argument names and may include the -keywords @code{&optional} and @code{&rest}. Also, the first two forms -in @var{body-forms} may be a documentation string and an interactive -declaration. - -There is no conflict if the same symbol @var{name} is also used as a -variable, since the symbol's value cell is independent of the function -cell. @xref{Symbol Components}. - -Here are some examples: - -@example -@group -(defun foo () 5) - @result{} foo -@end group -@group -(foo) - @result{} 5 -@end group - -@group -(defun bar (a &optional b &rest c) - (list a b c)) - @result{} bar -@end group -@group -(bar 1 2 3 4 5) - @result{} (1 2 (3 4 5)) -@end group -@group -(bar 1) - @result{} (1 nil nil) -@end group -@group -(bar) -@error{} Wrong number of arguments. -@end group - -@group -(defun capitalize-backwards () - "Upcase the last letter of a word." - (interactive) - (backward-word 1) - (forward-word 1) - (backward-char 1) - (capitalize-word 1)) - @result{} capitalize-backwards -@end group -@end example - -Be careful not to redefine existing functions unintentionally. -@code{defun} redefines even primitive functions such as @code{car} -without any hesitation or notification. Redefining a function already -defined is often done deliberately, and there is no way to distinguish -deliberate redefinition from unintentional redefinition. -@end defspec - -@defun defalias name definition -This special form defines the symbol @var{name} as a function, with -definition @var{definition} (which can be any valid Lisp function). - -The proper place to use @code{defalias} is where a specific function -name is being defined---especially where that name appears explicitly in -the source file being loaded. This is because @code{defalias} records -which file defined the function, just like @code{defun} -(@pxref{Unloading}). - -By contrast, in programs that manipulate function definitions for other -purposes, it is better to use @code{fset}, which does not keep such -records. -@end defun - - See also @code{defsubst}, which defines a function like @code{defun} -and tells the Lisp compiler to open-code it. @xref{Inline Functions}. - -@node Calling Functions -@section Calling Functions -@cindex function invocation -@cindex calling a function - - Defining functions is only half the battle. Functions don't do -anything until you @dfn{call} them, i.e., tell them to run. Calling a -function is also known as @dfn{invocation}. - - The most common way of invoking a function is by evaluating a list. -For example, evaluating the list @code{(concat "a" "b")} calls the -function @code{concat} with arguments @code{"a"} and @code{"b"}. -@xref{Evaluation}, for a description of evaluation. - - When you write a list as an expression in your program, the function -name is part of the program. This means that you choose which function -to call, and how many arguments to give it, when you write the program. -Usually that's just what you want. Occasionally you need to decide at -run time which function to call. To do that, use the functions -@code{funcall} and @code{apply}. - -@defun funcall function &rest arguments -@code{funcall} calls @var{function} with @var{arguments}, and returns -whatever @var{function} returns. - -Since @code{funcall} is a function, all of its arguments, including -@var{function}, are evaluated before @code{funcall} is called. This -means that you can use any expression to obtain the function to be -called. It also means that @code{funcall} does not see the expressions -you write for the @var{arguments}, only their values. These values are -@emph{not} evaluated a second time in the act of calling @var{function}; -@code{funcall} enters the normal procedure for calling a function at the -place where the arguments have already been evaluated. - -The argument @var{function} must be either a Lisp function or a -primitive function. Special forms and macros are not allowed, because -they make sense only when given the ``unevaluated'' argument -expressions. @code{funcall} cannot provide these because, as we saw -above, it never knows them in the first place. - -@example -@group -(setq f 'list) - @result{} list -@end group -@group -(funcall f 'x 'y 'z) - @result{} (x y z) -@end group -@group -(funcall f 'x 'y '(z)) - @result{} (x y (z)) -@end group -@group -(funcall 'and t nil) -@error{} Invalid function: #<subr and> -@end group -@end example - -Compare these example with the examples of @code{apply}. -@end defun - -@defun apply function &rest arguments -@code{apply} calls @var{function} with @var{arguments}, just like -@code{funcall} but with one difference: the last of @var{arguments} is a -list of arguments to give to @var{function}, rather than a single -argument. We also say that @code{apply} @dfn{spreads} this list so that -each individual element becomes an argument. - -@code{apply} returns the result of calling @var{function}. As with -@code{funcall}, @var{function} must either be a Lisp function or a -primitive function; special forms and macros do not make sense in -@code{apply}. - -@example -@group -(setq f 'list) - @result{} list -@end group -@group -(apply f 'x 'y 'z) -@error{} Wrong type argument: listp, z -@end group -@group -(apply '+ 1 2 '(3 4)) - @result{} 10 -@end group -@group -(apply '+ '(1 2 3 4)) - @result{} 10 -@end group - -@group -(apply 'append '((a b c) nil (x y z) nil)) - @result{} (a b c x y z) -@end group -@end example - -For an interesting example of using @code{apply}, see the description of -@code{mapcar}, in @ref{Mapping Functions}. -@end defun - -@cindex functionals - It is common for Lisp functions to accept functions as arguments or -find them in data structures (especially in hook variables and property -lists) and call them using @code{funcall} or @code{apply}. Functions -that accept function arguments are often called @dfn{functionals}. - - Sometimes, when you call a functional, it is useful to supply a no-op -function as the argument. Here are two different kinds of no-op -function: - -@defun identity arg -This function returns @var{arg} and has no side effects. -@end defun - -@defun ignore &rest args -This function ignores any arguments and returns @code{nil}. -@end defun - -@node Mapping Functions -@section Mapping Functions -@cindex mapping functions - - A @dfn{mapping function} applies a given function to each element of a -list or other collection. Emacs Lisp has three such functions; -@code{mapcar} and @code{mapconcat}, which scan a list, are described -here. For the third mapping function, @code{mapatoms}, see -@ref{Creating Symbols}. - -@defun mapcar function sequence -@code{mapcar} applies @var{function} to each element of @var{sequence} -in turn, and returns a list of the results. - -The argument @var{sequence} may be a list, a vector, or a string. The -result is always a list. The length of the result is the same as the -length of @var{sequence}. - -@smallexample -@group -@exdent @r{For example:} - -(mapcar 'car '((a b) (c d) (e f))) - @result{} (a c e) -(mapcar '1+ [1 2 3]) - @result{} (2 3 4) -(mapcar 'char-to-string "abc") - @result{} ("a" "b" "c") -@end group - -@group -;; @r{Call each function in @code{my-hooks}.} -(mapcar 'funcall my-hooks) -@end group - -@group -(defun mapcar* (f &rest args) - "Apply FUNCTION to successive cars of all ARGS. -Return the list of results." - ;; @r{If no list is exhausted,} - (if (not (memq 'nil args)) - ;; @r{apply function to @sc{CAR}s.} - (cons (apply f (mapcar 'car args)) - (apply 'mapcar* f - ;; @r{Recurse for rest of elements.} - (mapcar 'cdr args))))) -@end group - -@group -(mapcar* 'cons '(a b c) '(1 2 3 4)) - @result{} ((a . 1) (b . 2) (c . 3)) -@end group -@end smallexample -@end defun - -@defun mapconcat function sequence separator -@code{mapconcat} applies @var{function} to each element of -@var{sequence}: the results, which must be strings, are concatenated. -Between each pair of result strings, @code{mapconcat} inserts the string -@var{separator}. Usually @var{separator} contains a space or comma or -other suitable punctuation. - -The argument @var{function} must be a function that can take one -argument and return a string. - -@smallexample -@group -(mapconcat 'symbol-name - '(The cat in the hat) - " ") - @result{} "The cat in the hat" -@end group - -@group -(mapconcat (function (lambda (x) (format "%c" (1+ x)))) - "HAL-8000" - "") - @result{} "IBM.9111" -@end group -@end smallexample -@end defun - -@node Anonymous Functions -@section Anonymous Functions -@cindex anonymous function - - In Lisp, a function is a list that starts with @code{lambda}, a -byte-code function compiled from such a list, or alternatively a -primitive subr-object; names are ``extra''. Although usually functions -are defined with @code{defun} and given names at the same time, it is -occasionally more concise to use an explicit lambda expression---an -anonymous function. Such a list is valid wherever a function name is. - - Any method of creating such a list makes a valid function. Even this: - -@smallexample -@group -(setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x)))) -@result{} (lambda (x) (+ 12 x)) -@end group -@end smallexample - -@noindent -This computes a list that looks like @code{(lambda (x) (+ 12 x))} and -makes it the value (@emph{not} the function definition!) of -@code{silly}. - - Here is how we might call this function: - -@example -@group -(funcall silly 1) -@result{} 13 -@end group -@end example - -@noindent -(It does @emph{not} work to write @code{(silly 1)}, because this function -is not the @emph{function definition} of @code{silly}. We have not given -@code{silly} any function definition, just a value as a variable.) - - Most of the time, anonymous functions are constants that appear in -your program. For example, you might want to pass one as an argument -to the function @code{mapcar}, which applies any given function to each -element of a list. Here we pass an anonymous function that multiplies -a number by two: - -@example -@group -(defun double-each (list) - (mapcar '(lambda (x) (* 2 x)) list)) -@result{} double-each -@end group -@group -(double-each '(2 11)) -@result{} (4 22) -@end group -@end example - -@noindent -In such cases, we usually use the special form @code{function} instead -of simple quotation to quote the anonymous function. - -@defspec function function-object -@cindex function quoting -This special form returns @var{function-object} without evaluating it. -In this, it is equivalent to @code{quote}. However, it serves as a -note to the Emacs Lisp compiler that @var{function-object} is intended -to be used only as a function, and therefore can safely be compiled. -Contrast this with @code{quote}, in @ref{Quoting}. -@end defspec - - Using @code{function} instead of @code{quote} makes a difference -inside a function or macro that you are going to compile. For example: - -@example -@group -(defun double-each (list) - (mapcar (function (lambda (x) (* 2 x))) list)) -@result{} double-each -@end group -@group -(double-each '(2 11)) -@result{} (4 22) -@end group -@end example - -@noindent -If this definition of @code{double-each} is compiled, the anonymous -function is compiled as well. By contrast, in the previous definition -where ordinary @code{quote} is used, the argument passed to -@code{mapcar} is the precise list shown: - -@example -(lambda (x) (* x 2)) -@end example - -@noindent -The Lisp compiler cannot assume this list is a function, even though it -looks like one, since it does not know what @code{mapcar} does with the -list. Perhaps @code{mapcar} will check that the @sc{car} of the third -element is the symbol @code{*}! The advantage of @code{function} is -that it tells the compiler to go ahead and compile the constant -function. - - We sometimes write @code{function} instead of @code{quote} when -quoting the name of a function, but this usage is just a sort of -comment. - -@example -(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol} -@end example - - See @code{documentation} in @ref{Accessing Documentation}, for a -realistic example using @code{function} and an anonymous function. - -@node Function Cells -@section Accessing Function Cell Contents - - The @dfn{function definition} of a symbol is the object stored in the -function cell of the symbol. The functions described here access, test, -and set the function cell of symbols. - - See also the function @code{indirect-function} in @ref{Function -Indirection}. - -@defun symbol-function symbol -@kindex void-function -This returns the object in the function cell of @var{symbol}. If the -symbol's function cell is void, a @code{void-function} error is -signaled. - -This function does not check that the returned object is a legitimate -function. - -@example -@group -(defun bar (n) (+ n 2)) - @result{} bar -@end group -@group -(symbol-function 'bar) - @result{} (lambda (n) (+ n 2)) -@end group -@group -(fset 'baz 'bar) - @result{} bar -@end group -@group -(symbol-function 'baz) - @result{} bar -@end group -@end example -@end defun - -@cindex void function cell - If you have never given a symbol any function definition, we say that -that symbol's function cell is @dfn{void}. In other words, the function -cell does not have any Lisp object in it. If you try to call such a symbol -as a function, it signals a @code{void-function} error. - - Note that void is not the same as @code{nil} or the symbol -@code{void}. The symbols @code{nil} and @code{void} are Lisp objects, -and can be stored into a function cell just as any other object can be -(and they can be valid functions if you define them in turn with -@code{defun}). A void function cell contains no object whatsoever. - - You can test the voidness of a symbol's function definition with -@code{fboundp}. After you have given a symbol a function definition, you -can make it void once more using @code{fmakunbound}. - -@defun fboundp symbol -This function returns @code{t} if the symbol has an object in its -function cell, @code{nil} otherwise. It does not check that the object -is a legitimate function. -@end defun - -@defun fmakunbound symbol -This function makes @var{symbol}'s function cell void, so that a -subsequent attempt to access this cell will cause a @code{void-function} -error. (See also @code{makunbound}, in @ref{Local Variables}.) - -@example -@group -(defun foo (x) x) - @result{} x -@end group -@group -(foo 1) - @result{}1 -@end group -@group -(fmakunbound 'foo) - @result{} x -@end group -@group -(foo 1) -@error{} Symbol's function definition is void: foo -@end group -@end example -@end defun - -@defun fset symbol definition -This function stores @var{definition} in the function cell of @var{symbol}. -The result is @var{definition}. Normally @var{definition} should be a function -or the name of a function, but this is not checked. - -There are three normal uses of this function: - -@itemize @bullet -@item -Copying one symbol's function definition to another. (In other words, -making an alternate name for a function.) - -@item -Giving a symbol a function definition that is not a list and therefore -cannot be made with @code{defun}. For example, you can use @code{fset} -to give a symbol @code{s1} a function definition which is another symbol -@code{s2}; then @code{s1} serves as an alias for whatever definition -@code{s2} presently has. - -@item -In constructs for defining or altering functions. If @code{defun} -were not a primitive, it could be written in Lisp (as a macro) using -@code{fset}. -@end itemize - -Here are examples of the first two uses: - -@example -@group -;; @r{Give @code{first} the same definition @code{car} has.} -(fset 'first (symbol-function 'car)) - @result{} #<subr car> -@end group -@group -(first '(1 2 3)) - @result{} 1 -@end group - -@group -;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.} -(fset 'xfirst 'car) - @result{} car -@end group -@group -(xfirst '(1 2 3)) - @result{} 1 -@end group -@group -(symbol-function 'xfirst) - @result{} car -@end group -@group -(symbol-function (symbol-function 'xfirst)) - @result{} #<subr car> -@end group - -@group -;; @r{Define a named keyboard macro.} -(fset 'kill-two-lines "\^u2\^k") - @result{} "\^u2\^k" -@end group -@end example - -See also the related function @code{defalias}, in @ref{Defining -Functions}. -@end defun - - When writing a function that extends a previously defined function, -the following idiom is sometimes used: - -@example -(fset 'old-foo (symbol-function 'foo)) -(defun foo () - "Just like old-foo, except more so." -@group - (old-foo) - (more-so)) -@end group -@end example - -@noindent -This does not work properly if @code{foo} has been defined to autoload. -In such a case, when @code{foo} calls @code{old-foo}, Lisp attempts -to define @code{old-foo} by loading a file. Since this presumably -defines @code{foo} rather than @code{old-foo}, it does not produce the -proper results. The only way to avoid this problem is to make sure the -file is loaded before moving aside the old definition of @code{foo}. - - But it is unmodular and unclean, in any case, for a Lisp file to -redefine a function defined elsewhere. - -@node Inline Functions -@section Inline Functions -@cindex inline functions - -@findex defsubst -You can define an @dfn{inline function} by using @code{defsubst} instead -of @code{defun}. An inline function works just like an ordinary -function except for one thing: when you compile a call to the function, -the function's definition is open-coded into the caller. - -Making a function inline makes explicit calls run faster. But it also -has disadvantages. For one thing, it reduces flexibility; if you change -the definition of the function, calls already inlined still use the old -definition until you recompile them. Since the flexibility of -redefining functions is an important feature of Emacs, you should not -make a function inline unless its speed is really crucial. - -Another disadvantage is that making a large function inline can increase -the size of compiled code both in files and in memory. Since the speed -advantage of inline functions is greatest for small functions, you -generally should not make large functions inline. - -It's possible to define a macro to expand into the same code that an -inline function would execute. But the macro would have a limitation: -you can use it only explicitly---a macro cannot be called with -@code{apply}, @code{mapcar} and so on. Also, it takes some work to -convert an ordinary function into a macro. (@xref{Macros}.) To convert -it into an inline function is very easy; simply replace @code{defun} -with @code{defsubst}. Since each argument of an inline function is -evaluated exactly once, you needn't worry about how many times the -body uses the arguments, as you do for macros. (@xref{Argument -Evaluation}.) - -Inline functions can be used and open-coded later on in the same file, -following the definition, just like macros. - -@c Emacs versions prior to 19 did not have inline functions. - -@node Related Topics -@section Other Topics Related to Functions - - Here is a table of several functions that do things related to -function calling and function definitions. They are documented -elsewhere, but we provide cross references here. - -@table @code -@item apply -See @ref{Calling Functions}. - -@item autoload -See @ref{Autoload}. - -@item call-interactively -See @ref{Interactive Call}. - -@item commandp -See @ref{Interactive Call}. - -@item documentation -See @ref{Accessing Documentation}. - -@item eval -See @ref{Eval}. - -@item funcall -See @ref{Calling Functions}. - -@item ignore -See @ref{Calling Functions}. - -@item indirect-function -See @ref{Function Indirection}. - -@item interactive -See @ref{Using Interactive}. - -@item interactive-p -See @ref{Interactive Call}. - -@item mapatoms -See @ref{Creating Symbols}. - -@item mapcar -See @ref{Mapping Functions}. - -@item mapconcat -See @ref{Mapping Functions}. - -@item undefined -See @ref{Key Lookup}. -@end table - diff --git a/lispref/help.texi b/lispref/help.texi deleted file mode 100644 index 5b0b2f993ba..00000000000 --- a/lispref/help.texi +++ /dev/null @@ -1,627 +0,0 @@ -@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/help -@node Documentation, Files, Modes, Top -@chapter Documentation -@cindex documentation strings - - GNU Emacs Lisp has convenient on-line help facilities, most of which -derive their information from the documentation strings associated with -functions and variables. This chapter describes how to write good -documentation strings for your Lisp programs, as well as how to write -programs to access documentation. - - Note that the documentation strings for Emacs are not the same thing -as the Emacs manual. Manuals have their own source files, written in -the Texinfo language; documentation strings are specified in the -definitions of the functions and variables they apply to. A collection -of documentation strings is not sufficient as a manual because a good -manual is not organized in that fashion; it is organized in terms of -topics of discussion. - -@menu -* Documentation Basics:: Good style for doc strings. - Where to put them. How Emacs stores them. -* Accessing Documentation:: How Lisp programs can access doc strings. -* Keys in Documentation:: Substituting current key bindings. -* Describing Characters:: Making printable descriptions of - non-printing characters and key sequences. -* Help Functions:: Subroutines used by Emacs help facilities. -@end menu - -@node Documentation Basics -@comment node-name, next, previous, up -@section Documentation Basics -@cindex documentation conventions -@cindex writing a documentation string -@cindex string, writing a doc string - - A documentation string is written using the Lisp syntax for strings, -with double-quote characters surrounding the text of the string. This -is because it really is a Lisp string object. The string serves as -documentation when it is written in the proper place in the definition -of a function or variable. In a function definition, the documentation -string follows the argument list. In a variable definition, the -documentation string follows the initial value of the variable. - - When you write a documentation string, make the first line a complete -sentence (or two complete sentences) since some commands, such as -@code{apropos}, show only the first line of a multi-line documentation -string. Also, you should not indent the second line of a documentation -string, if you have one, because that looks odd when you use @kbd{C-h f} -(@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}). -@xref{Documentation Tips}. - - Documentation strings may contain several special substrings, which -stand for key bindings to be looked up in the current keymaps when the -documentation is displayed. This allows documentation strings to refer -to the keys for related commands and be accurate even when a user -rearranges the key bindings. (@xref{Accessing Documentation}.) - - Within the Lisp world, a documentation string accessible through the -function or variable that it describes: - -@itemize @bullet -@item -The documentation for a function is stored in the function definition -itself (@pxref{Lambda Expressions}). The function -@code{documentation} knows how to extract it. - -@item -@kindex variable-documentation -The documentation for a variable is stored in the variable's property -list under the property name @code{variable-documentation}. The -function @code{documentation-property} knows how to extract it. -@end itemize - -@cindex @file{DOC} (documentation) file -@cindex @file{emacs/etc/DOC-@var{version}} -@cindex @file{etc/DOC-@var{version}} -To save space, the documentation for preloaded functions and variables -(including primitive functions and autoloaded functions) is stored in -the file @file{emacs/etc/DOC-@var{version}}. The documentation for -functions and variables loaded during the Emacs session from -byte-compiled files is stored in those files (@pxref{Docs and -Compilation}). - -The data structure inside Emacs has an integer offset into the file, or -a list containing a string and an integer, in place of the documentation -string. The functions @code{documentation} and -@code{documentation-property} use that information to read the -documentation from the appropriate file; this is transparent to the -user. - - For information on the uses of documentation strings, see @ref{Help, , -Help, emacs, The GNU Emacs Manual}. - -@c Wordy to prevent overfull hbox. --rjc 15mar92 - The @file{emacs/lib-src} directory contains two utilities that you can -use to print nice-looking hardcopy for the file -@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc.c} and -@file{digest-doc.c}. - -@node Accessing Documentation -@section Access to Documentation Strings - -@defun documentation-property symbol property &optional verbatim -This function returns the documentation string that is recorded -@var{symbol}'s property list under property @var{property}. It -retrieves the text from a file if necessary, and runs -@code{substitute-command-keys} to substitute actual key bindings. (This -substitution is not done if @var{verbatim} is non-@code{nil}; the -@var{verbatim} argument exists only as of Emacs 19.) - -@smallexample -@group -(documentation-property 'command-line-processed - 'variable-documentation) - @result{} "t once command line has been processed" -@end group -@group -(symbol-plist 'command-line-processed) - @result{} (variable-documentation 188902) -@end group -@end smallexample -@end defun - -@defun documentation function &optional verbatim -This function returns the documentation string of @var{function}. It -reads the text from a file if necessary. Then (unless @var{verbatim} is -non-@code{nil}) it calls @code{substitute-command-keys}, to return a -value containing the actual (current) key bindings. - -The function @code{documentation} signals a @code{void-function} error -if @var{function} has no function definition. However, it is ok if -the function definition has no documentation string. In that case, -@code{documentation} returns @code{nil}. -@end defun - -@c Wordy to prevent overfull hboxes. --rjc 15mar92 -Here is an example of using the two functions, @code{documentation} and -@code{documentation-property}, to display the documentation strings for -several symbols in a @samp{*Help*} buffer. - -@smallexample -@group -(defun describe-symbols (pattern) - "Describe the Emacs Lisp symbols matching PATTERN. -All symbols that have PATTERN in their name are described -in the `*Help*' buffer." - (interactive "sDescribe symbols matching: ") - (let ((describe-func - (function - (lambda (s) -@end group -@group - ;; @r{Print description of symbol.} - (if (fboundp s) ; @r{It is a function.} - (princ - (format "%s\t%s\n%s\n\n" s - (if (commandp s) - (let ((keys (where-is-internal s))) - (if keys - (concat - "Keys: " - (mapconcat 'key-description - keys " ")) - "Keys: none")) - "Function") -@end group -@group - (or (documentation s) - "not documented")))) - - (if (boundp s) ; @r{It is a variable.} -@end group -@group - (princ - (format "%s\t%s\n%s\n\n" s - (if (user-variable-p s) - "Option " "Variable") -@end group -@group - (or (documentation-property - s 'variable-documentation) - "not documented"))))))) - sym-list) -@end group - -@group - ;; @r{Build a list of symbols that match pattern.} - (mapatoms (function - (lambda (sym) - (if (string-match pattern (symbol-name sym)) - (setq sym-list (cons sym sym-list)))))) -@end group - -@group - ;; @r{Display the data.} - (with-output-to-temp-buffer "*Help*" - (mapcar describe-func (sort sym-list 'string<)) - (print-help-return-message)))) -@end group -@end smallexample - - The @code{describe-symbols} function works like @code{apropos}, -but provides more information. - -@smallexample -@group -(describe-symbols "goal") - ----------- Buffer: *Help* ---------- -goal-column Option -*Semipermanent goal column for vertical motion, as set by @dots{} -@end group -@c Do not blithely break or fill these lines. -@c That makes them incorrect. - -@group -set-goal-column Command: C-x C-n -Set the current horizontal position as a goal for C-n and C-p. -@end group -@c DO NOT put a blank line here! That is factually inaccurate! -@group -Those commands will move to this position in the line moved to -rather than trying to keep the same horizontal position. -With a non-nil argument, clears out the goal column -so that C-n and C-p resume vertical motion. -The goal column is stored in the variable `goal-column'. -@end group - -@group -temporary-goal-column Variable -Current goal column for vertical motion. -It is the column where point was -at the start of current run of vertical motion commands. -When the `track-eol' feature is doing its job, the value is 9999. ----------- Buffer: *Help* ---------- -@end group -@end smallexample - -@defun Snarf-documentation filename - This function is used only during Emacs initialization, just before -the runnable Emacs is dumped. It finds the file offsets of the -documentation strings stored in the file @var{filename}, and records -them in the in-core function definitions and variable property lists in -place of the actual strings. @xref{Building Emacs}. - - Emacs finds the file @var{filename} in the @file{emacs/etc} directory. -When the dumped Emacs is later executed, the same file is found in the -directory @code{doc-directory}. Usually @var{filename} is -@code{"DOC-@var{version}"}. -@end defun - -@c Emacs 19 feature -@defvar doc-directory -This variable holds the name of the directory which should contion the -file @code{"DOC-@var{version}"} that contains documentation strings for -built-in and preloaded functions and variables. - -In most cases, this is the same as @code{data-directory}. They may be -different when you run Emacs from the directory where you built it, -without actually installing it. See @code{data-directory} in @ref{Help -Functions}. - -In older Emacs versions, @code{exec-directory} was used for this. -@end defvar - -@node Keys in Documentation -@section Substituting Key Bindings in Documentation -@cindex documentation, keys in -@cindex keys in documentation strings -@cindex substituting keys in documentation - - When documentation strings refer to key sequences, they should use the -current, actual key bindings. They can do so using certain special text -sequences described below. Accessing documentation strings in the usual -way substitutes current key binding information for these special -sequences. This works by calling @code{substitute-command-keys}. You -can also call that function yourself. - - Here is a list of the special sequences and what they mean: - -@table @code -@item \[@var{command}] -stands for a key sequence that will invoke @var{command}, or @samp{M-x -@var{command}} if @var{command} has no key bindings. - -@item \@{@var{mapvar}@} -stands for a summary of the value of @var{mapvar}, which should be a -keymap. The summary is made by @code{describe-bindings}. - -@item \<@var{mapvar}> -stands for no text itself. It is used for a side effect: it specifies -@var{mapvar} as the keymap for any following @samp{\[@var{command}]} -sequences in this documentation string. - -@item \= -quotes the following character and is discarded; thus, @samp{\=\[} puts -@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the -output. -@end table - -@strong{Please note:} Each @samp{\} must be doubled when written in a -string in Emacs Lisp. - -@defun substitute-command-keys string -This function scans @var{string} for the above special sequences and -replaces them by what they stand for, returning the result as a string. -This permits display of documentation that refers accurately to the -user's own customized key bindings. -@end defun - - Here are examples of the special sequences: - -@smallexample -@group -(substitute-command-keys - "To abort recursive edit, type: \\[abort-recursive-edit]") -@result{} "To abort recursive edit, type: C-]" -@end group - -@group -(substitute-command-keys - "The keys that are defined for the minibuffer here are: - \\@{minibuffer-local-must-match-map@}") -@result{} "The keys that are defined for the minibuffer here are: -@end group - -? minibuffer-completion-help -SPC minibuffer-complete-word -TAB minibuffer-complete -LFD minibuffer-complete-and-exit -RET minibuffer-complete-and-exit -C-g abort-recursive-edit -" - -@group -(substitute-command-keys - "To abort a recursive edit from the minibuffer, type\ -\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].") -@result{} "To abort a recursive edit from the minibuffer, type C-g." -@end group -@end smallexample - -@node Describing Characters -@section Describing Characters for Help Messages - - These functions convert events, key sequences or characters to textual -descriptions. These descriptions are useful for including arbitrary -text characters or key sequences in messages, because they convert -non-printing and whitespace characters to sequences of printing -characters. The description of a non-whitespace printing character is -the character itself. - -@defun key-description sequence -@cindex Emacs event standard notation -This function returns a string containing the Emacs standard notation -for the input events in @var{sequence}. The argument @var{sequence} may -be a string, vector or list. @xref{Input Events}, for more information -about valid events. See also the examples for -@code{single-key-description}, below. -@end defun - -@defun single-key-description event -@cindex event printing -@cindex character printing -@cindex control character printing -@cindex meta character printing -This function returns a string describing @var{event} in the standard -Emacs notation for keyboard input. A normal printing character appears -as itself, but a control character turns into a string starting with -@samp{C-}, a meta character turns into a string starting with @samp{M-}, -and space, linefeed, etc.@: appear as @samp{SPC}, @samp{LFD}, etc. A -function key symbol appears as itself. An event that is a list appears -as the name of the symbol in the @sc{car} of the list. - -@smallexample -@group -(single-key-description ?\C-x) - @result{} "C-x" -@end group -@group -(key-description "\C-x \M-y \n \t \r \f123") - @result{} "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3" -@end group -@group -(single-key-description 'C-mouse-1) - @result{} "C-mouse-1" -@end group -@end smallexample -@end defun - -@defun text-char-description character -This function returns a string describing @var{character} in the -standard Emacs notation for characters that appear in text---like -@code{single-key-description}, except that control characters are -represented with a leading caret (which is how control characters in -Emacs buffers are usually displayed). - -@smallexample -@group -(text-char-description ?\C-c) - @result{} "^C" -@end group -@group -(text-char-description ?\M-m) - @result{} "M-m" -@end group -@group -(text-char-description ?\C-\M-m) - @result{} "M-^M" -@end group -@end smallexample -@end defun - -@node Help Functions -@section Help Functions - - Emacs provides a variety of on-line help functions, all accessible to -the user as subcommands of the prefix @kbd{C-h}. For more information -about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here -we describe some program-level interfaces to the same information. - -@deffn Command apropos regexp &optional do-all predicate -This function finds all symbols whose names contain a match for the -regular expression @var{regexp}, and returns a list of them -(@pxref{Regular Expressions}). It also displays the symbols in a buffer -named @samp{*Help*}, each with a one-line description. - -@c Emacs 19 feature -If @var{do-all} is non-@code{nil}, then @code{apropos} also shows -key bindings for the functions that are found. - -If @var{predicate} is non-@code{nil}, it should be a function to be -called on each symbol that has matched @var{regexp}. Only symbols for -which @var{predicate} returns a non-@code{nil} value are listed or -displayed. - -In the first of the following examples, @code{apropos} finds all the -symbols with names containing @samp{exec}. In the second example, it -finds and returns only those symbols that are also commands. -(We don't show the output that results in the @samp{*Help*} buffer.) - -@smallexample -@group -(apropos "exec") - @result{} (Buffer-menu-execute command-execute exec-directory - exec-path execute-extended-command execute-kbd-macro - executing-kbd-macro executing-macro) -@end group - -@group -(apropos "exec" nil 'commandp) - @result{} (Buffer-menu-execute execute-extended-command) -@end group -@ignore -@group ----------- Buffer: *Help* ---------- -Buffer-menu-execute - Function: Save and/or delete buffers marked with - M-x Buffer-menu-save or M-x Buffer-menu-delete commands. -execute-extended-command ESC x - Function: Read function name, then read its - arguments and call it. ----------- Buffer: *Help* ---------- -@end group -@end ignore -@end smallexample - -The command @kbd{C-h a} (@code{command-apropos}) calls @code{apropos}, -but specifies a @var{predicate} to restrict the output to symbols that -are commands. The call to @code{apropos} looks like this: - -@smallexample -(apropos string t 'commandp) -@end smallexample -@end deffn - -@c Emacs 19 feature -@deffn Command super-apropos regexp &optional do-all -This function differs from @code{apropos} in that it searches -documentation strings as well as symbol names for matches for -@var{regexp}. By default, it searches the documentation strings only -for preloaded functions and variables. If @var{do-all} is -non-@code{nil}, it scans the names and documentation strings of all -functions and variables. -@end deffn - -@defvar help-map -The value of this variable is a local keymap for characters following the -Help key, @kbd{C-h}. -@end defvar - -@deffn {Prefix Command} help-command -This symbol is not a function; its function definition is actually the -keymap known as @code{help-map}. It is defined in @file{help.el} as -follows: - -@smallexample -@group -(define-key global-map "\C-h" 'help-command) -(fset 'help-command help-map) -@end group -@end smallexample -@end deffn - -@defun print-help-return-message &optional function -This function builds a string that explains how to restore the previous -state of the windows after a help command. After building the message, -it applies @var{function} to it if @var{function} is non-@code{nil}. -Otherwise it calls @code{message} to display it in the echo area. - -This function expects to be called inside a -@code{with-output-to-temp-buffer} special form, and expects -@code{standard-output} to have the value bound by that special form. -For an example of its use, see the long example in @ref{Accessing -Documentation}. -@end defun - -@defvar help-char -The value of this variable is the help character---the character that -Emacs recognizes as meaning Help. By default, it is 8, which is -@kbd{C-h}. When Emacs reads this character, if @code{help-form} is -non-@code{nil} Lisp expression, it evaluates that expression, and -displays the result in a window if it is a string. - -Usually the value of @code{help-form}'s value is @code{nil}. Then the -help character has no special meaning at the level of command input, and -it becomes part of a key sequence in the normal way. The standard key -binding of @kbd{C-h} is a prefix key for several general-purpose help -features. - -The help character is special after prefix keys, too. If it has no -binding as a subcommand of the prefix key, it runs -@code{describe-prefix-bindings}, which displays a list of all the -subcommands of the prefix key. -@end defvar - -@defvar help-form -If this variable is non-@code{nil}, its value is a form to evaluate -whenever the character @code{help-char} is read. If evaluating the form -produces a string, that string is displayed. - -A command that calls @code{read-event} or @code{read-char} probably -should bind @code{help-form} to a non-@code{nil} expression while it -does input. (The exception is when @kbd{C-h} is meaningful input.) -Evaluating this expression should result in a string that explains what -the input is for and how to enter it properly. - -Entry to the minibuffer binds this variable to the value of -@code{minibuffer-help-form} (@pxref{Minibuffer Misc}). -@end defvar - -@defvar prefix-help-command -This variable holds a function to print help for a prefix character. -The function is called when the user types a prefix key followed by the -help character, and the help character has no binding after that prefix. -The variable's default value is @code{describe-prefix-bindings}. -@end defvar - -@defun describe-prefix-bindings -This function calls @code{describe-bindings} to display a list of all -the subcommands of the prefix key of the most recent key sequence. The -prefix described consists of all but the last event of that key -sequence. (The last event is, presumably, the help character.) -@end defun - - The following two functions are found in the library @file{helper}. -They are for modes that want to provide help without relinquishing -control, such as the ``electric'' modes. You must load that library -with @code{(require 'helper)} in order to use them. Their names begin -with @samp{Helper} to distinguish them from the ordinary help functions. - -@deffn Command Helper-describe-bindings -This command pops up a window displaying a help buffer containing a -listing of all of the key bindings from both the local and global keymaps. -It works by calling @code{describe-bindings}. -@end deffn - -@deffn Command Helper-help -This command provides help for the current mode. It prompts the user -in the minibuffer with the message @samp{Help (Type ? for further -options)}, and then provides assistance in finding out what the key -bindings are, and what the mode is intended for. It returns @code{nil}. - -This can be customized by changing the map @code{Helper-help-map}. -@end deffn - -@c Emacs 19 feature -@defvar data-directory -This variable holds the name of the directory in which Emacs finds -certain documentation and text files that come with Emacs. In older -Emacs versions, @code{exec-directory} was used for this. -@end defvar - -@c Emacs 19 feature -@defmac make-help-screen fname help-line help-text help-map -This macro defines a help command named @var{fname} that acts like a -prefix key that shows a list of the subcommands it offers. - -When invoked, @var{fname} displays @var{help-text} in a window, then -reads and executes a key sequence according to @var{help-map}. The -string @var{help-text} should describe the bindings available in -@var{help-map}. - -The command @var{fname} is defined to handle a few events itself, by -scrolling the display of @var{help-text}. When @var{fname} reads one of -those special events, it does the scrolling and then reads another -event. When it reads an event that is not one of those few, and which -has a binding in @var{help-map}, it executes that key's binding and -then returns. - -The argument @var{help-line} should be a single-line summary of the -alternatives in @var{help-map}. In the current version of Emacs, this -argument is used only if you set the option @code{three-step-help} to -@code{t}. -@end defmac - -@defopt three-step-help -If this variable is non-@code{nil}, commands defined with -@code{make-help-screen} display their @var{help-line} strings in the -echo area at first, and display the longer @var{help-text} strings only -if the user types the help character again. -@end defopt diff --git a/lispref/hooks.texi b/lispref/hooks.texi deleted file mode 100644 index 046ac7cc5d5..00000000000 --- a/lispref/hooks.texi +++ /dev/null @@ -1,129 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/hooks -@node Standard Hooks, Index, Standard Keymaps, Top -@appendix Standard Hooks - -The following is a list of hook variables that let you provide -functions to be called from within Emacs on suitable occasions. - -Most of these variables have names ending with @samp{-hook}. They are -@dfn{normal hooks}, run by means of @code{run-hooks}. The value of such -a hook is a list of functions; the functions are called with no -arguments and their values are completely ignored. The recommended way -to put a new function on such a hook is to call @code{add-hook}. -@xref{Hooks}, for more information about using hooks. - -The variables whose names end in @samp{-hooks} or @samp{-functions} are -usually @dfn{abnormal hooks}; their values are lists of functions, but -these functions are called in a special way (they are passed arguments, -or their values are used). A few of these variables are actually normal -hooks which were named before we established the convention that normal -hooks' names should end in @samp{-hook}. - -The variables whose names end in @samp{-function} have single functions -as their values. (In older Emacs versions, some of these variables had -names ending in @samp{-hook} even though they were not normal hooks; -however, we have renamed all of those.) - -@c !!! need xref to where each hook is documented or else document it -@c by specifying what is expected, and when it is called relative to -@c mode initialization.) - -@table @code -@item activate-mark-hook -@item after-change-function -@item after-change-functions -@item after-init-hook -@item after-insert-file-functions -@item after-make-frame-hook -@item auto-fill-function -@item auto-save-hook -@item before-change-function -@item before-change-functions -@item before-init-hook -@item before-make-frame-hook -@item blink-paren-function -@item c-mode-hook -@item calendar-load-hook -@item command-history-hook -@item comment-indent-function -@item deactivate-mark-hook -@item diary-display-hook -@item diary-hook -@item dired-mode-hook -@item disabled-command-hook -@item edit-picture-hook -@item electric-buffer-menu-mode-hook -@item electric-command-history-hook -@item electric-help-mode-hook -@item emacs-lisp-mode-hook -@item find-file-hooks -@item find-file-not-found-hooks -@item first-change-hook -@item fortran-comment-hook -@item fortran-mode-hook -@item ftp-setup-write-file-hooks -@item ftp-write-file-hook -@item indent-mim-hook -@item initial-calendar-window-hook -@item kill-buffer-query-functions -@item kill-emacs-query-functions -@item LaTeX-mode-hook -@item ledit-mode-hook -@item lisp-indent-function -@item lisp-interaction-mode-hook -@item lisp-mode-hook -@item list-diary-entries-hook -@item m2-mode-hook -@item mail-mode-hook -@item mail-setup-hook -@item mark-diary-entries-hook -@item medit-mode-hook -@item mh-compose-letter-hook -@item mh-folder-mode-hook -@item mh-letter-mode-hook -@item mim-mode-hook -@item minibuffer-setup-hook -@item minibuffer-exit-hook -@item news-mode-hook -@item news-reply-mode-hook -@item news-setup-hook -@item nongregorian-diary-listing-hook -@item nongregorian-diary-marking-hook -@item nroff-mode-hook -@item outline-mode-hook -@item plain-TeX-mode-hook -@item post-command-hook -@item pre-abbrev-expand-hook -@item pre-command-hook -@item print-diary-entries-hook -@item prolog-mode-hook -@item protect-innocence-hook -@item rmail-edit-mode-hook -@item rmail-mode-hook -@item rmail-summary-mode-hook -@item scheme-indent-hook -@item scheme-mode-hook -@item scribe-mode-hook -@item shell-mode-hook -@item shell-set-directory-error-hook -@item suspend-hook -@item suspend-resume-hook -@item temp-buffer-show-function -@item term-setup-hook -@item terminal-mode-hook -@item terminal-mode-break-hook -@item TeX-mode-hook -@item text-mode-hook -@item today-visible-calendar-hook -@item today-invisible-calendar-hook -@item vi-mode-hook -@item view-hook -@item window-setup-hook -@item write-contents-hooks -@item write-file-hooks -@item write-region-annotate-functions -@end table diff --git a/lispref/internals.texi b/lispref/internals.texi deleted file mode 100644 index 48323f79d33..00000000000 --- a/lispref/internals.texi +++ /dev/null @@ -1,960 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/internals -@node GNU Emacs Internals, Standard Errors, Tips, Top -@comment node-name, next, previous, up -@appendix GNU Emacs Internals - -This chapter describes how the runnable Emacs executable is dumped with -the preloaded Lisp libraries in it, how storage is allocated, and some -internal aspects of GNU Emacs that may be of interest to C programmers. - -@menu -* Building Emacs:: How to preload Lisp libraries into Emacs. -* Pure Storage:: A kludge to make preloaded Lisp functions sharable. -* Garbage Collection:: Reclaiming space for Lisp objects no longer used. -* Writing Emacs Primitives:: Writing C code for Emacs. -* Object Internals:: Data formats of buffers, windows, processes. -@end menu - -@node Building Emacs, Pure Storage, GNU Emacs Internals, GNU Emacs Internals -@appendixsec Building Emacs -@cindex building Emacs -@pindex temacs - - This section explains the steps involved in building the Emacs -executable. You don't have to know this material to build and install -Emacs, since the makefiles do all these things automatically. This -information is pertinent to Emacs maintenance. - - Compilation of the C source files in the @file{src} directory -produces an executable file called @file{temacs}, also called a -@dfn{bare impure Emacs}. It contains the Emacs Lisp interpreter and I/O -routines, but not the editing commands. - -@cindex @file{loadup.el} - The command @w{@samp{temacs -l loadup}} uses @file{temacs} to create -the real runnable Emacs executable. These arguments direct -@file{temacs} to evaluate the Lisp files specified in the file -@file{loadup.el}. These files set up the normal Emacs editing -environment, resulting in an Emacs that is still impure but no longer -bare. - - It takes a substantial time to load the standard Lisp files. Luckily, -you don't have to do this each time you run Emacs; @file{temacs} can -dump out an executable program called @file{emacs} that has these files -preloaded. @file{emacs} starts more quickly because it does not need to -load the files. This is the Emacs executable that is normally -installed. - - To create @file{emacs}, use the command @samp{temacs -batch -l loadup -dump}. The purpose of @samp{-batch} here is to prevent @file{temacs} -from trying to initialize any of its data on the terminal; this ensures -that the tables of terminal information are empty in the dumped Emacs. -The argument @samp{dump} tells @file{loadup.el} to dump a new executable -named @file{emacs}. - - Some operating systems don't support dumping. On those systems, you -must start Emacs with the @samp{temacs -l loadup} command each time you -use it. This takes a substantial time, but since you need to start -Emacs once a day at most---or once a week if you never log out---the -extra time is not too severe a problem. - -@cindex @file{site-load.el} - You can specify additional files to preload by writing a library named -@file{site-load.el} that loads them. You may need to increase the value -of @code{PURESIZE}, in @file{src/puresize.h}, to make room for the -additional data. (Try adding increments of 20000 until it is big -enough.) However, the advantage of preloading additional files -decreases as machines get faster. On modern machines, it is usually not -advisable. - - After @file{loadup.el} reads @file{site-load.el}, it finds the -documentation strings for primitive and preloaded functions (and -variables) in the file @file{etc/DOC} where they are stored, by calling -@code{Snarf-documentation} (@pxref{Accessing Documentation}). - -@cindex @file{site-init.el} - You can specify other Lisp expressions to execute just before dumping -by putting them in a library named @file{site-init.el}. This file is -executed after the documentation strings are found. - - If you want to preload function or variable definitions, there are -three ways you can do this and make their documentation strings -accessible when you subsequently run Emacs: - -@itemize @bullet -@item -Arrange to scan these files when producing the @file{etc/DOC} file, -and load them with @file{site-load.el}. - -@item -Load the files with @file{site-init.el}, then copy the files into the -installation directory for Lisp files when you install Emacs. - -@item -Specify a non-@code{nil} value for -@code{byte-compile-dynamic-docstrings} as a local variable in each these -files, and load them with either @file{site-load.el} or -@file{site-init.el}. (This method has the drawback that the -documentation strings take up space in Emacs all the time.) -@end itemize - - It is not advisable to put anything in @file{site-load.el} or -@file{site-init.el} that would alter any of the features that users -expect in an ordinary unmodified Emacs. If you feel you must override -normal features for your site, do it with @file{default.el}, so that -users can override your changes if they wish. @xref{Start-up Summary}. - -@defun dump-emacs to-file from-file -@cindex unexec - This function dumps the current state of Emacs into an executable file -@var{to-file}. It takes symbols from @var{from-file} (this is normally -the executable file @file{temacs}). - -If you use this function in an Emacs that was already dumped, you must -set @code{command-line-processed} to @code{nil} first for good results. -@xref{Command Line Arguments}. -@end defun - -@deffn Command emacs-version - This function returns a string describing the version of Emacs that is -running. It is useful to include this string in bug reports. - -@example -@group -(emacs-version) - @result{} "GNU Emacs 19.29.1 (i386-debian-linux) \ - of Tue Jun 6 1995 on balloon" -@end group -@end example - -Called interactively, the function prints the same information in the -echo area. -@end deffn - -@defvar emacs-build-time -The value of this variable is the time at which Emacs was built at the -local site. - -@example -@group -emacs-build-time - @result{} "Tue Jun 6 14:55:57 1995" -@end group -@end example -@end defvar - -@defvar emacs-version -The value of this variable is the version of Emacs being run. It is a -string such as @code{"19.29.1"}. -@end defvar - - The following two variables did not exist before Emacs version 19.23, -which reduces their usefulness at present, but we hope they will be -convenient in the future. - -@defvar emacs-major-version -The major version number of Emacs, as an integer. For Emacs version -19.29, the value is 19. -@end defvar - -@defvar emacs-minor-version -The minor version number of Emacs, as an integer. For Emacs version -19.29, the value is 29. -@end defvar - -@node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals -@appendixsec Pure Storage -@cindex pure storage - - Emacs Lisp uses two kinds of storage for user-created Lisp objects: -@dfn{normal storage} and @dfn{pure storage}. Normal storage is where -all the new data created during an Emacs session is kept; see the -following section for information on normal storage. Pure storage is -used for certain data in the preloaded standard Lisp files---data that -should never change during actual use of Emacs. - - Pure storage is allocated only while @file{temacs} is loading the -standard preloaded Lisp libraries. In the file @file{emacs}, it is -marked as read-only (on operating systems that permit this), so that -the memory space can be shared by all the Emacs jobs running on the -machine at once. Pure storage is not expandable; a fixed amount is -allocated when Emacs is compiled, and if that is not sufficient for the -preloaded libraries, @file{temacs} crashes. If that happens, you must -increase the compilation parameter @code{PURESIZE} in the file -@file{src/puresize.h}. This normally won't happen unless you try to -preload additional libraries or add features to the standard ones. - -@defun purecopy object -This function makes a copy of @var{object} in pure storage and returns -it. It copies strings by simply making a new string with the same -characters in pure storage. It recursively copies the contents of -vectors and cons cells. It does not make copies of other objects such -as symbols, but just returns them unchanged. It signals an error if -asked to copy markers. - -This function is a no-op except while Emacs is being built and dumped; -it is usually called only in the file @file{emacs/lisp/loaddefs.el}, but -a few packages call it just in case you decide to preload them. -@end defun - -@defvar pure-bytes-used -The value of this variable is the number of bytes of pure storage -allocated so far. Typically, in a dumped Emacs, this number is very -close to the total amount of pure storage available---if it were not, -we would preallocate less. -@end defvar - -@defvar purify-flag -This variable determines whether @code{defun} should make a copy of the -function definition in pure storage. If it is non-@code{nil}, then the -function definition is copied into pure storage. - -This flag is @code{t} while loading all of the basic functions for -building Emacs initially (allowing those functions to be sharable and -non-collectible). Dumping Emacs as an executable always writes -@code{nil} in this variable, regardless of the value it actually has -before and after dumping. - -You should not change this flag in a running Emacs. -@end defvar - -@node Garbage Collection, Writing Emacs Primitives, Pure Storage, GNU Emacs Internals -@appendixsec Garbage Collection -@cindex garbage collector - -@cindex memory allocation - When a program creates a list or the user defines a new function (such -as by loading a library), that data is placed in normal storage. If -normal storage runs low, then Emacs asks the operating system to -allocate more memory in blocks of 1k bytes. Each block is used for one -type of Lisp object, so symbols, cons cells, markers, etc., are -segregated in distinct blocks in memory. (Vectors, long strings, -buffers and certain other editing types, which are fairly large, are -allocated in individual blocks, one per object, while small strings are -packed into blocks of 8k bytes.) - - It is quite common to use some storage for a while, then release it by -(for example) killing a buffer or deleting the last pointer to an -object. Emacs provides a @dfn{garbage collector} to reclaim this -abandoned storage. (This name is traditional, but ``garbage recycler'' -might be a more intuitive metaphor for this facility.) - - The garbage collector operates by finding and marking all Lisp objects -that are still accessible to Lisp programs. To begin with, it assumes -all the symbols, their values and associated function definitions, and -any data presently on the stack, are accessible. Any objects that can -be reached indirectly through other accessible objects are also -accessible. - - When marking is finished, all objects still unmarked are garbage. No -matter what the Lisp program or the user does, it is impossible to refer -to them, since there is no longer a way to reach them. Their space -might as well be reused, since no one will miss them. The second -(``sweep'') phase of the garbage collector arranges to reuse them. - -@cindex free list - The sweep phase puts unused cons cells onto a @dfn{free list} -for future allocation; likewise for symbols and markers. It compacts -the accessible strings so they occupy fewer 8k blocks; then it frees the -other 8k blocks. Vectors, buffers, windows, and other large objects are -individually allocated and freed using @code{malloc} and @code{free}. - -@cindex CL note---allocate more storage -@quotation -@b{Common Lisp note:} Unlike other Lisps, GNU Emacs Lisp does not -call the garbage collector when the free list is empty. Instead, it -simply requests the operating system to allocate more storage, and -processing continues until @code{gc-cons-threshold} bytes have been -used. - -This means that you can make sure that the garbage collector will not -run during a certain portion of a Lisp program by calling the garbage -collector explicitly just before it (provided that portion of the -program does not use so much space as to force a second garbage -collection). -@end quotation - -@deffn Command garbage-collect -This command runs a garbage collection, and returns information on -the amount of space in use. (Garbage collection can also occur -spontaneously if you use more than @code{gc-cons-threshold} bytes of -Lisp data since the previous garbage collection.) - -@code{garbage-collect} returns a list containing the following -information: - -@example -@group -((@var{used-conses} . @var{free-conses}) - (@var{used-syms} . @var{free-syms}) -@end group - (@var{used-markers} . @var{free-markers}) - @var{used-string-chars} - @var{used-vector-slots} - (@var{used-floats} . @var{free-floats})) - -@group -(garbage-collect) - @result{} ((3435 . 2332) (1688 . 0) - (57 . 417) 24510 3839 (4 . 1)) -@end group -@end example - -Here is a table explaining each element: - -@table @var -@item used-conses -The number of cons cells in use. - -@item free-conses -The number of cons cells for which space has been obtained from the -operating system, but that are not currently being used. - -@item used-syms -The number of symbols in use. - -@item free-syms -The number of symbols for which space has been obtained from the -operating system, but that are not currently being used. - -@item used-markers -The number of markers in use. - -@item free-markers -The number of markers for which space has been obtained from the -operating system, but that are not currently being used. - -@item used-string-chars -The total size of all strings, in characters. - -@item used-vector-slots -The total number of elements of existing vectors. - -@item used-floats -@c Emacs 19 feature -The number of floats in use. - -@item free-floats -@c Emacs 19 feature -The number of floats for which space has been obtained from the -operating system, but that are not currently being used. -@end table -@end deffn - -@defopt garbage-collection-messages -If this variable is non-@code{nil}, Emacs displays a message at the -beginning and end of garbage collection. The default value is -@code{nil}, meaning there are no such messages. -@end defopt - -@defopt gc-cons-threshold -The value of this variable is the number of bytes of storage that must -be allocated for Lisp objects after one garbage collection in order to -trigger another garbage collection. A cons cell counts as eight bytes, -a string as one byte per character plus a few bytes of overhead, and so -on; space allocated to the contents of buffers does not count. Note -that the subsequent garbage collection does not happen immediately when -the threshold is exhausted, but only the next time the Lisp evaluator is -called. - -The initial threshold value is 300,000. If you specify a larger -value, garbage collection will happen less often. This reduces the -amount of time spent garbage collecting, but increases total memory use. -You may want to do this when running a program that creates lots of -Lisp data. - -You can make collections more frequent by specifying a smaller value, -down to 10,000. A value less than 10,000 will remain in effect only -until the subsequent garbage collection, at which time -@code{garbage-collect} will set the threshold back to 10,000. -@end defopt - -@c Emacs 19 feature -@defun memory-limit -This function returns the address of the last byte Emacs has allocated, -divided by 1024. We divide the value by 1024 to make sure it fits in a -Lisp integer. - -You can use this to get a general idea of how your actions affect the -memory usage. -@end defun - -@node Writing Emacs Primitives, Object Internals, Garbage Collection, GNU Emacs Internals -@appendixsec Writing Emacs Primitives -@cindex primitive function internals - - Lisp primitives are Lisp functions implemented in C. The details of -interfacing the C function so that Lisp can call it are handled by a few -C macros. The only way to really understand how to write new C code is -to read the source, but we can explain some things here. - - An example of a special form is the definition of @code{or}, from -@file{eval.c}. (An ordinary function would have the same general -appearance.) - -@cindex garbage collection protection -@smallexample -@group -DEFUN ("or", For, Sor, 0, UNEVALLED, 0, - "Eval args until one of them yields non-nil; return that value.\n\ -The remaining args are not evalled at all.\n\ -@end group -@group -If all args return nil, return nil.") - (args) - Lisp_Object args; -@{ - register Lisp_Object val; - Lisp_Object args_left; - struct gcpro gcpro1; -@end group - -@group - if (NULL (args)) - return Qnil; - - args_left = args; - GCPRO1 (args_left); -@end group - -@group - do - @{ - val = Feval (Fcar (args_left)); - if (!NULL (val)) - break; - args_left = Fcdr (args_left); - @} - while (!NULL (args_left)); -@end group - -@group - UNGCPRO; - return val; -@} -@end group -@end smallexample - - Let's start with a precise explanation of the arguments to the -@code{DEFUN} macro. Here is a template for them: - -@example -DEFUN (@var{lname}, @var{fname}, @var{sname}, @var{min}, @var{max}, @var{interactive}, @var{doc}) -@end example - -@table @var -@item lname -This is the name of the Lisp symbol to define as the function name; in -the example above, it is @code{or}. - -@item fname -This is the C function name for this function. This is -the name that is used in C code for calling the function. The name is, -by convention, @samp{F} prepended to the Lisp name, with all dashes -(@samp{-}) in the Lisp name changed to underscores. Thus, to call this -function from C code, call @code{For}. Remember that the arguments must -be of type @code{Lisp_Object}; various macros and functions for creating -values of type @code{Lisp_Object} are declared in the file -@file{lisp.h}. - -@item sname -This is a C variable name to use for a structure that holds the data for -the subr object that represents the function in Lisp. This structure -conveys the Lisp symbol name to the initialization routine that will -create the symbol and store the subr object as its definition. By -convention, this name is always @var{fname} with @samp{F} replaced with -@samp{S}. - -@item min -This is the minimum number of arguments that the function requires. The -function @code{or} allows a minimum of zero arguments. - -@item max -This is the maximum number of arguments that the function accepts, if -there is a fixed maximum. Alternatively, it can be @code{UNEVALLED}, -indicating a special form that receives unevaluated arguments, or -@code{MANY}, indicating an unlimited number of evaluated arguments (the -equivalent of @code{&rest}). Both @code{UNEVALLED} and @code{MANY} are -macros. If @var{max} is a number, it may not be less than @var{min} and -it may not be greater than seven. - -@item interactive -This is an interactive specification, a string such as might be used as -the argument of @code{interactive} in a Lisp function. In the case of -@code{or}, it is 0 (a null pointer), indicating that @code{or} cannot be -called interactively. A value of @code{""} indicates a function that -should receive no arguments when called interactively. - -@item doc -This is the documentation string. It is written just like a -documentation string for a function defined in Lisp, except you must -write @samp{\n\} at the end of each line. In particular, the first line -should be a single sentence. -@end table - - After the call to the @code{DEFUN} macro, you must write the argument -name list that every C function must have, followed by ordinary C -declarations for the arguments. For a function with a fixed maximum -number of arguments, declare a C argument for each Lisp argument, and -give them all type @code{Lisp_Object}. When a Lisp function has no -upper limit on the number of arguments, its implementation in C actually -receives exactly two arguments: the first is the number of Lisp -arguments, and the second is the address of a block containing their -values. They have types @code{int} and @w{@code{Lisp_Object *}}. - - Within the function @code{For} itself, note the use of the macros -@code{GCPRO1} and @code{UNGCPRO}. @code{GCPRO1} is used to ``protect'' -a variable from garbage collection---to inform the garbage collector that -it must look in that variable and regard its contents as an accessible -object. This is necessary whenever you call @code{Feval} or anything -that can directly or indirectly call @code{Feval}. At such a time, any -Lisp object that you intend to refer to again must be protected somehow. -@code{UNGCPRO} cancels the protection of the variables that are -protected in the current function. It is necessary to do this explicitly. - - For most data types, it suffices to protect at least one pointer to -the object; as long as the object is not recycled, all pointers to it -remain valid. This is not so for strings, because the garbage collector -can move them. When the garbage collector moves a string, it relocates -all the pointers it knows about; any other pointers become invalid. -Therefore, you must protect all pointers to strings across any point -where garbage collection may be possible. - - The macro @code{GCPRO1} protects just one local variable. If you want -to protect two, use @code{GCPRO2} instead; repeating @code{GCPRO1} will -not work. Macros @code{GCPRO3} and @code{GCPRO4} also exist. - - These macros implicitly use local variables such as @code{gcpro1}; you -must declare these explicitly, with type @code{struct gcpro}. Thus, if -you use @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}. -Alas, we can't explain all the tricky details here. - - You must not use C initializers for static or global variables unless -they are never written once Emacs is dumped. These variables with -initializers are allocated in an area of memory that becomes read-only -(on certain operating systems) as a result of dumping Emacs. @xref{Pure -Storage}. - - Do not use static variables within functions---place all static -variables at top level in the file. This is necessary because Emacs on -some operating systems defines the keyword @code{static} as a null -macro. (This definition is used because those systems put all variables -declared static in a place that becomes read-only after dumping, whether -they have initializers or not.) - - Defining the C function is not enough to make a Lisp primitive -available; you must also create the Lisp symbol for the primitive and -store a suitable subr object in its function cell. The code looks like -this: - -@example -defsubr (&@var{subr-structure-name}); -@end example - -@noindent -Here @var{subr-structure-name} is the name you used as the third -argument to @code{DEFUN}. - - If you add a new primitive to a file that already has Lisp primitives -defined in it, find the function (near the end of the file) named -@code{syms_of_@var{something}}, and add the call to @code{defsubr} -there. If the file doesn't have this function, or if you create a new -file, add to it a @code{syms_of_@var{filename}} (e.g., -@code{syms_of_myfile}). Then find the spot in @file{emacs.c} where all -of these functions are called, and add a call to -@code{syms_of_@var{filename}} there. - - The function @code{syms_of_@var{filename}} is also the place to define -any C variables that are to be visible as Lisp variables. -@code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible -in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int} -visible in Lisp with a value that is always an integer. -@code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp -with a value that is either @code{t} or @code{nil}. - - Here is another example function, with more complicated arguments. -This comes from the code for the X Window System, and it demonstrates -the use of macros and functions to manipulate Lisp objects. - -@smallexample -@group -DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p, - Scoordinates_in_window_p, 2, 2, - "xSpecify coordinate pair: \nXExpression which evals to window: ", - "Return non-nil if POSITIONS is in WINDOW.\n\ - \(POSITIONS is a list, (SCREEN-X SCREEN-Y)\)\n\ -@end group -@group - Returned value is list of positions expressed\n\ - relative to window upper left corner.") - (coordinate, window) - register Lisp_Object coordinate, window; -@{ - register Lisp_Object xcoord, ycoord; -@end group - -@group - if (!CONSP (coordinate)) wrong_type_argument (Qlistp, coordinate); - CHECK_WINDOW (window, 2); - xcoord = Fcar (coordinate); - ycoord = Fcar (Fcdr (coordinate)); - CHECK_NUMBER (xcoord, 0); - CHECK_NUMBER (ycoord, 1); -@end group -@group - if ((XINT (xcoord) < XINT (XWINDOW (window)->left)) - || (XINT (xcoord) >= (XINT (XWINDOW (window)->left) - + XINT (XWINDOW (window)->width)))) - return Qnil; - XFASTINT (xcoord) -= XFASTINT (XWINDOW (window)->left); -@end group -@group - if (XINT (ycoord) == (screen_height - 1)) - return Qnil; -@end group -@group - if ((XINT (ycoord) < XINT (XWINDOW (window)->top)) - || (XINT (ycoord) >= (XINT (XWINDOW (window)->top) - + XINT (XWINDOW (window)->height)) - 1)) - return Qnil; -@end group -@group - XFASTINT (ycoord) -= XFASTINT (XWINDOW (window)->top); - return (Fcons (xcoord, Fcons (ycoord, Qnil))); -@} -@end group -@end smallexample - - Note that C code cannot call functions by name unless they are defined -in C. The way to call a function written in Lisp is to use -@code{Ffuncall}, which embodies the Lisp function @code{funcall}. Since -the Lisp function @code{funcall} accepts an unlimited number of -arguments, in C it takes two: the number of Lisp-level arguments, and a -one-dimensional array containing their values. The first Lisp-level -argument is the Lisp function to call, and the rest are the arguments to -pass to it. Since @code{Ffuncall} can call the evaluator, you must -protect pointers from garbage collection around the call to -@code{Ffuncall}. - - The C functions @code{call0}, @code{call1}, @code{call2}, and so on, -provide handy ways to call a Lisp function conveniently with a fixed -number of arguments. They work by calling @code{Ffuncall}. - - @file{eval.c} is a very good file to look through for examples; -@file{lisp.h} contains the definitions for some important macros and -functions. - -@node Object Internals, , Writing Emacs Primitives, GNU Emacs Internals -@appendixsec Object Internals -@cindex object internals - - GNU Emacs Lisp manipulates many different types of data. The actual -data are stored in a heap and the only access that programs have to it is -through pointers. Pointers are thirty-two bits wide in most -implementations. Depending on the operating system and type of machine -for which you compile Emacs, twenty-four to twenty-six bits are used to -address the object, and the remaining six to eight bits are used for a -tag that identifies the object's type. - - Because Lisp objects are represented as tagged pointers, it is always -possible to determine the Lisp data type of any object. The C data type -@code{Lisp_Object} can hold any Lisp object of any data type. Ordinary -variables have type @code{Lisp_Object}, which means they can hold any -type of Lisp value; you can determine the actual data type only at run -time. The same is true for function arguments; if you want a function -to accept only a certain type of argument, you must check the type -explicitly using a suitable predicate (@pxref{Type Predicates}). -@cindex type checking internals - -@menu -* Buffer Internals:: Components of a buffer structure. -* Window Internals:: Components of a window structure. -* Process Internals:: Components of a process structure. -@end menu - -@node Buffer Internals, Window Internals, Object Internals, Object Internals -@appendixsubsec Buffer Internals -@cindex internals, of buffer -@cindex buffer internals - - Buffers contain fields not directly accessible by the Lisp programmer. -We describe them here, naming them by the names used in the C code. -Many are accessible indirectly in Lisp programs via Lisp primitives. - -@table @code -@item name -The buffer name is a string that names the buffer. It is guaranteed to -be unique. @xref{Buffer Names}. - -@item save_modified -This field contains the time when the buffer was last saved, as an integer. -@xref{Buffer Modification}. - -@item modtime -This field contains the modification time of the visited file. It is -set when the file is written or read. Every time the buffer is written -to the file, this field is compared to the modification time of the -file. @xref{Buffer Modification}. - -@item auto_save_modified -This field contains the time when the buffer was last auto-saved. - -@item last_window_start -This field contains the @code{window-start} position in the buffer as of -the last time the buffer was displayed in a window. - -@item undo_list -This field points to the buffer's undo list. @xref{Undo}. - -@item syntax_table_v -This field contains the syntax table for the buffer. @xref{Syntax Tables}. - -@item downcase_table -This field contains the conversion table for converting text to lower case. -@xref{Case Table}. - -@item upcase_table -This field contains the conversion table for converting text to upper case. -@xref{Case Table}. - -@item case_canon_table -This field contains the conversion table for canonicalizing text for -case-folding search. @xref{Case Table}. - -@item case_eqv_table -This field contains the equivalence table for case-folding search. -@xref{Case Table}. - -@item display_table -This field contains the buffer's display table, or @code{nil} if it doesn't -have one. @xref{Display Tables}. - -@item markers -This field contains the chain of all markers that currently point into -the buffer. Deletion of text in the buffer, and motion of the buffer's -gap, must check each of these markers and perhaps update it. -@xref{Markers}. - -@item backed_up -This field is a flag that tells whether a backup file has been made -for the visited file of this buffer. - -@item mark -This field contains the mark for the buffer. The mark is a marker, -hence it is also included on the list @code{markers}. @xref{The Mark}. - -@item mark_active -This field is non-@code{nil} if the buffer's mark is active. - -@item local_var_alist -This field contains the association list describing the variables local -in this buffer, and their values, with the exception of local variables -that have special slots in the buffer object. (Those slots are omitted -from this table.) @xref{Buffer-Local Variables}. - -@item base_buffer -This field holds the buffer's base buffer (if it is an indirect buffer), -or @code{nil}. - -@item keymap -This field holds the buffer's local keymap. @xref{Keymaps}. - -@item overlay_center -This field holds the current overlay center position. @xref{Overlays}. - -@item overlays_before -This field holds a list of the overlays in this buffer that end at or -before the current overlay center position. They are sorted in order of -decreasing end position. - -@item overlays_after -This field holds a list of the overlays in this buffer that end after -the current overlay center position. They are sorted in order of -increasing beginning position. -@end table - -@node Window Internals, Process Internals, Buffer Internals, Object Internals -@appendixsubsec Window Internals -@cindex internals, of window -@cindex window internals - - Windows have the following accessible fields: - -@table @code -@item frame -The frame that this window is on. - -@item mini_p -Non-@code{nil} if this window is a minibuffer window. - -@item buffer -The buffer that the window is displaying. This may change often during -the life of the window. - -@item dedicated -Non-@code{nil} if this window is dedicated to its buffer. - -@item pointm -@cindex window point internals -This is the value of point in the current buffer when this window is -selected; when it is not selected, it retains its previous value. - -@item start -The position in the buffer that is the first character to be displayed -in the window. - -@item force_start -If this flag is non-@code{nil}, it says that the window has been -scrolled explicitly by the Lisp program. This affects what the next -redisplay does if point is off the screen: instead of scrolling the -window to show the text around point, it moves point to a location that -is on the screen. - -@item last_modified -The @code{modified} field of the window's buffer, as of the last time -a redisplay completed in this window. - -@item last_point -The buffer's value of point, as of the last time -a redisplay completed in this window. - -@item left -This is the left-hand edge of the window, measured in columns. (The -leftmost column on the screen is @w{column 0}.) - -@item top -This is the top edge of the window, measured in lines. (The top line on -the screen is @w{line 0}.) - -@item height -The height of the window, measured in lines. - -@item width -The width of the window, measured in columns. - -@item next -This is the window that is the next in the chain of siblings. It is -@code{nil} in a window that is the rightmost or bottommost of a group of -siblings. - -@item prev -This is the window that is the previous in the chain of siblings. It is -@code{nil} in a window that is the leftmost or topmost of a group of -siblings. - -@item parent -Internally, Emacs arranges windows in a tree; each group of siblings has -a parent window whose area includes all the siblings. This field points -to a window's parent. - -Parent windows do not display buffers, and play little role in display -except to shape their child windows. Emacs Lisp programs usually have -no access to the parent windows; they operate on the windows at the -leaves of the tree, which actually display buffers. - -@item hscroll -This is the number of columns that the display in the window is scrolled -horizontally to the left. Normally, this is 0. - -@item use_time -This is the last time that the window was selected. The function -@code{get-lru-window} uses this field. - -@item display_table -The window's display table, or @code{nil} if none is specified for it. - -@item update_mode_line -Non-@code{nil} means this window's mode line needs to be updated. - -@item base_line_number -The line number of a certain position in the buffer, or @code{nil}. -This is used for displaying the line number of point in the mode line. - -@item base_line_pos -The position in the buffer for which the line number is known, or -@code{nil} meaning none is known. - -@item region_showing -If the region (or part of it) is highlighted in this window, this field -holds the mark position that made one end of that region. Otherwise, -this field is @code{nil}. -@end table - -@node Process Internals, , Window Internals, Object Internals -@appendixsubsec Process Internals -@cindex internals, of process -@cindex process internals - - The fields of a process are: - -@table @code -@item name -A string, the name of the process. - -@item command -A list containing the command arguments that were used to start this -process. - -@item filter -A function used to accept output from the process instead of a buffer, -or @code{nil}. - -@item sentinel -A function called whenever the process receives a signal, or @code{nil}. - -@item buffer -The associated buffer of the process. - -@item pid -An integer, the Unix process @sc{id}. - -@item childp -A flag, non-@code{nil} if this is really a child process. -It is @code{nil} for a network connection. - -@item mark -A marker indicating the position of the end of the last output from this -process inserted into the buffer. This is often but not always the end -of the buffer. - -@item kill_without_query -If this is non-@code{nil}, killing Emacs while this process is still -running does not ask for confirmation about killing the process. - -@item raw_status_low -@itemx raw_status_high -These two fields record 16 bits each of the process status returned by -the @code{wait} system call. - -@item status -The process status, as @code{process-status} should return it. - -@item tick -@itemx update_tick -If these two fields are not equal, a change in the status of the process -needs to be reported, either by running the sentinel or by inserting a -message in the process buffer. - -@item pty_flag -Non-@code{nil} if communication with the subprocess uses a @sc{pty}; -@code{nil} if it uses a pipe. - -@item infd -The file descriptor for input from the process. - -@item outfd -The file descriptor for output to the process. - -@item subtty -The file descriptor for the terminal that the subprocess is using. (On -some systems, there is no need to record this, so the value is -@code{nil}.) - -@item tty_name -The name of the terminal that the subprocess is using, -or @code{nil} if it is using pipes. -@end table diff --git a/lispref/intro.texi b/lispref/intro.texi deleted file mode 100644 index def0d1c84bc..00000000000 --- a/lispref/intro.texi +++ /dev/null @@ -1,866 +0,0 @@ -@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/intro - -@node Copying, Introduction, Top, Top -@comment node-name, next, previous, up -@unnumbered GNU GENERAL PUBLIC LICENSE -@center Version 2, June 1991 - -@display -Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. -675 Mass Ave, Cambridge, MA 02139, USA - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@unnumberedsec Preamble - - The licenses for most software are designed to take away your -freedom to share and change it. By contrast, the GNU General Public -License is intended to guarantee your freedom to share and change free -software---to make sure the software is free for all its users. This -General Public License applies to most of the Free Software -Foundation's software and to any other program whose authors commit to -using it. (Some other Free Software Foundation software is covered by -the GNU Library General Public License instead.) You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -this service if you wish), that you receive source code or can get it -if you want it, that you can change the software or use pieces of it -in new free programs; and that you know you can do these things. - - To protect your rights, we need to make restrictions that forbid -anyone to deny you these rights or to ask you to surrender the rights. -These restrictions translate to certain responsibilities for you if you -distribute copies of the software, or if you modify it. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must give the recipients all the rights that -you have. You must make sure that they, too, receive or can get the -source code. And you must show them these terms so they know their -rights. - - We protect your rights with two steps: (1) copyright the software, and -(2) offer you this license which gives you legal permission to copy, -distribute and/or modify the software. - - Also, for each author's protection and ours, we want to make certain -that everyone understands that there is no warranty for this free -software. If the software is modified by someone else and passed on, we -want its recipients to know that what they have is not the original, so -that any problems introduced by others will not reflect on the original -authors' reputations. - - Finally, any free program is threatened constantly by software -patents. We wish to avoid the danger that redistributors of a free -program will individually obtain patent licenses, in effect making the -program proprietary. To prevent this, we have made it clear that any -patent must be licensed for everyone's free use or not licensed at all. - - The precise terms and conditions for copying, distribution and -modification follow. - -@iftex -@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -@end iftex -@ifinfo -@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION -@end ifinfo - -@enumerate 0 -@item -This License applies to any program or other work which contains -a notice placed by the copyright holder saying it may be distributed -under the terms of this General Public License. The ``Program'', below, -refers to any such program or work, and a ``work based on the Program'' -means either the Program or any derivative work under copyright law: -that is to say, a work containing the Program or a portion of it, -either verbatim or with modifications and/or translated into another -language. (Hereinafter, translation is included without limitation in -the term ``modification''.) Each licensee is addressed as ``you''. - -Activities other than copying, distribution and modification are not -covered by this License; they are outside its scope. The act of -running the Program is not restricted, and the output from the Program -is covered only if its contents constitute a work based on the -Program (independent of having been made by running the Program). -Whether that is true depends on what the Program does. - -@item -You may copy and distribute verbatim copies of the Program's -source code as you receive it, in any medium, provided that you -conspicuously and appropriately publish on each copy an appropriate -copyright notice and disclaimer of warranty; keep intact all the -notices that refer to this License and to the absence of any warranty; -and give any other recipients of the Program a copy of this License -along with the Program. - -You may charge a fee for the physical act of transferring a copy, and -you may at your option offer warranty protection in exchange for a fee. - -@item -You may modify your copy or copies of the Program or any portion -of it, thus forming a work based on the Program, and copy and -distribute such modifications or work under the terms of Section 1 -above, provided that you also meet all of these conditions: - -@enumerate a -@item -You must cause the modified files to carry prominent notices -stating that you changed the files and the date of any change. - -@item -You must cause any work that you distribute or publish, that in -whole or in part contains or is derived from the Program or any -part thereof, to be licensed as a whole at no charge to all third -parties under the terms of this License. - -@item -If the modified program normally reads commands interactively -when run, you must cause it, when started running for such -interactive use in the most ordinary way, to print or display an -announcement including an appropriate copyright notice and a -notice that there is no warranty (or else, saying that you provide -a warranty) and that users may redistribute the program under -these conditions, and telling the user how to view a copy of this -License. (Exception: if the Program itself is interactive but -does not normally print such an announcement, your work based on -the Program is not required to print an announcement.) -@end enumerate - -These requirements apply to the modified work as a whole. If -identifiable sections of that work are not derived from the Program, -and can be reasonably considered independent and separate works in -themselves, then this License, and its terms, do not apply to those -sections when you distribute them as separate works. But when you -distribute the same sections as part of a whole which is a work based -on the Program, the distribution of the whole must be on the terms of -this License, whose permissions for other licensees extend to the -entire whole, and thus to each and every part regardless of who wrote it. - -Thus, it is not the intent of this section to claim rights or contest -your rights to work written entirely by you; rather, the intent is to -exercise the right to control the distribution of derivative or -collective works based on the Program. - -In addition, mere aggregation of another work not based on the Program -with the Program (or with a work based on the Program) on a volume of -a storage or distribution medium does not bring the other work under -the scope of this License. - -@item -You may copy and distribute the Program (or a work based on it, -under Section 2) in object code or executable form under the terms of -Sections 1 and 2 above provided that you also do one of the following: - -@enumerate a -@item -Accompany it with the complete corresponding machine-readable -source code, which must be distributed under the terms of Sections -1 and 2 above on a medium customarily used for software interchange; or, - -@item -Accompany it with a written offer, valid for at least three -years, to give any third party, for a charge no more than your -cost of physically performing source distribution, a complete -machine-readable copy of the corresponding source code, to be -distributed under the terms of Sections 1 and 2 above on a medium -customarily used for software interchange; or, - -@item -Accompany it with the information you received as to the offer -to distribute corresponding source code. (This alternative is -allowed only for noncommercial distribution and only if you -received the program in object code or executable form with such -an offer, in accord with Subsection b above.) -@end enumerate - -The source code for a work means the preferred form of the work for -making modifications to it. For an executable work, complete source -code means all the source code for all modules it contains, plus any -associated interface definition files, plus the scripts used to -control compilation and installation of the executable. However, as a -special exception, the source code distributed need not include -anything that is normally distributed (in either source or binary -form) with the major components (compiler, kernel, and so on) of the -operating system on which the executable runs, unless that component -itself accompanies the executable. - -If distribution of executable or object code is made by offering -access to copy from a designated place, then offering equivalent -access to copy the source code from the same place counts as -distribution of the source code, even though third parties are not -compelled to copy the source along with the object code. - -@item -You may not copy, modify, sublicense, or distribute the Program -except as expressly provided under this License. Any attempt -otherwise to copy, modify, sublicense or distribute the Program is -void, and will automatically terminate your rights under this License. -However, parties who have received copies, or rights, from you under -this License will not have their licenses terminated so long as such -parties remain in full compliance. - -@item -You are not required to accept this License, since you have not -signed it. However, nothing else grants you permission to modify or -distribute the Program or its derivative works. These actions are -prohibited by law if you do not accept this License. Therefore, by -modifying or distributing the Program (or any work based on the -Program), you indicate your acceptance of this License to do so, and -all its terms and conditions for copying, distributing or modifying -the Program or works based on it. - -@item -Each time you redistribute the Program (or any work based on the -Program), the recipient automatically receives a license from the -original licensor to copy, distribute or modify the Program subject to -these terms and conditions. You may not impose any further -restrictions on the recipients' exercise of the rights granted herein. -You are not responsible for enforcing compliance by third parties to -this License. - -@item -If, as a consequence of a court judgment or allegation of patent -infringement or for any other reason (not limited to patent issues), -conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot -distribute so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you -may not distribute the Program at all. For example, if a patent -license would not permit royalty-free redistribution of the Program by -all those who receive copies directly or indirectly through you, then -the only way you could satisfy both it and this License would be to -refrain entirely from distribution of the Program. - -If any portion of this section is held invalid or unenforceable under -any particular circumstance, the balance of the section is intended to -apply and the section as a whole is intended to apply in other -circumstances. - -It is not the purpose of this section to induce you to infringe any -patents or other property right claims or to contest validity of any -such claims; this section has the sole purpose of protecting the -integrity of the free software distribution system, which is -implemented by public license practices. Many people have made -generous contributions to the wide range of software distributed -through that system in reliance on consistent application of that -system; it is up to the author/donor to decide if he or she is willing -to distribute software through any other system and a licensee cannot -impose that choice. - -This section is intended to make thoroughly clear what is believed to -be a consequence of the rest of this License. - -@item -If the distribution and/or use of the Program is restricted in -certain countries either by patents or by copyrighted interfaces, the -original copyright holder who places the Program under this License -may add an explicit geographical distribution limitation excluding -those countries, so that distribution is permitted only in or among -countries not thus excluded. In such case, this License incorporates -the limitation as if written in the body of this License. - -@item -The Free Software Foundation may publish revised and/or new versions -of the General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - -Each version is given a distinguishing version number. If the Program -specifies a version number of this License which applies to it and ``any -later version'', you have the option of following the terms and conditions -either of that version or of any later version published by the Free -Software Foundation. If the Program does not specify a version number of -this License, you may choose any version ever published by the Free Software -Foundation. - -@item -If you wish to incorporate parts of the Program into other free -programs whose distribution conditions are different, write to the author -to ask for permission. For software which is copyrighted by the Free -Software Foundation, write to the Free Software Foundation; we sometimes -make exceptions for this. Our decision will be guided by the two goals -of preserving the free status of all derivatives of our free software and -of promoting the sharing and reuse of software generally. - -@iftex -@heading NO WARRANTY -@end iftex -@ifinfo -@center NO WARRANTY -@end ifinfo - -@item -BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY -FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN -OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES -PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED -OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF -MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@. THE ENTIRE RISK AS -TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU@. SHOULD THE -PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, -REPAIR OR CORRECTION. - -@item -IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR -REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, -INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING -OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED -TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY -YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER -PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE -POSSIBILITY OF SUCH DAMAGES. -@end enumerate - -@iftex -@heading END OF TERMS AND CONDITIONS -@end iftex -@ifinfo -@center END OF TERMS AND CONDITIONS -@end ifinfo - -@page -@unnumberedsec How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -convey the exclusion of warranty; and each file should have at least -the ``copyright'' line and a pointer to where the full notice is found. - -@smallexample -@var{one line to give the program's name and an idea of what it does.} -Copyright (C) 19@var{yy} @var{name of author} - -This program is free software; you can redistribute it and/or -modify it under the terms of the GNU General Public License -as published by the Free Software Foundation; either version 2 -of the License, or (at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program; if not, write to the Free Software -Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. -@end smallexample - -Also add information on how to contact you by electronic and paper mail. - -If the program is interactive, make it output a short notice like this -when it starts in an interactive mode: - -@smallexample -Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} -Gnomovision comes with ABSOLUTELY NO WARRANTY; for details -type `show w'. This is free software, and you are welcome -to redistribute it under certain conditions; type `show c' -for details. -@end smallexample - -The hypothetical commands @samp{show w} and @samp{show c} should show -the appropriate parts of the General Public License. Of course, the -commands you use may be called something other than @samp{show w} and -@samp{show c}; they could even be mouse-clicks or menu items---whatever -suits your program. - -You should also get your employer (if you work as a programmer) or your -school, if any, to sign a ``copyright disclaimer'' for the program, if -necessary. Here is a sample; alter the names: - -@smallexample -@group -Yoyodyne, Inc., hereby disclaims all copyright -interest in the program `Gnomovision' -(which makes passes at compilers) written -by James Hacker. - -@var{signature of Ty Coon}, 1 April 1989 -Ty Coon, President of Vice -@end group -@end smallexample - -This General Public License does not permit incorporating your program into -proprietary programs. If your program is a subroutine library, you may -consider it more useful to permit linking proprietary applications with the -library. If this is what you want to do, use the GNU Library General -Public License instead of this License. - -@node Introduction, Lisp Data Types, Copying, Top -@chapter Introduction - - Most of the GNU Emacs text editor is written in the programming -language called Emacs Lisp. You can write new code in Emacs Lisp and -install it as an extension to the editor. However, Emacs Lisp is more -than a mere ``extension language''; it is a full computer programming -language in its own right. You can use it as you would any other -programming language. - - Because Emacs Lisp is designed for use in an editor, it has special -features for scanning and parsing text as well as features for handling -files, buffers, displays, subprocesses, and so on. Emacs Lisp is -closely integrated with the editing facilities; thus, editing commands -are functions that can also conveniently be called from Lisp programs, -and parameters for customization are ordinary Lisp variables. - - This manual describes Emacs Lisp, presuming considerable familiarity -with the use of Emacs for editing. (See @cite{The GNU Emacs Manual} -for this basic information.) Generally speaking, the earlier chapters -describe features of Emacs Lisp that have counterparts in many -programming languages, and later chapters describe features that are -peculiar to Emacs Lisp or relate specifically to editing. - - This is edition 2.4. - -@menu -* Caveats:: Flaws and a request for help. -* Lisp History:: Emacs Lisp is descended from Maclisp. -* Conventions:: How the manual is formatted. -* Acknowledgements:: The authors, editors, and sponsors of this manual. -@end menu - -@node Caveats -@section Caveats - - This manual has gone through numerous drafts. It is nearly complete -but not flawless. There are a few topics that are not covered, either -because we consider them secondary (such as most of the individual -modes) or because they are yet to be written. Because we are not able -to deal with them completely, we have left out several parts -intentionally. This includes most information about usage on VMS. - - The manual should be fully correct in what it does cover, and it is -therefore open to criticism on anything it says---from specific examples -and descriptive text, to the ordering of chapters and sections. If -something is confusing, or you find that you have to look at the sources -or experiment to learn something not covered in the manual, then perhaps -the manual should be fixed. Please let us know. - -@iftex - As you use the manual, we ask that you mark pages with corrections so -you can later look them up and send them in. If you think of a simple, -real-life example for a function or group of functions, please make an -effort to write it up and send it in. Please reference any comments to -the chapter name, section name, and function name, as appropriate, since -page numbers and chapter and section numbers will change and we may have -trouble finding the text you are talking about. Also state the number -of the edition you are criticizing. -@end iftex -@ifinfo - -As you use this manual, we ask that you send corrections as soon as you -find them. If you think of a simple, real life example for a function -or group of functions, please make an effort to write it up and send it -in. Please reference any comments to the node name and function or -variable name, as appropriate. Also state the number of the edition -which you are criticizing. -@end ifinfo - -Please mail comments and corrections to - -@example -bug-lisp-manual@@prep.ai.mit.edu -@end example - -@noindent -We let mail to this list accumulate unread until someone decides to -apply the corrections. Months, and sometimes years, go by between -updates. So please attach no significance to the lack of a reply---your -mail @emph{will} be acted on in due time. If you want to contact the -Emacs maintainers more quickly, send mail to -@code{bug-gnu-emacs@@prep.ai.mit.edu}. - -@display - --Bil Lewis, Dan LaLiberte, Richard Stallman -@end display - -@node Lisp History -@section Lisp History -@cindex Lisp history - - Lisp (LISt Processing language) was first developed in the late 1950's -at the Massachusetts Institute of Technology for research in artificial -intelligence. The great power of the Lisp language makes it superior -for other purposes as well, such as writing editing commands. - -@cindex Maclisp -@cindex Common Lisp - Dozens of Lisp implementations have been built over the years, each -with its own idiosyncrasies. Many of them were inspired by Maclisp, -which was written in the 1960's at MIT's Project MAC. Eventually the -implementors of the descendants of Maclisp came together and developed a -standard for Lisp systems, called Common Lisp. - - GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common -Lisp. If you know Common Lisp, you will notice many similarities. -However, many of the features of Common Lisp have been omitted or -simplified in order to reduce the memory requirements of GNU Emacs. -Sometimes the simplifications are so drastic that a Common Lisp user -might be very confused. We will occasionally point out how GNU Emacs -Lisp differs from Common Lisp. If you don't know Common Lisp, don't -worry about it; this manual is self-contained. - -@node Conventions -@section Conventions - -This section explains the notational conventions that are used in this -manual. You may want to skip this section and refer back to it later. - -@menu -* Some Terms:: Explanation of terms we use in this manual. -* nil and t:: How the symbols @code{nil} and @code{t} are used. -* Evaluation Notation:: The format we use for examples of evaluation. -* Printing Notation:: The format we use for examples that print output. -* Error Messages:: The format we use for examples of errors. -* Buffer Text Notation:: The format we use for buffer contents in examples. -* Format of Descriptions:: Notation for describing functions, variables, etc. -@end menu - -@node Some Terms -@subsection Some Terms - - Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp -printer'' are used to refer to those routines in Lisp that convert -textual representations of Lisp objects into actual Lisp objects, and vice -versa. @xref{Printed Representation}, for more details. You, the -person reading this manual, are thought of as ``the programmer'' and are -addressed as ``you''. ``The user'' is the person who uses Lisp programs, -including those you write. - -@cindex fonts - Examples of Lisp code appear in this font or form: @code{(list 1 2 -3)}. Names that represent arguments or metasyntactic variables appear -in this font or form: @var{first-number}. - -@node nil and t -@subsection @code{nil} and @code{t} -@cindex @code{nil}, uses of -@cindex truth value -@cindex boolean -@cindex false - - In Lisp, the symbol @code{nil} has three separate meanings: it -is a symbol with the name @samp{nil}; it is the logical truth value -@var{false}; and it is the empty list---the list of zero elements. -When used as a variable, @code{nil} always has the value @code{nil}. - - As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are -identical: they stand for the same object, the symbol @code{nil}. The -different ways of writing the symbol are intended entirely for human -readers. After the Lisp reader has read either @samp{()} or @samp{nil}, -there is no way to determine which representation was actually written -by the programmer. - - In this manual, we use @code{()} when we wish to emphasize that it -means the empty list, and we use @code{nil} when we wish to emphasize -that it means the truth value @var{false}. That is a good convention to use -in Lisp programs also. - -@example -(cons 'foo ()) ; @r{Emphasize the empty list} -(not nil) ; @r{Emphasize the truth value @var{false}} -@end example - -@cindex @code{t} and truth -@cindex true - In contexts where a truth value is expected, any non-@code{nil} value -is considered to be @var{true}. However, @code{t} is the preferred way -to represent the truth value @var{true}. When you need to choose a -value which represents @var{true}, and there is no other basis for -choosing, use @code{t}. The symbol @code{t} always has value @code{t}. - - In Emacs Lisp, @code{nil} and @code{t} are special symbols that always -evaluate to themselves. This is so that you do not need to quote them -to use them as constants in a program. An attempt to change their -values results in a @code{setting-constant} error. @xref{Accessing -Variables}. - -@node Evaluation Notation -@subsection Evaluation Notation -@cindex evaluation notation -@cindex documentation notation - - A Lisp expression that you can evaluate is called a @dfn{form}. -Evaluating a form always produces a result, which is a Lisp object. In -the examples in this manual, this is indicated with @samp{@result{}}: - -@example -(car '(1 2)) - @result{} 1 -@end example - -@noindent -You can read this as ``@code{(car '(1 2))} evaluates to 1''. - - When a form is a macro call, it expands into a new form for Lisp to -evaluate. We show the result of the expansion with -@samp{@expansion{}}. We may or may not show the actual result of the -evaluation of the expanded form. - -@example -(third '(a b c)) - @expansion{} (car (cdr (cdr '(a b c)))) - @result{} c -@end example - - Sometimes to help describe one form we show another form that -produces identical results. The exact equivalence of two forms is -indicated with @samp{@equiv{}}. - -@example -(make-sparse-keymap) @equiv{} (list 'keymap) -@end example - -@node Printing Notation -@subsection Printing Notation -@cindex printing notation - - Many of the examples in this manual print text when they are -evaluated. If you execute example code in a Lisp Interaction buffer -(such as the buffer @samp{*scratch*}), the printed text is inserted into -the buffer. If you execute the example by other means (such as by -evaluating the function @code{eval-region}), the printed text is -displayed in the echo area. You should be aware that text displayed in -the echo area is truncated to a single line. - - Examples in this manual indicate printed text with @samp{@print{}}, -irrespective of where that text goes. The value returned by evaluating -the form (here @code{bar}) follows on a separate line. - -@example -@group -(progn (print 'foo) (print 'bar)) - @print{} foo - @print{} bar - @result{} bar -@end group -@end example - -@node Error Messages -@subsection Error Messages -@cindex error message notation - - Some examples signal errors. This normally displays an error message -in the echo area. We show the error message on a line starting with -@samp{@error{}}. Note that @samp{@error{}} itself does not appear in -the echo area. - -@example -(+ 23 'x) -@error{} Wrong type argument: integer-or-marker-p, x -@end example - -@node Buffer Text Notation -@subsection Buffer Text Notation -@cindex buffer text notation - - Some examples show modifications to text in a buffer, with ``before'' -and ``after'' versions of the text. These examples show the contents of -the buffer in question between two lines of dashes containing the buffer -name. In addition, @samp{@point{}} indicates the location of point. -(The symbol for point, of course, is not part of the text in the buffer; -it indicates the place @emph{between} two characters where point is -located.) - -@example ----------- Buffer: foo ---------- -This is the @point{}contents of foo. ----------- Buffer: foo ---------- - -(insert "changed ") - @result{} nil ----------- Buffer: foo ---------- -This is the changed @point{}contents of foo. ----------- Buffer: foo ---------- -@end example - -@node Format of Descriptions -@subsection Format of Descriptions -@cindex description format - - Functions, variables, macros, commands, user options, and special -forms are described in this manual in a uniform format. The first -line of a description contains the name of the item followed by its -arguments, if any. -@ifinfo -The category---function, variable, or whatever---appears at the -beginning of the line. -@end ifinfo -@iftex -The category---function, variable, or whatever---is printed next to the -right margin. -@end iftex -The description follows on succeeding lines, sometimes with examples. - -@menu -* A Sample Function Description:: A description of an imaginary - function, @code{foo}. -* A Sample Variable Description:: A description of an imaginary - variable, - @code{electric-future-map}. -@end menu - -@node A Sample Function Description -@subsubsection A Sample Function Description -@cindex function descriptions -@cindex command descriptions -@cindex macro descriptions -@cindex special form descriptions - - In a function description, the name of the function being described -appears first. It is followed on the same line by a list of parameters. -The names used for the parameters are also used in the body of the -description. - - The appearance of the keyword @code{&optional} in the parameter list -indicates that the arguments for subsequent parameters may be omitted -(omitted parameters default to @code{nil}). Do not write -@code{&optional} when you call the function. - - The keyword @code{&rest} (which will always be followed by a single -parameter) indicates that any number of arguments can follow. The value -of the single following parameter will be a list of all these arguments. -Do not write @code{&rest} when you call the function. - - Here is a description of an imaginary function @code{foo}: - -@defun foo integer1 &optional integer2 &rest integers -The function @code{foo} subtracts @var{integer1} from @var{integer2}, -then adds all the rest of the arguments to the result. If @var{integer2} -is not supplied, then the number 19 is used by default. - -@example -(foo 1 5 3 9) - @result{} 16 -(foo 5) - @result{} 14 -@end example - -More generally, - -@example -(foo @var{w} @var{x} @var{y}@dots{}) -@equiv{} -(+ (- @var{x} @var{w}) @var{y}@dots{}) -@end example -@end defun - - Any parameter whose name contains the name of a type (e.g., -@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that -type. A plural of a type (such as @var{buffers}) often means a list of -objects of that type. Parameters named @var{object} may be of any type. -(@xref{Lisp Data Types}, for a list of Emacs object types.) -Parameters with other sorts of names (e.g., @var{new-file}) are -discussed specifically in the description of the function. In some -sections, features common to parameters of several functions are -described at the beginning. - - @xref{Lambda Expressions}, for a more complete description of optional -and rest arguments. - - Command, macro, and special form descriptions have the same format, -but the word `Function' is replaced by `Command', `Macro', or `Special -Form', respectively. Commands are simply functions that may be called -interactively; macros process their arguments differently from functions -(the arguments are not evaluated), but are presented the same way. - - Special form descriptions use a more complex notation to specify -optional and repeated parameters because they can break the argument -list down into separate arguments in more complicated ways. -@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that @var{optional-arg} is -optional and @samp{@var{repeated-args}@dots{}} stands for zero or more -arguments. Parentheses are used when several arguments are grouped into -additional levels of list structure. Here is an example: - -@defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} -This imaginary special form implements a loop that executes the -@var{body} forms and then increments the variable @var{var} on each -iteration. On the first iteration, the variable has the value -@var{from}; on subsequent iterations, it is incremented by 1 (or by -@var{inc} if that is given). The loop exits before executing @var{body} -if @var{var} equals @var{to}. Here is an example: - -@example -(count-loop (i 0 10) - (prin1 i) (princ " ") - (prin1 (aref vector i)) (terpri)) -@end example - -If @var{from} and @var{to} are omitted, then @var{var} is bound to -@code{nil} before the loop begins, and the loop exits if @var{var} is -non-@code{nil} at the beginning of an iteration. Here is an example: - -@example -(count-loop (done) - (if (pending) - (fixit) - (setq done t))) -@end example - -In this special form, the arguments @var{from} and @var{to} are -optional, but must both be present or both absent. If they are present, -@var{inc} may optionally be specified as well. These arguments are -grouped with the argument @var{var} into a list, to distinguish them -from @var{body}, which includes all remaining elements of the form. -@end defspec - -@node A Sample Variable Description -@subsubsection A Sample Variable Description -@cindex variable descriptions -@cindex option descriptions - - A @dfn{variable} is a name that can hold a value. Although any -variable can be set by the user, certain variables that exist -specifically so that users can change them are called @dfn{user -options}. Ordinary variables and user options are described using a -format like that for functions except that there are no arguments. - - Here is a description of the imaginary @code{electric-future-map} -variable.@refill - -@defvar electric-future-map -The value of this variable is a full keymap used by Electric Command -Future mode. The functions in this map allow you to edit commands you -have not yet thought about executing. -@end defvar - - User option descriptions have the same format, but `Variable' is -replaced by `User Option'. - -@node Acknowledgements -@section Acknowledgements - - This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte, -Richard M. Stallman and Chris Welty, the volunteers of the GNU manual -group, in an effort extending over several years. Robert J. Chassell -helped to review and edit the manual, with the support of the Defense -Advanced Research Projects Agency, ARPA Order 6082, arranged by Warren -A. Hunt, Jr. of Computational Logic, Inc. - - Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom, -Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence -R. Dodd, Peter Doornbosch, David A. Duff, Chris Eich, Beverly -Erlebacher, David Eckelkamp, Ralf Fassel, Eirik Fuller, Stephen Gildea, -Bob Glickstein, Eric Hanchrow, George Hartzell, Nathan Hess, Masayuki -Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe -Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland -McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson, -Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul -Rockwell, Per Starback, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, -Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty, -Dale Worley, Rusty Wright, and David D. Zuhn. diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi deleted file mode 100644 index 77ac4ecce75..00000000000 --- a/lispref/keymaps.texi +++ /dev/null @@ -1,1776 +0,0 @@ -@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. -* 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. -* Menu Keymaps:: A keymap can define a menu. -@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 events 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-n} 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. - - Each ordinary binding applies to events of a particular @dfn{event -type}, which is always a character or a symbol. @xref{Classifying -Events}. - - An ordinary element of a keymap is a cons cell of the form -@code{(@var{type} .@: @var{binding})}. This specifies one binding, for -events of type @var{type}. - -@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 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. More precisely, 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. - -@c ??? This should come after makr-sparse-keymap -@defun make-keymap &optional prompt -This function creates and returns a new full keymap (i.e., one -containing 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 that -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, which we call the -@dfn{parent keymap}. Such a keymap looks like this: - -@example -(keymap @var{bindings}@dots{} . @var{parent-keymap}) -@end example - -@noindent -The effect is that this keymap inherits all the bindings of -@var{parent-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{parent-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{parent-keymap}. - -The proper way to construct a keymap with a parent is to use -@code{set-keymap-parent}; if you have code that directly constructs a -keymap with a parent, please convert the program to use -@code{set-keymap-parent} instead. - -@defun keymap-parent keymap -This returns the parent keymap of @var{keymap}. If @var{keymap} -has no parent, @code{keymap-parent} returns @code{nil}. -@end defun - -@defun set-keymap-parent keymap parent -This sets the parent keymap of @var{keymap} to @var{parent}, and returns -@var{parent}. If @var{parent} is @code{nil}, this function gives -@var{keymap} no parent at all. - -If @var{keymap} has submaps (bindings for prefix keys), they too receive -new parent keymaps that reflect what @var{parent} specifies for those -prefix keys. -@end defun - -Here is an example showing how to make a keymap that inherits -from @code{text-mode-map}: - -@example -(let ((map (make-sparse-keymap))) - (set-keymap-parent map text-mode-map) - map) -@end example - -@node Prefix Keys -@section Prefix Keys -@cindex prefix key - - A @dfn{prefix key} has an associated keymap that 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 that 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 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} is used 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 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 -that has a name. The function also sets @var{symbol} as a variable, to -have the keymap as its value. It 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 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 -same local keymap, you can think of the keymap as local to the mode. A -change to the local keymap of a buffer (using @code{local-set-key}, for -example) is 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 that -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}, above. See @ref{Keymaps and -Minor Modes}, for more information about minor modes. -@end defvar - -@defvar overriding-local-map -If non-@code{nil}, this variable holds 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 - -@defvar overriding-terminal-local-map -If non-@code{nil}, this variable holds a keymap to use instead of -@code{overriding-local-map}, the buffer's local keymap and all the minor -mode keymaps. - -This variable is always local to the current terminal and cannot be -buffer-local. @xref{Multiple Displays}. It is used to implement -incremental search mode. -@end defvar - -@defvar overriding-local-map-menu-flag -If this variable is non-@code{nil}, the value of -@code{overriding-local-map} or @code{overriding-terminal-local-map} can -affect the display of the menu bar. The default value is @code{nil}, so -those map variables have no effect on the menu bar. - -Note that these two map variables do affect the execution of key -sequences entered using the menu bar, even if they do not affect the -menu bar display. So if a menu bar key sequence comes in, you should -clear the variables before looking up and executing that key sequence. -Modes that use the variables would typically do this anyway; normally -they respond to events that they do not handle by ``unreading'' them and -exiting. -@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 type 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. @xref{What Is a Function}. - -@item @var{array} -@cindex string in keymap -The array (either a string or a vector) is a keyboard macro. The events -used so far in the lookup form a complete key, and the array is its -binding. 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 @key{SPC}) 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 that 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 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 that 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 -you explicitly ask about them. (To do this, supply @code{t} as an -element of @var{key}; see @ref{Format of Keymaps}.) - -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} (above). - -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 -variable that 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 a binding in the global keymap, the change is effective in all -buffers (though it has no direct effect in buffers that shadow 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 (@pxref{Key Binding -Commands}). You can also use @code{define-key}, a more general -function; then you must specify explicitly the map to change. - -@cindex meta character key constants -@cindex control character key constants - In writing the key sequence to rebind, it is good 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}. You can also use this escape syntax in -vectors, as well as others that aren't allowed in strings; one example -is @samp{[?\C-\H-x home]}. @xref{Character Type}. - - The key definition and lookup functions accept an alternate syntax for -event types in a key sequence that is a vector: you can use a list -containing modifier names plus one base event (a character or function -key name). For example, @code{(control ?a)} is equivalent to -@code{?\C-a} and @code{(hyper control left)} is equivalent to -@code{C-H-left}. - - One advantage of using a list to represent the event type is that the -precise numeric codes for the modifier bits don't appear in compiled -files. - - 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 - - Here is an example that creates a sparse keymap and makes a number of -bindings in it: - -@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{keymap}, 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}. - - 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 -or - -@smallexample -(global-set-key [(control ?x) (control ?\\)] '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. - -@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 -that uses @var{key} 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 is also the value of -the variable @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 indirect keymap bindings. 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. - -If @var{prefix} is non-@code{nil}, it should be a prefix key; then the -listing includes only keys that start with @var{prefix}. - -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}. -@end deffn - -@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 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}). - -The individual bindings in the menu keymap should have item -strings; these strings become the items displayed in the menu. A -binding with an 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. - -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 may use @var{help-string} as extended documentation for -the menu item, available on request. - -As far as @code{define-key} is concerned, @var{string} and -@var{help-string} are 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. - -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 that -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 menu bar does not recalculate which items are enabled every time you -look at a menu. This is because the X toolkit requires the whole tree -of menus in advance. To force recalculation of the menu bar, call -@code{force-mode-line-update} (@pxref{Mode Line Format}). - -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 strings in a mouse menu, since that is redundant. - -Sometimes it is useful to make menu items that use the ``same'' command -but with different enable conditions. You can do this by defining alias -commands. Here's an example that makes two aliases for -@code{toggle-read-only} and gives them different enable conditions: - -@example -(defalias 'make-read-only 'toggle-read-only) -(put 'make-read-only 'menu-enable '(not buffer-read-only)) -(defalias 'make-writable 'toggle-read-only) -(put 'make-writable 'menu-enable 'buffer-read-only) -@end example - -When using aliases in menus, often it is useful to display the -equivalent key bindings for the ``real'' command name, not the aliases -(which typically don't have any key bindings except for the menu -itself). To request this, give the alias symbol a non-@code{nil} -@code{menu-alias} property. Thus, - -@example -(put 'make-read-only 'menu-alias t) -(put 'make-writable 'menu-alias t) -@end example - -@noindent -causes menu items for @code{make-read-only} and @code{make-writable} to -show the keyboard bindings for @code{toggle-read-only}. - -@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 that 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 an 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. (The variable @code{menu-prompt-more-char} specifies -which character is used for this; @key{SPC} is the default.) - -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. - -@ignore -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. We plan to change this; by -the time you read this manual, keyboard menus may explicitly name the -key for each alternative. -@end ignore - -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. - - The variable @code{overriding-local-map} is normally ignored when -determining the menu bar contents. That is, the menu bar is computed -from the keymaps that would be active if @code{overriding-local-map} -were @code{nil}. @xref{Active Keymaps}. - - 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 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: - -@example -@group -(modify-frame-parameters (selected-frame) - '((menu-bar-lines . 2))) -@end group - -@group -;; @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"))) -@end group - -@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 example - - 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 - -@defvar menu-bar-update-hook -This normal hook is run whenever the user clicks on the menu bar, before -displaying a submenu. You can use it to update submenus whose contents -should vary. -@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 event @var{after}. The argument @var{key} should -be of length one---a vector or string with just one element. - -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}. - -Here is how to insert an item called @samp{Work} in the @samp{Signals} -menu of Shell mode, after the item @code{break}: - -@example -(define-key-after - (lookup-key shell-mode-map [menu-bar signals]) - [work] '("Work" . work-command) 'break) -@end example - -Note that @var{key} is a sequence containing just one event type, but -@var{after} is just an event type (not a sequence). -@end defun diff --git a/lispref/lists.texi b/lispref/lists.texi deleted file mode 100644 index da9d57319ed..00000000000 --- a/lispref/lists.texi +++ /dev/null @@ -1,1416 +0,0 @@ -@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 that 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; see -@ref{Cons Cell Type}. @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. - -@cindex list structure - Because most cons cells are used as part of lists, the phrase -@dfn{list structure} has come to mean any structure made out of cons -cells. - - 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{Cons Cell Type}, for the read and print syntax of cons cells and -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 -that 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 2000 - -@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, -but the last one should be a list. All arguments except the last one -are copied, so none of them are altered. - -More generally, the final argument to @code{append} may be any Lisp -object. The final argument is not copied or converted; it becomes the -@sc{cdr} of the last cons cell in the new list. If the final argument -is itself a list, then its elements become in effect elements of the -result list. If the final element is not a list, the result is a -``dotted list'' since its final @sc{cdr} is not @code{nil} as required -in a true list. - -See @code{nconc} in @ref{Rearrangement}, for a way to join lists with no -copying. - -Here is an example of using @code{append}: - -@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 how @code{append} works 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 - -Here are some examples where the final argument is not a list: - -@example -(append '(x y) 'z) - @result{} (x y . z) -(append '(x y) [z]) - @result{} (x y . [z]) -@end example - -@noindent -The second example shows that when the final argument is a sequence but -not a list, the sequence's elements do not become elements of the -resulting list. Instead, the sequence becomes the final @sc{cdr}, like -any other non-list final argument. - -The @code{append} function also allows integers as arguments. It -converts them to strings of digits, making up the decimal print -representation of the integer, and then uses the strings instead of the -original integers. @strong{Don't use this feature; we plan to eliminate -it. If you already use this feature, change your programs now!} The -proper way to convert an integer to a decimal number in this way is with -@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}. When -used on a list, @code{setcar} 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} as the new @sc{cdr} of @var{cons}, -replacing its previous @sc{cdr}. It returns the value @var{object}. -@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 - -@need 4000 - 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. - -@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 - -@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 by reversing -the @sc{cdr}s in the cons cells forming the list. The cons cell that -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 - -@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{intersection} -@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 'b '(a b c b a)) - @result{} (b c b a) -@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 '(a b c (4))) - @result{} (a b c (4)) -@end group -@group -(delq 'a sample-list) - @result{} (b c (4)) -@end group -@group -sample-list - @result{} (a b c (4)) -@end group -@group -(delq 'c sample-list) - @result{} (a b (4)) -@end group -@group -sample-list - @result{} (a b (4)) -@end group -@end example - -Note that @code{(delq 'c sample-list)} modifies @code{sample-list} to -splice out the third element, but @code{(delq 'a 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{} (a c (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 - - See also the function @code{add-to-list}, in @ref{Setting Variables}, -for another way to add an element to a list stored in a variable. - -@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 rassoc 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{equal} to @var{value}. - -@code{rassoc} is like @code{assoc} 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{assoc}'', finding the key for a given value. -@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")) -@end group - (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") -@group -(eq (cdr (car (cdr needles-per-cluster))) - (cdr (car (cdr copy)))) - @result{} t -@end group -@end smallexample - - This example shows how @code{copy-alist} makes it possible to change -the associations of one copy without affecting the other: - -@smallexample -@group -(setcdr (assq 3 copy) '("Martian Vacuum Pine")) -(cdr (assq 3 needles-per-cluster)) - @result{} ("Pitch Pine") -@end group -@end smallexample -@end defun - - diff --git a/lispref/loading.texi b/lispref/loading.texi deleted file mode 100644 index 29c2480f1f5..00000000000 --- a/lispref/loading.texi +++ /dev/null @@ -1,680 +0,0 @@ -@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/loading -@node Loading, Byte Compilation, Macros, Top -@chapter Loading -@cindex loading -@cindex library -@cindex Lisp library - - Loading a file of Lisp code means bringing its contents into the Lisp -environment in the form of Lisp objects. Emacs finds and opens the -file, reads the text, evaluates each form, and then closes the file. - - The load functions evaluate all the expressions in a file just -as the @code{eval-current-buffer} function evaluates all the -expressions in a buffer. The difference is that the load functions -read and evaluate the text in the file as found on disk, not the text -in an Emacs buffer. - -@cindex top-level form - The loaded file must contain Lisp expressions, either as source code -or as byte-compiled code. Each form in the file is called a -@dfn{top-level form}. There is no special format for the forms in a -loadable file; any form in a file may equally well be typed directly -into a buffer and evaluated there. (Indeed, most code is tested this -way.) Most often, the forms are function definitions and variable -definitions. - - A file containing Lisp code is often called a @dfn{library}. Thus, -the ``Rmail library'' is a file containing code for Rmail mode. -Similarly, a ``Lisp library directory'' is a directory of files -containing Lisp code. - -@menu -* How Programs Do Loading:: The @code{load} function and others. -* Autoload:: Setting up a function to autoload. -* Repeated Loading:: Precautions about loading a file twice. -* Named Features:: Loading a library if it isn't already loaded. -* Unloading:: How to ``unload'' a library that was loaded. -* Hooks for Loading:: Providing code to be run when - particular libraries are loaded. -@end menu - -@node How Programs Do Loading -@section How Programs Do Loading - - Emacs Lisp has several interfaces for loading. For example, -@code{autoload} creates a placeholder object for a function in a file; -trying to call the autoloading function loads the file to get the -function's real definition (@pxref{Autoload}). @code{require} loads a -file if it isn't already loaded (@pxref{Named Features}). Ultimately, all -these facilities call the @code{load} function to do the work. - -@defun load filename &optional missing-ok nomessage nosuffix -This function finds and opens a file of Lisp code, evaluates all the -forms in it, and closes the file. - -To find the file, @code{load} first looks for a file named -@file{@var{filename}.elc}, that is, for a file whose name is -@var{filename} with @samp{.elc} appended. If such a file exists, it is -loaded. If there is no file by that name, then @code{load} looks for a -file named @file{@var{filename}.el}. If that file exists, it is loaded. -Finally, if neither of those names is found, @code{load} looks for a -file named @var{filename} with nothing appended, and loads it if it -exists. (The @code{load} function is not clever about looking at -@var{filename}. In the perverse case of a file named @file{foo.el.el}, -evaluation of @code{(load "foo.el")} will indeed find it.) - -If the optional argument @var{nosuffix} is non-@code{nil}, then the -suffixes @samp{.elc} and @samp{.el} are not tried. In this case, you -must specify the precise file name you want. - -If @var{filename} is a relative file name, such as @file{foo} or -@file{baz/foo.bar}, @code{load} searches for the file using the variable -@code{load-path}. It appends @var{filename} to each of the directories -listed in @code{load-path}, and loads the first file it finds whose name -matches. The current default directory is tried only if it is specified -in @code{load-path}, where @code{nil} stands for the default directory. -@code{load} tries all three possible suffixes in the first directory in -@code{load-path}, then all three suffixes in the second directory, and -so on. - -If you get a warning that @file{foo.elc} is older than @file{foo.el}, it -means you should consider recompiling @file{foo.el}. @xref{Byte -Compilation}. - -Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear -in the echo area during loading unless @var{nomessage} is -non-@code{nil}. - -@cindex load errors -Any unhandled errors while loading a file terminate loading. If the -load was done for the sake of @code{autoload}, any function definitions -made during the loading are undone. - -@kindex file-error -If @code{load} can't find the file to load, then normally it signals the -error @code{file-error} (with @samp{Cannot open load file -@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then -@code{load} just returns @code{nil}. - -You can use the variable @code{load-read-function} to specify a function -for @code{load} to use instead of @code{read} for reading expressions. -See below. - -@code{load} returns @code{t} if the file loads successfully. -@end defun - -@ignore -@deffn Command load-file filename -This function loads the file @var{filename}. If @var{filename} is an -absolute file name, then it is loaded. If it is relative, then the -current default directory is assumed. @code{load-path} is not used, and -suffixes are not appended. Use this function if you wish to specify -the file to be loaded exactly. -@end deffn - -@deffn Command load-library library -This function loads the library named @var{library}. A library is -nothing more than a file that may be loaded as described earlier. This -function is identical to @code{load}, save that it reads a file name -interactively with completion. -@end deffn -@end ignore - -@defopt load-path -@cindex @code{EMACSLOADPATH} environment variable -The value of this variable is a list of directories to search when -loading files with @code{load}. Each element is a string (which must be -a directory name) or @code{nil} (which stands for the current working -directory). The value of @code{load-path} is initialized from the -environment variable @code{EMACSLOADPATH}, if that exists; otherwise its -default value is specified in @file{emacs/src/paths.h} when Emacs is -built. - -The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH}; -@samp{:} (or @samp{;}, according to the operating system) separates -directory names, and @samp{.} is used for the current default directory. -Here is an example of how to set your @code{EMACSLOADPATH} variable from -a @code{csh} @file{.login} file: - -@c This overfull hbox is OK. --rjc 16mar92 -@smallexample -setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp -@end smallexample - -Here is how to set it using @code{sh}: - -@smallexample -export EMACSLOADPATH -EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp -@end smallexample - -Here is an example of code you can place in a @file{.emacs} file to add -several directories to the front of your default @code{load-path}: - -@smallexample -@group -(setq load-path - (append (list nil "/user/bil/emacs" - "/usr/local/lisplib" - "~/emacs") - load-path)) -@end group -@end smallexample - -@c Wordy to rid us of an overfull hbox. --rjc 15mar92 -@noindent -In this example, the path searches the current working directory first, -followed then by the @file{/user/bil/emacs} directory, the -@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory, -which are then followed by the standard directories for Lisp code. - -The command line options @samp{-l} or @samp{-load} specify a Lisp -library to load as part of Emacs startup. Since this file might be in -the current directory, Emacs 18 temporarily adds the current directory -to the front of @code{load-path} so the file can be found there. Newer -Emacs versions also find such files in the current directory, but -without altering @code{load-path}. - -Dumping Emacs uses a special value of @code{load-path}. If the value of -@code{load-path} at the end of dumping is unchanged (that is, still the -same special value), the dumped Emacs switches to the ordinary -@code{load-path} value when it starts up, as described above. But if -@code{load-path} has any other value at the end of dumping, that value -is used for execution of the dumped Emacs also. - -Therefore, if you want to change @code{load-path} temporarily for -loading a few libraries in @file{site-init.el} or @file{site-load.el}, -you should bind @code{load-path} locally with @code{let} around the -calls to @code{load}. -@end defopt - - The default value of @code{load-path}, when running an Emacs which has -been installed on the system, looks like this: - -@smallexample -("/usr/local/share/emacs/@var{version}/site-lisp" - "/usr/local/share/emacs/site-lisp" - "/usr/local/share/emacs/@var{version}/lisp") -@end smallexample - - The last of these three directories is where the Lisp files of Emacs -itself are installed; the first two are for additional Lisp packages -installed at your site. The first directory is for locally installed -packages that belong with a particular Emacs version; the second is for -locally installed packages that can be used with any installed Emacs -version. - - There are several reasons why a Lisp package that works well in one -Emacs version can cause trouble in another. Sometimes packages need -updating for incompatible changes in Emacs; sometimes they depend on -undocumented internal Emacs data that can change without notice; -sometimes a newer Emacs version incorporates a version of the package, -and should be used only with that version. - - If you run Emacs from the directory where it was built---that is, an -executable that has not been formally installed---then @code{load-path} -normally contains two additional directories. These are the @code{lisp} -and @code{site-lisp} subdirectories of the main build directory. (Both -are represented as absolute file names.) - -@defvar load-in-progress -This variable is non-@code{nil} if Emacs is in the process of loading a -file, and it is @code{nil} otherwise. -@end defvar - -@defvar load-read-function -This variable specifies an alternate expression-reading function for -@code{load} and @code{eval-region} to use instead of @code{read}. -The function should accept one argument, just as @code{read} does. - -Normally, the variable's value is @code{nil}, which means those -functions should use @code{read}. -@end defvar - - To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}. - -@node Autoload -@section Autoload -@cindex autoload - - The @dfn{autoload} facility allows you to make a function or macro -known in Lisp, but put off loading the file that defines it. The first -call to the function automatically reads the proper file to install the -real definition and other associated code, then runs the real definition -as if it had been loaded all along. - - There are two ways to set up an autoloaded function: by calling -@code{autoload}, and by writing a special ``magic'' comment in the -source before the real definition. @code{autoload} is the low-level -primitive for autoloading; any Lisp program can call @code{autoload} at -any time. Magic comments do nothing on their own; they serve as a guide -for the command @code{update-file-autoloads}, which constructs calls to -@code{autoload} and arranges to execute them when Emacs is built. Magic -comments are the most convenient way to make a function autoload, but -only for packages installed along with Emacs. - -@defun autoload function filename &optional docstring interactive type -This function defines the function (or macro) named @var{function} so as -to load automatically from @var{filename}. The string @var{filename} -specifies the file to load to get the real definition of @var{function}. - -The argument @var{docstring} is the documentation string for the -function. Normally, this is the identical to the documentation string -in the function definition itself. Specifying the documentation string -in the call to @code{autoload} makes it possible to look at the -documentation without loading the function's real definition. - -If @var{interactive} is non-@code{nil}, then the function can be called -interactively. This lets completion in @kbd{M-x} work without loading -the function's real definition. The complete interactive specification -need not be given here; it's not needed unless the user actually calls -@var{function}, and when that happens, it's time to load the real -definition. - -You can autoload macros and keymaps as well as ordinary functions. -Specify @var{type} as @code{macro} if @var{function} is really a macro. -Specify @var{type} as @code{keymap} if @var{function} is really a -keymap. Various parts of Emacs need to know this information without -loading the real definition. - -An autoloaded keymap loads automatically during key lookup when a prefix -key's binding is the symbol @var{function}. Autoloading does not occur -for other kinds of access to the keymap. In particular, it does not -happen when a Lisp program gets the keymap from the value of a variable -and calls @code{define-key}; not even if the variable name is the same -symbol @var{function}. - -@cindex function cell in autoload -If @var{function} already has a non-void function definition that is not -an autoload object, @code{autoload} does nothing and returns @code{nil}. -If the function cell of @var{function} is void, or is already an autoload -object, then it is defined as an autoload object like this: - -@example -(autoload @var{filename} @var{docstring} @var{interactive} @var{type}) -@end example - -For example, - -@example -@group -(symbol-function 'run-prolog) - @result{} (autoload "prolog" 169681 t nil) -@end group -@end example - -@noindent -In this case, @code{"prolog"} is the name of the file to load, 169681 -refers to the documentation string in the @file{emacs/etc/DOC} file -(@pxref{Documentation Basics}), @code{t} means the function is -interactive, and @code{nil} that it is not a macro or a keymap. -@end defun - -@cindex autoload errors - The autoloaded file usually contains other definitions and may require -or provide one or more features. If the file is not completely loaded -(due to an error in the evaluation of its contents), any function -definitions or @code{provide} calls that occurred during the load are -undone. This is to ensure that the next attempt to call any function -autoloading from this file will try again to load the file. If not for -this, then some of the functions in the file might appear defined, but -they might fail to work properly for the lack of certain subroutines -defined later in the file and not loaded successfully. - - If the autoloaded file fails to define the desired Lisp function or -macro, then an error is signaled with data @code{"Autoloading failed to -define function @var{function-name}"}. - -@findex update-file-autoloads -@findex update-directory-autoloads - A magic autoload comment looks like @samp{;;;###autoload}, on a line -by itself, just before the real definition of the function in its -autoloadable source file. The command @kbd{M-x update-file-autoloads} -writes a corresponding @code{autoload} call into @file{loaddefs.el}. -Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}. -@kbd{M-x update-directory-autoloads} is even more powerful; it updates -autoloads for all files in the current directory. - - The same magic comment can copy any kind of form into -@file{loaddefs.el}. If the form following the magic comment is not a -function definition, it is copied verbatim. You can also use a magic -comment to execute a form at build time @emph{without} executing it when -the file itself is loaded. To do this, write the form @emph{on the same -line} as the magic comment. Since it is in a comment, it does nothing -when you load the source file; but @code{update-file-autoloads} copies -it to @file{loaddefs.el}, where it is executed while building Emacs. - - The following example shows how @code{doctor} is prepared for -autoloading with a magic comment: - -@smallexample -;;;###autoload -(defun doctor () - "Switch to *doctor* buffer and start giving psychotherapy." - (interactive) - (switch-to-buffer "*doctor*") - (doctor-mode)) -@end smallexample - -@noindent -Here's what that produces in @file{loaddefs.el}: - -@smallexample -(autoload 'doctor "doctor" - "\ -Switch to *doctor* buffer and start giving psychotherapy." - t) -@end smallexample - -@noindent -The backslash and newline immediately following the double-quote are a -convention used only in the preloaded Lisp files such as -@file{loaddefs.el}; they tell @code{make-docfile} to put the -documentation string in the @file{etc/DOC} file. @xref{Building Emacs}. - -@node Repeated Loading -@section Repeated Loading -@cindex repeated loading - - You may load one file more than once in an Emacs session. For -example, after you have rewritten and reinstalled a function definition -by editing it in a buffer, you may wish to return to the original -version; you can do this by reloading the file it came from. - - When you load or reload files, bear in mind that the @code{load} and -@code{load-library} functions automatically load a byte-compiled file -rather than a non-compiled file of similar name. If you rewrite a file -that you intend to save and reinstall, remember to byte-compile it if -necessary; otherwise you may find yourself inadvertently reloading the -older, byte-compiled file instead of your newer, non-compiled file! - - When writing the forms in a Lisp library file, keep in mind that the -file might be loaded more than once. For example, the choice of -@code{defvar} vs.@: @code{defconst} for defining a variable depends on -whether it is desirable to reinitialize the variable if the library is -reloaded: @code{defconst} does so, and @code{defvar} does not. -(@xref{Defining Variables}.) - - The simplest way to add an element to an alist is like this: - -@example -(setq minor-mode-alist - (cons '(leif-mode " Leif") minor-mode-alist)) -@end example - -@noindent -But this would add multiple elements if the library is reloaded. -To avoid the problem, write this: - -@example -(or (assq 'leif-mode minor-mode-alist) - (setq minor-mode-alist - (cons '(leif-mode " Leif") minor-mode-alist))) -@end example - - To add an element to a list just once, use @code{add-to-list} -(@pxref{Setting Variables}). - - Occasionally you will want to test explicitly whether a library has -already been loaded. Here's one way to test, in a library, whether it -has been loaded before: - -@example -(defvar foo-was-loaded) - -(if (not (boundp 'foo-was-loaded)) - @var{execute-first-time-only}) - -(setq foo-was-loaded t) -@end example - -@noindent -If the library uses @code{provide} to provide a named feature, you can -use @code{featurep} to test whether the library has been loaded. -@ifinfo -@xref{Named Features}. -@end ifinfo - -@node Named Features -@section Features -@cindex features -@cindex requiring features -@cindex providing features - - @code{provide} and @code{require} are an alternative to -@code{autoload} for loading files automatically. They work in terms of -named @dfn{features}. Autoloading is triggered by calling a specific -function, but a feature is loaded the first time another program asks -for it by name. - - A feature name is a symbol that stands for a collection of functions, -variables, etc. The file that defines them should @dfn{provide} the -feature. Another program that uses them may ensure they are defined by -@dfn{requiring} the feature. This loads the file of definitions if it -hasn't been loaded already. - - To require the presence of a feature, call @code{require} with the -feature name as argument. @code{require} looks in the global variable -@code{features} to see whether the desired feature has been provided -already. If not, it loads the feature from the appropriate file. This -file should call @code{provide} at the top level to add the feature to -@code{features}; if it fails to do so, @code{require} signals an error. -@cindex load error with require - - Features are normally named after the files that provide them, so that -@code{require} need not be given the file name. - - For example, in @file{emacs/lisp/prolog.el}, -the definition for @code{run-prolog} includes the following code: - -@smallexample -(defun run-prolog () - "Run an inferior Prolog process, with I/O via buffer *prolog*." - (interactive) - (require 'comint) - (switch-to-buffer (make-comint "prolog" prolog-program-name)) - (inferior-prolog-mode)) -@end smallexample - -@noindent -The expression @code{(require 'comint)} loads the file @file{comint.el} -if it has not yet been loaded. This ensures that @code{make-comint} is -defined. - -The @file{comint.el} file contains the following top-level expression: - -@smallexample -(provide 'comint) -@end smallexample - -@noindent -This adds @code{comint} to the global @code{features} list, so that -@code{(require 'comint)} will henceforth know that nothing needs to be -done. - -@cindex byte-compiling @code{require} - When @code{require} is used at top level in a file, it takes effect -when you byte-compile that file (@pxref{Byte Compilation}) as well as -when you load it. This is in case the required package contains macros -that the byte compiler must know about. - - Although top-level calls to @code{require} are evaluated during -byte compilation, @code{provide} calls are not. Therefore, you can -ensure that a file of definitions is loaded before it is byte-compiled -by including a @code{provide} followed by a @code{require} for the same -feature, as in the following example. - -@smallexample -@group -(provide 'my-feature) ; @r{Ignored by byte compiler,} - ; @r{evaluated by @code{load}.} -(require 'my-feature) ; @r{Evaluated by byte compiler.} -@end group -@end smallexample - -@noindent -The compiler ignores the @code{provide}, then processes the -@code{require} by loading the file in question. Loading the file does -execute the @code{provide} call, so the subsequent @code{require} call -does nothing while loading. - -@defun provide feature -This function announces that @var{feature} is now loaded, or being -loaded, into the current Emacs session. This means that the facilities -associated with @var{feature} are or will be available for other Lisp -programs. - -The direct effect of calling @code{provide} is to add @var{feature} to -the front of the list @code{features} if it is not already in the list. -The argument @var{feature} must be a symbol. @code{provide} returns -@var{feature}. - -@smallexample -features - @result{} (bar bish) - -(provide 'foo) - @result{} foo -features - @result{} (foo bar bish) -@end smallexample - -When a file is loaded to satisfy an autoload, and it stops due to an -error in the evaluating its contents, any function definitions or -@code{provide} calls that occurred during the load are undone. -@xref{Autoload}. -@end defun - -@defun require feature &optional filename -This function checks whether @var{feature} is present in the current -Emacs session (using @code{(featurep @var{feature})}; see below). If it -is not, then @code{require} loads @var{filename} with @code{load}. If -@var{filename} is not supplied, then the name of the symbol -@var{feature} is used as the file name to load. - -If loading the file fails to provide @var{feature}, @code{require} -signals an error, @samp{Required feature @var{feature} was not -provided}. -@end defun - -@defun featurep feature -This function returns @code{t} if @var{feature} has been provided in the -current Emacs session (i.e., @var{feature} is a member of -@code{features}.) -@end defun - -@defvar features -The value of this variable is a list of symbols that are the features -loaded in the current Emacs session. Each symbol was put in this list -with a call to @code{provide}. The order of the elements in the -@code{features} list is not significant. -@end defvar - -@node Unloading -@section Unloading -@cindex unloading - -@c Emacs 19 feature - You can discard the functions and variables loaded by a library to -reclaim memory for other Lisp objects. To do this, use the function -@code{unload-feature}: - -@deffn Command unload-feature feature &optional force -This command unloads the library that provided feature @var{feature}. -It undefines all functions, macros, and variables defined in that -library with @code{defconst}, @code{defvar}, @code{defun}, -@code{defmacro}, @code{defsubst} and @code{defalias}. It then restores -any autoloads formerly associated with those symbols. (Loading -saves these in the @code{autoload} property of the symbol.) - -Ordinarily, @code{unload-feature} refuses to unload a library on which -other loaded libraries depend. (A library @var{a} depends on library -@var{b} if @var{a} contains a @code{require} for @var{b}.) If the -optional argument @var{force} is non-@code{nil}, dependencies are -ignored and you can unload any library. -@end deffn - - The @code{unload-feature} function is written in Lisp; its actions are -based on the variable @code{load-history}. - -@defvar load-history -This variable's value is an alist connecting library names with the -names of functions and variables they define, the features they provide, -and the features they require. - -Each element is a list and describes one library. The @sc{car} of the -list is the name of the library, as a string. The rest of the list is -composed of these kinds of objects: - -@itemize @bullet -@item -Symbols that were defined by this library. -@item -Lists of the form @code{(require . @var{feature})} indicating -features that were required. -@item -Lists of the form @code{(provide . @var{feature})} indicating -features that were provided. -@end itemize - -The value of @code{load-history} may have one element whose @sc{car} is -@code{nil}. This element describes definitions made with -@code{eval-buffer} on a buffer that is not visiting a file. -@end defvar - - The command @code{eval-region} updates @code{load-history}, but does so -by adding the symbols defined to the element for the file being visited, -rather than replacing that element. - -@node Hooks for Loading -@section Hooks for Loading -@cindex loading hooks -@cindex hooks for loading - -You can ask for code to be executed if and when a particular library is -loaded, by calling @code{eval-after-load}. - -@defun eval-after-load library form -This function arranges to evaluate @var{form} at the end of loading the -library @var{library}, if and when @var{library} is loaded. If -@var{library} is already loaded, it evaluates @var{form} right away. - -The library name @var{library} must exactly match the argument of -@code{load}. To get the proper results when an installed library is -found by searching @code{load-path}, you should not include any -directory names in @var{library}. - -An error in @var{form} does not undo the load, but does prevent -execution of the rest of @var{form}. -@end defun - -In general, well-designed Lisp programs should not use this feature. -The clean and modular ways to interact with a Lisp library are (1) -examine and set the library's variables (those which are meant for -outside use), and (2) call the library's functions. If you wish to -do (1), you can do it immediately---there is no need to wait for when -the library is loaded. To do (2), you must load the library (preferably -with @code{require}). - -But it is ok to use @code{eval-after-load} in your personal customizations -if you don't feel they must meet the design standards of programs to be -released. - -@defvar after-load-alist -An alist of expressions to evaluate if and when particular libraries are -loaded. Each element looks like this: - -@example -(@var{filename} @var{forms}@dots{}) -@end example - -The function @code{load} checks @code{after-load-alist} in order to -implement @code{eval-after-load}. -@end defvar - -@c Emacs 19 feature diff --git a/lispref/locals.texi b/lispref/locals.texi deleted file mode 100644 index 86e6750248c..00000000000 --- a/lispref/locals.texi +++ /dev/null @@ -1,150 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/locals -@node Standard Buffer-Local Variables, Standard Keymaps, Standard Errors, Top -@appendix Buffer-Local Variables -@c The title "Standard Buffer-Local Variables" is too long for -@c smallbook. --rjc 30mar92 - - The table below lists the general-purpose Emacs variables that are -automatically local (when set) in each buffer. Many Lisp packages -define such variables for their internal use; we don't list them here. - -@table @code -@item abbrev-mode -@pxref{Abbrevs} - -@item auto-fill-function -@pxref{Auto Filling} - -@item buffer-auto-save-file-name -@pxref{Auto-Saving} - -@item buffer-backed-up -@pxref{Backup Files} - -@item buffer-display-table -@pxref{Display Tables} - -@item buffer-file-format -@pxref{Format Conversion} - -@item buffer-file-name -@pxref{Buffer File Name} - -@item buffer-file-number -@pxref{Buffer File Name} - -@item buffer-file-truename -@pxref{Buffer File Name} - -@item buffer-file-type -@pxref{Files and MS-DOS} - -@item buffer-invisibility-spec -@pxref{Invisible Text} - -@item buffer-offer-save -@pxref{Saving Buffers} - -@item buffer-read-only -@pxref{Read Only Buffers} - -@item buffer-saved-size -@pxref{Point} - -@item buffer-undo-list -@pxref{Undo} - -@item cache-long-line-scans -@pxref{Text Lines} - -@item case-fold-search -@pxref{Searching and Case} - -@item ctl-arrow -@pxref{Usual Display} - -@item comment-column -@pxref{Comments,,, emacs, The GNU Emacs Manual} - -@item default-directory -@pxref{System Environment} - -@item defun-prompt-regexp -@pxref{List Motion} - -@item fill-column -@pxref{Auto Filling} - -@item goal-column -@pxref{Moving Point,,, emacs, The GNU Emacs Manual} - -@item left-margin -@pxref{Indentation} - -@item local-abbrev-table -@pxref{Abbrevs} - -@item local-write-file-hooks -@pxref{Saving Buffers} - -@item major-mode -@pxref{Mode Help} - -@item mark-active -@pxref{The Mark} - -@item mark-ring -@pxref{The Mark} - -@item minor-modes -@pxref{Minor Modes} - -@item mode-line-buffer-identification -@pxref{Mode Line Variables} - -@item mode-line-format -@pxref{Mode Line Data} - -@item mode-line-modified -@pxref{Mode Line Variables} - -@item mode-line-process -@pxref{Mode Line Variables} - -@item mode-name -@pxref{Mode Line Variables} - -@item overwrite-mode -@pxref{Insertion} - -@item paragraph-separate -@pxref{Standard Regexps} - -@item paragraph-start -@pxref{Standard Regexps} - -@item point-before-scroll -Used for communication between mouse commands and scroll-bar commands. - -@item require-final-newline -@pxref{Insertion} - -@item selective-display -@pxref{Selective Display} - -@item selective-display-ellipses -@pxref{Selective Display} - -@item tab-width -@pxref{Usual Display} - -@item truncate-lines -@pxref{Truncation} - -@item vc-mode -@pxref{Mode Line Variables} -@end table diff --git a/lispref/macros.texi b/lispref/macros.texi deleted file mode 100644 index 22a07f14dbe..00000000000 --- a/lispref/macros.texi +++ /dev/null @@ -1,579 +0,0 @@ -@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 files that define -them (@pxref{Named Features}). To avoid loading the macro definition files -when someone @emph{runs} the compiled program, write -@code{eval-when-compile} around the @code{require} calls (@pxref{Eval -During Compile}). - -@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 functionals 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) -@findex ` - - Macros often need to construct large list structures from a mixture of -constants and nonconstant parts. To make this easier, use the macro -@samp{`} (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 -'(a list of (+ 2 3) elements) - @result{} (a list of (+ 2 3) elements) -@end group -@end example - -@findex , @r{(with Backquote)} -The special marker @samp{,} inside of the argument to backquote -indicates a value that isn't constant. Backquote evaluates the -argument of @samp{,} 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 ,@@ @r{(with Backquote)} -@cindex splicing (with backquote) -You can also @dfn{splice} an evaluated value into the resulting list, -using the special marker @samp{,@@}. 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 @samp{`} 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 - -@quotation -Before Emacs version 19.29, @samp{`} used a different syntax which -required an extra level of parentheses around the entire backquote -construct. Likewise, each @samp{,} or @samp{,@@} substition required an -extra level of parentheses surrounding both the @samp{,} or @samp{,@@} -and the following expression. The old syntax required whitespace -between the @samp{`}, @samp{,} or @samp{,@@} and the following -expression. - -This syntax is still accepted, but no longer recommended except for -compatibility with old Emacs versions. -@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.) - -Here's an equivalent definition simplified through use of backquote: - -@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))." - `(let ((,var ,init)) - (while (<= ,var ,final) - ,@@body - (inc ,var)))) -@end group -@end smallexample - -Both forms of this definition (with backquote and without) suffer 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: - -@smallexample -@group -(let ((max 0)) - (for x from 0 to 10 do - (let ((this (frob x))) - (if (< max this) - (setq max this))))) -@end group -@end smallexample - -@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 already 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} that 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. diff --git a/lispref/maps.texi b/lispref/maps.texi deleted file mode 100644 index 77dc80001b9..00000000000 --- a/lispref/maps.texi +++ /dev/null @@ -1,190 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/maps -@node Standard Keymaps, Standard Hooks, Standard Buffer-Local Variables, Top -@appendix Standard Keymaps - -The following symbols are used as the names for various keymaps. -Some of these exist when Emacs is first started, others are -loaded only when their respective mode is used. This is not -an exhaustive list. - -Almost all of these maps are used as local maps. Indeed, of the modes -that presently exist, only Vip mode and Terminal mode ever change the -global keymap. - -@table @code -@item Buffer-menu-mode-map -@vindex Buffer-menu-mode-map -A full keymap used by Buffer Menu mode. - -@item c-mode-map -@vindex c-mode-map -A sparse keymap used by C mode. - -@item command-history-map -@vindex command-history-map -A full keymap used by Command History mode. - -@item ctl-x-4-map -@vindex ctl-x-4-map -A sparse keymap for subcommands of the prefix @kbd{C-x 4}. - -@item ctl-x-5-map -@vindex ctl-x-5-map -A sparse keymap for subcommands of the prefix @kbd{C-x 5}. - -@item ctl-x-map -@vindex ctl-x-map -A full keymap for @kbd{C-x} commands. - -@item debugger-mode-map -@vindex debugger-mode-map -A full keymap used by Debugger mode. - -@item dired-mode-map -@vindex dired-mode-map -A full keymap for @code{dired-mode} buffers. - -@item edit-abbrevs-map -@vindex edit-abbrevs-map -A sparse keymap used in @code{edit-abbrevs}. - -@item edit-tab-stops-map -@vindex edit-tab-stops-map -A sparse keymap used in @code{edit-tab-stops}. - -@item electric-buffer-menu-mode-map -@vindex electric-buffer-menu-mode-map -A full keymap used by Electric Buffer Menu mode. - -@item electric-history-map -@vindex electric-history-map -A full keymap used by Electric Command History mode. - -@item emacs-lisp-mode-map -@vindex emacs-lisp-mode-map -A sparse keymap used by Emacs Lisp mode. - -@item facemenu-menu -@vindex facemenu-menu -The keymap that displays the Text Properties menu. - -@item facemenu-background-menu -@vindex facemenu-background-menu -The keymap that displays the Background Color submenu of the Text -Properties menu. - -@item facemenu-face-menu -@vindex facemenu-face-menu -The keymap that displays the Face submenu of the Text Properties menu. - -@item facemenu-foreground-menu -@vindex facemenu-foreground-menu -The keymap that displays the Foreground Color submenu of the Text -Properties menu. - -@item facemenu-indentation-menu -@vindex facemenu-indentation-menu -The keymap that displays the Indentation submenu of the Text Properties menu. - -@item facemenu-justification-menu -@vindex facemenu-justification-menu -The keymap that displays the Justification submenu of the Text -Properties menu. - -@item facemenu-special-menu -@vindex facemenu-special-menu -The keymap that displays the Special Props submenu of the Text -Properties menu. - -@item function-key-map -@vindex function-key-map -The keymap for translating keypad and function keys.@* -If there are none, then it contains an empty sparse keymap. - -@item fundamental-mode-map -@vindex fundamental-mode-map -The local keymap for Fundamental mode.@* -It is empty and should not be changed. - -@item Helper-help-map -@vindex Helper-help-map -A full keymap used by the help utility package.@* -It has the same keymap in its value cell and in its function -cell. - -@item Info-edit-map -@vindex Info-edit-map -A sparse keymap used by the @kbd{e} command of Info. - -@item Info-mode-map -@vindex Info-mode-map -A sparse keymap containing Info commands. - -@item isearch-mode-map -@vindex isearch-mode-map -A keymap that defines the characters you can type within incremental -search. - -@item key-translation-map -@vindex key-translation-map -A keymap for translating keys. This one overrides ordinary key -bindings, unlike @code{function-key-map}. - -@item lisp-interaction-mode-map -@vindex lisp-interaction-mode-map -A sparse keymap used by Lisp mode. - -@item lisp-mode-map -@vindex lisp-mode-map -A sparse keymap used by Lisp mode. - -@item menu-bar-edit-menu -@vindex menu-bar-edit-menu -The keymap which displays the Edit menu in the menu bar. - -@item menu-bar-files-menu -@vindex menu-bar-files-menu -The keymap which displays the Files menu in the menu bar. - -@item menu-bar-help-menu -@vindex menu-bar-help-menu -The keymap which displays the Help menu in the menu bar. - -@item menu-bar-search-menu -@vindex menu-bar-search-menu -The keymap which displays the Search menu in the menu bar. - -@item menu-bar-tools-menu -@vindex menu-bar-tools-menu -The keymap which displays the Tools menu in the menu bar. - -@item mode-specific-map -@vindex mode-specific-map -The keymap for characters following @kbd{C-c}. Note, this is in the -global map. 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 occur-mode-map -@vindex occur-mode-map -A local keymap used by Occur mode. - -@item query-replace-map -@vindex query-replace-map -A local keymap used for responses in @code{query-replace} and related -commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}. The functions -that use this map do not support prefix keys; they look up one event at a -time. - -@item text-mode-map -@vindex text-mode-map -A sparse keymap used by Text mode. - -@item view-mode-map -@vindex view-mode-map -A full keymap used by View mode. -@end table diff --git a/lispref/markers.texi b/lispref/markers.texi deleted file mode 100644 index 8c41fa17f17..00000000000 --- a/lispref/markers.texi +++ /dev/null @@ -1,579 +0,0 @@ -@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/markers -@node Markers, Text, Positions, Top -@chapter Markers -@cindex markers - - A @dfn{marker} is a Lisp object used to specify a position in a buffer -relative to the surrounding text. A marker changes its offset from the -beginning of the buffer automatically whenever text is inserted or -deleted, so that it stays with the two characters on either side of it. - -@menu -* Overview of Markers:: The components of a marker, and how it relocates. -* Predicates on Markers:: Testing whether an object is a marker. -* Creating Markers:: Making empty markers or markers at certain places. -* Information from Markers:: Finding the marker's buffer or character position. -* Changing Markers:: Moving the marker to a new buffer or position. -* The Mark:: How ``the mark'' is implemented with a marker. -* The Region:: How to access ``the region''. -@end menu - -@node Overview of Markers -@section Overview of Markers - - A marker specifies a buffer and a position in that buffer. The marker -can be used to represent a position in the functions that require one, -just as an integer could be used. @xref{Positions}, for a complete -description of positions. - - A marker has two attributes: the marker position, and the marker -buffer. The marker position is an integer that is equivalent (at a -given time) to the marker as a position in that buffer. But the -marker's position value can change often during the life of the marker. -Insertion and deletion of text in the buffer relocate the marker. The -idea is that a marker positioned between two characters remains between -those two characters despite insertion and deletion elsewhere in the -buffer. Relocation changes the integer equivalent of the marker. - -@cindex marker relocation - Deleting text around a marker's position leaves the marker between the -characters immediately before and after the deleted text. Inserting -text at the position of a marker normally leaves the marker in front of -the new text---unless it is inserted with @code{insert-before-markers} -(@pxref{Insertion}). - -@cindex marker garbage collection - Insertion and deletion in a buffer must check all the markers and -relocate them if necessary. This slows processing in a buffer with a -large number of markers. For this reason, it is a good idea to make a -marker point nowhere if you are sure you don't need it any more. -Unreferenced markers are garbage collected eventually, but until then -will continue to use time if they do point somewhere. - -@cindex markers as numbers - Because it is common to perform arithmetic operations on a marker -position, most of the arithmetic operations (including @code{+} and -@code{-}) accept markers as arguments. In such cases, the marker -stands for its current position. - -Here are examples of creating markers, setting markers, and moving point -to markers: - -@example -@group -;; @r{Make a new marker that initially does not point anywhere:} -(setq m1 (make-marker)) - @result{} #<marker in no buffer> -@end group - -@group -;; @r{Set @code{m1} to point between the 99th and 100th characters} -;; @r{in the current buffer:} -(set-marker m1 100) - @result{} #<marker at 100 in markers.texi> -@end group - -@group -;; @r{Now insert one character at the beginning of the buffer:} -(goto-char (point-min)) - @result{} 1 -(insert "Q") - @result{} nil -@end group - -@group -;; @r{@code{m1} is updated appropriately.} -m1 - @result{} #<marker at 101 in markers.texi> -@end group - -@group -;; @r{Two markers that point to the same position} -;; @r{are not @code{eq}, but they are @code{equal}.} -(setq m2 (copy-marker m1)) - @result{} #<marker at 101 in markers.texi> -(eq m1 m2) - @result{} nil -(equal m1 m2) - @result{} t -@end group - -@group -;; @r{When you are finished using a marker, make it point nowhere.} -(set-marker m1 nil) - @result{} #<marker in no buffer> -@end group -@end example - -@node Predicates on Markers -@section Predicates on Markers - - You can test an object to see whether it is a marker, or whether it is -either an integer or a marker. The latter test is useful in connection -with the arithmetic functions that work with both markers and integers. - -@defun markerp object -This function returns @code{t} if @var{object} is a marker, @code{nil} -otherwise. Note that integers are not markers, even though many -functions will accept either a marker or an integer. -@end defun - -@defun integer-or-marker-p object -This function returns @code{t} if @var{object} is an integer or a marker, -@code{nil} otherwise. -@end defun - -@defun number-or-marker-p object -This function returns @code{t} if @var{object} is a number (either kind) -or a marker, @code{nil} otherwise. -@end defun - -@node Creating Markers -@section Functions That Create Markers - - When you create a new marker, you can make it point nowhere, or point -to the present position of point, or to the beginning or end of the -accessible portion of the buffer, or to the same place as another given -marker. - -@defun make-marker -This functions returns a newly created marker that does not point -anywhere. - -@example -@group -(make-marker) - @result{} #<marker in no buffer> -@end group -@end example -@end defun - -@defun point-marker -This function returns a new marker that points to the present position -of point in the current buffer. @xref{Point}. For an example, see -@code{copy-marker}, below. -@end defun - -@defun point-min-marker -This function returns a new marker that points to the beginning of the -accessible portion of the buffer. This will be the beginning of the -buffer unless narrowing is in effect. @xref{Narrowing}. -@end defun - -@defun point-max-marker -@cindex end of buffer marker -This function returns a new marker that points to the end of the -accessible portion of the buffer. This will be the end of the buffer -unless narrowing is in effect. @xref{Narrowing}. - -Here are examples of this function and @code{point-min-marker}, shown in -a buffer containing a version of the source file for the text of this -chapter. - -@example -@group -(point-min-marker) - @result{} #<marker at 1 in markers.texi> -(point-max-marker) - @result{} #<marker at 15573 in markers.texi> -@end group - -@group -(narrow-to-region 100 200) - @result{} nil -@end group -@group -(point-min-marker) - @result{} #<marker at 100 in markers.texi> -@end group -@group -(point-max-marker) - @result{} #<marker at 200 in markers.texi> -@end group -@end example -@end defun - -@defun copy-marker marker-or-integer -If passed a marker as its argument, @code{copy-marker} returns a -new marker that points to the same place and the same buffer as does -@var{marker-or-integer}. If passed an integer as its argument, -@code{copy-marker} returns a new marker that points to position -@var{marker-or-integer} in the current buffer. - -If passed an integer argument less than 1, @code{copy-marker} returns a -new marker that points to the beginning of the current buffer. If -passed an integer argument greater than the length of the buffer, -@code{copy-marker} returns a new marker that points to the end of the -buffer. - -An error is signaled if @var{marker} is neither a marker nor an -integer. - -@example -@group -(setq p (point-marker)) - @result{} #<marker at 2139 in markers.texi> -@end group - -@group -(setq q (copy-marker p)) - @result{} #<marker at 2139 in markers.texi> -@end group - -@group -(eq p q) - @result{} nil -@end group - -@group -(equal p q) - @result{} t -@end group - -@group -(copy-marker 0) - @result{} #<marker at 1 in markers.texi> -@end group - -@group -(copy-marker 20000) - @result{} #<marker at 7572 in markers.texi> -@end group -@end example -@end defun - -@node Information from Markers -@section Information from Markers - - This section describes the functions for accessing the components of a -marker object. - -@defun marker-position marker -This function returns the position that @var{marker} points to, or -@code{nil} if it points nowhere. -@end defun - -@defun marker-buffer marker -This function returns the buffer that @var{marker} points into, or -@code{nil} if it points nowhere. - -@example -@group -(setq m (make-marker)) - @result{} #<marker in no buffer> -@end group -@group -(marker-position m) - @result{} nil -@end group -@group -(marker-buffer m) - @result{} nil -@end group - -@group -(set-marker m 3770 (current-buffer)) - @result{} #<marker at 3770 in markers.texi> -@end group -@group -(marker-buffer m) - @result{} #<buffer markers.texi> -@end group -@group -(marker-position m) - @result{} 3770 -@end group -@end example -@end defun - - Two distinct markers are considered @code{equal} (even though not -@code{eq}) to each other if they have the same position and buffer, or -if they both point nowhere. - -@node Changing Markers -@section Changing Marker Positions - - This section describes how to change the position of an existing -marker. When you do this, be sure you know whether the marker is used -outside of your program, and, if so, what effects will result from -moving it---otherwise, confusing things may happen in other parts of -Emacs. - -@defun set-marker marker position &optional buffer -This function moves @var{marker} to @var{position} -in @var{buffer}. If @var{buffer} is not provided, it defaults to -the current buffer. - -If @var{position} is less than 1, @code{set-marker} moves @var{marker} -to the beginning of the buffer. If @var{position} is greater than the -size of the buffer, @code{set-marker} moves marker to the end of the -buffer. If @var{position} is @code{nil} or a marker that points -nowhere, then @var{marker} is set to point nowhere. - -The value returned is @var{marker}. - -@example -@group -(setq m (point-marker)) - @result{} #<marker at 4714 in markers.texi> -@end group -@group -(set-marker m 55) - @result{} #<marker at 55 in markers.texi> -@end group -@group -(setq b (get-buffer "foo")) - @result{} #<buffer foo> -@end group -@group -(set-marker m 0 b) - @result{} #<marker at 1 in foo> -@end group -@end example -@end defun - -@defun move-marker marker position &optional buffer -This is another name for @code{set-marker}. -@end defun - -@node The Mark -@section The Mark -@cindex mark, the -@cindex mark ring - - One special marker in each buffer is designated @dfn{the mark}. It -records a position for the user for the sake of commands such as -@kbd{C-w} and @kbd{C-x @key{TAB}}. Lisp programs should set the mark -only to values that have a potential use to the user, and never for -their own internal purposes. For example, the @code{replace-regexp} -command sets the mark to the value of point before doing any -replacements, because this enables the user to move back there -conveniently after the replace is finished. - - Many commands are designed so that when called interactively they -operate on the text between point and the mark. If you are writing such -a command, don't examine the mark directly; instead, use -@code{interactive} with the @samp{r} specification. This provides the -values of point and the mark as arguments to the command in an -interactive call, but permits other Lisp programs to specify arguments -explicitly. @xref{Interactive Codes}. - - Each buffer has its own value of the mark that is independent of the -value of the mark in other buffers. When a buffer is created, the mark -exists but does not point anywhere. We consider this state as ``the -absence of a mark in that buffer.'' - - Once the mark ``exists'' in a buffer, it normally never ceases to -exist. However, it may become @dfn{inactive}, if Transient Mark mode is -enabled. The variable @code{mark-active}, which is always local in all -buffers, indicates whether the mark is active: non-@code{nil} means yes. -A command can request deactivation of the mark upon return to the editor -command loop by setting @code{deactivate-mark} to a non-@code{nil} value -(but this causes deactivation only if Transient Mark mode is enabled). - - The main motivation for using Transient Mark mode is that this mode -also enables highlighting of the region when the mark is active. -@xref{Display}. - - In addition to the mark, each buffer has a @dfn{mark ring} which is a -list of markers containing previous values of the mark. When editing -commands change the mark, they should normally save the old value of the -mark on the mark ring. The variable @code{mark-ring-max} specifies the -maximum number of entries in the mark ring; once the list becomes this -long, adding a new element deletes the last element. - -@defun mark &optional force -@cindex current buffer mark -This function returns the current buffer's mark position as an integer. - -If the mark is inactive, @code{mark} normally signals an error. -However, if @var{force} is non-@code{nil}, then @code{mark} returns the -mark position anyway---or @code{nil}, if the mark is not yet set for -this buffer. -@end defun - -@defun mark-marker -This function returns the current buffer's mark. This is the very marker -that records the mark location inside Emacs, not a copy. Therefore, -changing this marker's position will directly affect the position of the mark. -Don't do it unless that is the effect you want. - -@example -@group -(setq m (mark-marker)) - @result{} #<marker at 3420 in markers.texi> -@end group -@group -(set-marker m 100) - @result{} #<marker at 100 in markers.texi> -@end group -@group -(mark-marker) - @result{} #<marker at 100 in markers.texi> -@end group -@end example - -Like any marker, this marker can be set to point at any buffer you like. -We don't recommend that you make it point at any buffer other than the -one of which it is the mark. If you do, it will yield perfectly -consistent, but rather odd, results. -@end defun - -@ignore -@deffn Command set-mark-command jump -If @var{jump} is @code{nil}, this command sets the mark to the value -of point and pushes the previous value of the mark on the mark ring. The -message @samp{Mark set} is also displayed in the echo area. - -If @var{jump} is not @code{nil}, this command sets point to the value -of the mark, and sets the mark to the previous saved mark value, which -is popped off the mark ring. - -This function is @emph{only} intended for interactive use. -@end deffn -@end ignore - -@defun set-mark position -This function sets the mark to @var{position}, and activates the mark. -The old value of the mark is @emph{not} pushed onto the mark ring. - -@strong{Please note:} Use this function only if you want the user to -see that the mark has moved, and you want the previous mark position to -be lost. Normally, when a new mark is set, the old one should go on the -@code{mark-ring}. For this reason, most applications should use -@code{push-mark} and @code{pop-mark}, not @code{set-mark}. - -Novice Emacs Lisp programmers often try to use the mark for the wrong -purposes. The mark saves a location for the user's convenience. An -editing command should not alter the mark unless altering the mark is -part of the user-level functionality of the command. (And, in that -case, this effect should be documented.) To remember a location for -internal use in the Lisp program, store it in a Lisp variable. For -example: - -@example -@group -(let ((beg (point))) - (forward-line 1) - (delete-region beg (point))). -@end group -@end example -@end defun - -@c for interactive use only -@ignore -@deffn Command exchange-point-and-mark -This function exchanges the positions of point and the mark. -It is intended for interactive use. -@end deffn -@end ignore - -@defun push-mark &optional position nomsg activate -This function sets the current buffer's mark to @var{position}, and -pushes a copy of the previous mark onto @code{mark-ring}. If -@var{position} is @code{nil}, then the value of point is used. -@code{push-mark} returns @code{nil}. - -The function @code{push-mark} normally @emph{does not} activate the -mark. To do that, specify @code{t} for the argument @var{activate}. - -A @samp{Mark set} message is displayed unless @var{nomsg} is -non-@code{nil}. -@end defun - -@defun pop-mark -This function pops off the top element of @code{mark-ring} and makes -that mark become the buffer's actual mark. This does not move point in -the buffer, and it does nothing if @code{mark-ring} is empty. It -deactivates the mark. - -The return value is not meaningful. -@end defun - -@defopt transient-mark-mode -@cindex Transient Mark mode -This variable if non-@code{nil} enables Transient Mark mode, in which -every buffer-modifying primitive sets @code{deactivate-mark}. The -consequence of this is that commands that modify the buffer normally -make the mark inactive. -@end defopt - -@defvar deactivate-mark -If an editor command sets this variable non-@code{nil}, then the editor -command loop deactivates the mark after the command returns, but only if -Transient Mark mode is enabled. -@end defvar - -@defun deactivate-mark -This function deactivates the mark, but only if Transient Mark mode -is enabled. -@end defun - -@defvar mark-active -The mark is active when this variable is non-@code{nil}. This variable -is always local in each buffer. -@end defvar - -@defvar activate-mark-hook -@defvarx deactivate-mark-hook -These normal hooks are run, respectively, when the mark becomes active -and when it becomes inactive. The hook @code{activate-mark-hook} is also -run at the end of a command if the mark is active and the region may -have changed. -@end defvar - -@defvar mark-ring -The value of this buffer-local variable is the list of saved former -marks of the current buffer, most recent first. - -@example -@group -mark-ring -@result{} (#<marker at 11050 in markers.texi> - #<marker at 10832 in markers.texi> - @dots{}) -@end group -@end example -@end defvar - -@defopt mark-ring-max -The value of this variable is the maximum size of @code{mark-ring}. If -more marks than this are pushed onto the @code{mark-ring}, -@code{push-mark} discards an old mark when it adds a new one. -@end defopt - -@node The Region -@section The Region -@cindex region, the - - The text between point and the mark is known as @dfn{the region}. -Various functions operate on text delimited by point and the mark, but -only those functions specifically related to the region itself are -described here. - -@defun region-beginning -This function returns the position of the beginning of the region (as -an integer). This is the position of either point or the mark, -whichever is smaller. - -If the mark does not point anywhere, an error is signaled. -@end defun - -@defun region-end -This function returns the position of the end of the region (as an -integer). This is the position of either point or the mark, whichever is -larger. - -If the mark does not point anywhere, an error is signaled. -@end defun - - Few programs need to use the @code{region-beginning} and -@code{region-end} functions. A command designed to operate on a region -should normally use @code{interactive} with the @samp{r} specification -to find the beginning and end of the region. This lets other Lisp -programs specify the bounds explicitly as arguments. (@xref{Interactive -Codes}.) diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi deleted file mode 100644 index 9ff436a8fc1..00000000000 --- a/lispref/minibuf.texi +++ /dev/null @@ -1,1452 +0,0 @@ -@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/minibuf -@node Minibuffers, Command Loop, Read and Print, Top -@chapter Minibuffers -@cindex arguments, reading -@cindex complex arguments -@cindex minibuffer - - A @dfn{minibuffer} is a special buffer that Emacs commands use to read -arguments more complicated than the single numeric prefix argument. -These arguments include file names, buffer names, and command names (as -in @kbd{M-x}). The minibuffer is displayed on the bottom line of the -screen, in the same place as the echo area, but only while it is in -use for reading an argument. - -@menu -* Intro to Minibuffers:: Basic information about minibuffers. -* Text from Minibuffer:: How to read a straight text string. -* Object from Minibuffer:: How to read a Lisp object or expression. -* Minibuffer History:: Recording previous minibuffer inputs - so the user can reuse them. -* Completion:: How to invoke and customize completion. -* Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. -* Minibuffer Misc:: Various customization hooks and variables. -@end menu - -@node Intro to Minibuffers -@section Introduction to Minibuffers - - In most ways, a minibuffer is a normal Emacs buffer. Most operations -@emph{within} a buffer, such as editing commands, work normally in a -minibuffer. However, many operations for managing buffers do not apply -to minibuffers. The name of a minibuffer always has the form @w{@samp{ -*Minibuf-@var{number}}}, and it cannot be changed. Minibuffers are -displayed only in special windows used only for minibuffers; these -windows always appear at the bottom of a frame. (Sometime frames have -no minibuffer window, and sometimes a special kind of frame contains -nothing but a minibuffer window; see @ref{Minibuffers and Frames}.) - - The minibuffer's window is normally a single line. You can resize it -temporarily with the window sizing commands; it reverts to its normal -size when the minibuffer is exited. You can resize it permanently by -using the window sizing commands in the frame's other window, when the -minibuffer is not active. If the frame contains just a minibuffer, you -can change the minibuffer's size by changing the frame's size. - - If a command uses a minibuffer while there is an active minibuffer, -this is called a @dfn{recursive minibuffer}. The first minibuffer is -named @w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by -incrementing the number at the end of the name. (The names begin with a -space so that they won't show up in normal buffer lists.) Of several -recursive minibuffers, the innermost (or most recently entered) is the -active minibuffer. We usually call this ``the'' minibuffer. You can -permit or forbid recursive minibuffers by setting the variable -@code{enable-recursive-minibuffers} or by putting properties of that -name on command symbols (@pxref{Minibuffer Misc}). - - Like other buffers, a minibuffer may use any of several local keymaps -(@pxref{Keymaps}); these contain various exit commands and in some cases -completion commands (@pxref{Completion}). - -@itemize @bullet -@item -@code{minibuffer-local-map} is for ordinary input (no completion). - -@item -@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits -just like @key{RET}. This is used mainly for Mocklisp compatibility. - -@item -@code{minibuffer-local-completion-map} is for permissive completion. - -@item -@code{minibuffer-local-must-match-map} is for strict completion and -for cautious completion. -@end itemize - -@node Text from Minibuffer -@section Reading Text Strings with the Minibuffer - - Most often, the minibuffer is used to read text as a string. It can -also be used to read a Lisp object in textual form. The most basic -primitive for minibuffer input is @code{read-from-minibuffer}; it can do -either one. - - In most cases, you should not call minibuffer input functions in the -middle of a Lisp function. Instead, do all minibuffer input as part of -reading the arguments for a command, in the @code{interactive} spec. -@xref{Defining Commands}. - -@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist -This function is the most general way to get input through the -minibuffer. By default, it accepts arbitrary text and returns it as a -string; however, if @var{read} is non-@code{nil}, then it uses -@code{read} to convert the text into a Lisp object (@pxref{Input -Functions}). - -The first thing this function does is to activate a minibuffer and -display it with @var{prompt-string} as the prompt. This value must be a -string. - -Then, if @var{initial-contents} is a string, @code{read-from-minibuffer} -inserts it into the minibuffer, leaving point at the end. The -minibuffer appears with this text as its contents. - -@c Emacs 19 feature -The value of @var{initial-contents} may also be a cons cell of the form -@code{(@var{string} . @var{position})}. This means to insert -@var{string} in the minibuffer but put point @var{position} characters -from the beginning, rather than at the end. - -If @var{keymap} is non-@code{nil}, that keymap is the local keymap to -use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the -value of @code{minibuffer-local-map} is used as the keymap. Specifying -a keymap is the most important way to customize the minibuffer for -various applications such as completion. - -The argument @var{hist} specifies which history list variable to use -for saving the input and for history commands used in the minibuffer. -It defaults to @code{minibuffer-history}. @xref{Minibuffer History}. - -When the user types a command to exit the minibuffer, -@code{read-from-minibuffer} uses the text in the minibuffer to produce -its return value. Normally it simply makes a string containing that -text. However, if @var{read} is non-@code{nil}, -@code{read-from-minibuffer} reads the text and returns the resulting -Lisp object, unevaluated. (@xref{Input Functions}, for information -about reading.) -@end defun - -@defun read-string prompt &optional initial -This function reads a string from the minibuffer and returns it. The -arguments @var{prompt} and @var{initial} are used as in -@code{read-from-minibuffer}. The keymap used is -@code{minibuffer-local-map}. - -This is a simplified interface to the -@code{read-from-minibuffer} function: - -@smallexample -@group -(read-string @var{prompt} @var{initial}) -@equiv{} -(read-from-minibuffer @var{prompt} @var{initial} nil nil nil) -@end group -@end smallexample -@end defun - -@defvar minibuffer-local-map -This is the default local keymap for reading from the minibuffer. By -default, it makes the following bindings: - -@table @asis -@item @key{LFD} -@code{exit-minibuffer} - -@item @key{RET} -@code{exit-minibuffer} - -@item @kbd{C-g} -@code{abort-recursive-edit} - -@item @kbd{M-n} -@code{next-history-element} - -@item @kbd{M-p} -@code{previous-history-element} - -@item @kbd{M-r} -@code{next-matching-history-element} - -@item @kbd{M-s} -@code{previous-matching-history-element} -@end table -@end defvar - -@c In version 18, initial is required -@c Emacs 19 feature -@defun read-no-blanks-input prompt &optional initial -This function reads a string from the minibuffer, but does not allow -whitespace characters as part of the input: instead, those characters -terminate the input. The arguments @var{prompt} and @var{initial} are -used as in @code{read-from-minibuffer}. - -This is a simplified interface to the @code{read-from-minibuffer} -function, and passes the value of the @code{minibuffer-local-ns-map} -keymap as the @var{keymap} argument for that function. Since the keymap -@code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is} -possible to put a space into the string, by quoting it. - -@smallexample -@group -(read-no-blanks-input @var{prompt} @var{initial}) -@equiv{} -(read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map) -@end group -@end smallexample -@end defun - -@defvar minibuffer-local-ns-map -This built-in variable is the keymap used as the minibuffer local keymap -in the function @code{read-no-blanks-input}. By default, it makes the -following bindings, in addition to those of @code{minibuffer-local-map}: - -@table @asis -@item @key{SPC} -@cindex @key{SPC} in minibuffer -@code{exit-minibuffer} - -@item @key{TAB} -@cindex @key{TAB} in minibuffer -@code{exit-minibuffer} - -@item @kbd{?} -@cindex @kbd{?} in minibuffer -@code{self-insert-and-exit} -@end table -@end defvar - -@node Object from Minibuffer -@section Reading Lisp Objects with the Minibuffer - - This section describes functions for reading Lisp objects with the -minibuffer. - -@defun read-minibuffer prompt &optional initial -This function reads a Lisp object in the minibuffer and returns it, -without evaluating it. The arguments @var{prompt} and @var{initial} are -used as in @code{read-from-minibuffer}. - -This is a simplified interface to the -@code{read-from-minibuffer} function: - -@smallexample -@group -(read-minibuffer @var{prompt} @var{initial}) -@equiv{} -(read-from-minibuffer @var{prompt} @var{initial} nil t) -@end group -@end smallexample - -Here is an example in which we supply the string @code{"(testing)"} as -initial input: - -@smallexample -@group -(read-minibuffer - "Enter an expression: " (format "%s" '(testing))) - -;; @r{Here is how the minibuffer is displayed:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Enter an expression: (testing)@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -The user can type @key{RET} immediately to use the initial input as a -default, or can edit the input. -@end defun - -@defun eval-minibuffer prompt &optional initial -This function reads a Lisp expression in the minibuffer, evaluates it, -then returns the result. The arguments @var{prompt} and @var{initial} -are used as in @code{read-from-minibuffer}. - -This function simply evaluates the result of a call to -@code{read-minibuffer}: - -@smallexample -@group -(eval-minibuffer @var{prompt} @var{initial}) -@equiv{} -(eval (read-minibuffer @var{prompt} @var{initial})) -@end group -@end smallexample -@end defun - -@defun edit-and-eval-command prompt form -This function reads a Lisp expression in the minibuffer, and then -evaluates it. The difference between this command and -@code{eval-minibuffer} is that here the initial @var{form} is not -optional and it is treated as a Lisp object to be converted to printed -representation rather than as a string of text. It is printed with -@code{prin1}, so if it is a string, double-quote characters (@samp{"}) -appear in the initial text. @xref{Output Functions}. - -The first thing @code{edit-and-eval-command} does is to activate the -minibuffer with @var{prompt} as the prompt. Then it inserts the printed -representation of @var{form} in the minibuffer, and lets the user edit. -When the user exits the minibuffer, the edited text is read with -@code{read} and then evaluated. The resulting value becomes the value -of @code{edit-and-eval-command}. - -In the following example, we offer the user an expression with initial -text which is a valid form already: - -@smallexample -@group -(edit-and-eval-command "Please edit: " '(forward-word 1)) - -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Please edit: (forward-word 1)@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -Typing @key{RET} right away would exit the minibuffer and evaluate the -expression, thus moving point forward one word. -@code{edit-and-eval-command} returns @code{nil} in this example. -@end defun - -@node Minibuffer History -@section Minibuffer History -@cindex minibuffer history -@cindex history list - -A @dfn{minibuffer history list} records previous minibuffer inputs so -the user can reuse them conveniently. A history list is actually a -symbol, not a list; it is a variable whose value is a list of strings -(previous inputs), most recent first. - -There are many separate history lists, used for different kinds of -inputs. It's the Lisp programmer's job to specify the right history -list for each use of the minibuffer. - -The basic minibuffer input functions @code{read-from-minibuffer} and -@code{completing-read} both accept an optional argument named @var{hist} -which is how you specify the history list. Here are the possible -values: - -@table @asis -@item @var{variable} -Use @var{variable} (a symbol) as the history list. - -@item (@var{variable} . @var{startpos}) -Use @var{variable} (a symbol) as the history list, and assume that the -initial history position is @var{startpos} (an integer, counting from -zero which specifies the most recent element of the history). - -If you specify @var{startpos}, then you should also specify that element -of the history as the initial minibuffer contents, for consistency. -@end table - -If you don't specify @var{hist}, then the default history list -@code{minibuffer-history} is used. For other standard history lists, -see below. You can also create your own history list variable; just -initialize it to @code{nil} before the first use. - -Both @code{read-from-minibuffer} and @code{completing-read} add new -elements to the history list automatically, and provide commands to -allow the user to reuse items on the list. The only thing your program -needs to do to use a history list is to initialize it and to pass its -name to the input functions when you wish. But it is safe to modify the -list by hand when the minibuffer input functions are not using it. - -@defvar minibuffer-history -The default history list for minibuffer history input. -@end defvar - -@defvar query-replace-history -A history list for arguments to @code{query-replace} (and similar -arguments to other commands). -@end defvar - -@defvar file-name-history -A history list for file name arguments. -@end defvar - -@defvar regexp-history -A history list for regular expression arguments. -@end defvar - -@defvar extended-command-history -A history list for arguments that are names of extended commands. -@end defvar - -@defvar shell-command-history -A history list for arguments that are shell commands. -@end defvar - -@defvar read-expression-history -A history list for arguments that are Lisp expressions to evaluate. -@end defvar - -@node Completion -@section Completion -@cindex completion - - @dfn{Completion} is a feature that fills in the rest of a name -starting from an abbreviation for it. Completion works by comparing the -user's input against a list of valid names and determining how much of -the name is determined uniquely by what the user has typed. For -example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then -type the first few letters of the name of the buffer to which you wish -to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs -extends the name as far as it can. - - Standard Emacs commands offer completion for names of symbols, files, -buffers, and processes; with the functions in this section, you can -implement completion for other kinds of names. - - The @code{try-completion} function is the basic primitive for -completion: it returns the longest determined completion of a given -initial string, with a given set of strings to match against. - - The function @code{completing-read} provides a higher-level interface -for completion. A call to @code{completing-read} specifies how to -determine the list of valid names. The function then activates the -minibuffer with a local keymap that binds a few keys to commands useful -for completion. Other functions provide convenient simple interfaces -for reading certain kinds of names with completion. - -@menu -* Basic Completion:: Low-level functions for completing strings. - (These are too low level to use the minibuffer.) -* Minibuffer Completion:: Invoking the minibuffer with completion. -* Completion Commands:: Minibuffer commands that do completion. -* High-Level Completion:: Convenient special cases of completion - (reading buffer name, file name, etc.) -* Reading File Names:: Using completion to read file names. -* Programmed Completion:: Finding the completions for a given file name. -@end menu - -@node Basic Completion -@subsection Basic Completion Functions - - The two functions @code{try-completion} and @code{all-completions} -have nothing in themselves to do with minibuffers. We describe them in -this chapter so as to keep them near the higher-level completion -features that do use the minibuffer. - -@defun try-completion string collection &optional predicate -This function returns the longest common substring of all possible -completions of @var{string} in @var{collection}. The value of -@var{collection} must be an alist, an obarray, or a function that -implements a virtual set of strings (see below). - -Completion compares @var{string} against each of the permissible -completions specified by @var{collection}; if the beginning of the -permissible completion equals @var{string}, it matches. If no permissible -completions match, @code{try-completion} returns @code{nil}. If only -one permissible completion matches, and the match is exact, then -@code{try-completion} returns @code{t}. Otherwise, the value is the -longest initial sequence common to all the permissible completions that -match. - -If @var{collection} is an alist (@pxref{Association Lists}), the -@sc{car}s of the alist elements form the set of permissible completions. - -@cindex obarray in completion -If @var{collection} is an obarray (@pxref{Creating Symbols}), the names -of all symbols in the obarray form the set of permissible completions. The -global variable @code{obarray} holds an obarray containing the names of -all interned Lisp symbols. - -Note that the only valid way to make a new obarray is to create it -empty and then add symbols to it one by one using @code{intern}. -Also, you cannot intern a given symbol in more than one obarray. - -If the argument @var{predicate} is non-@code{nil}, then it must be a -function of one argument. It is used to test each possible match, and -the match is accepted only if @var{predicate} returns non-@code{nil}. -The argument given to @var{predicate} is either a cons cell from the alist -(the @sc{car} of which is a string) or else it is a symbol (@emph{not} a -symbol name) from the obarray. - -You can also use a symbol that is a function as @var{collection}. Then -the function is solely responsible for performing completion; -@code{try-completion} returns whatever this function returns. The -function is called with three arguments: @var{string}, @var{predicate} -and @code{nil}. (The reason for the third argument is so that the same -function can be used in @code{all-completions} and do the appropriate -thing in either case.) @xref{Programmed Completion}. - -In the first of the following examples, the string @samp{foo} is -matched by three of the alist @sc{car}s. All of the matches begin with -the characters @samp{fooba}, so that is the result. In the second -example, there is only one possible match, and it is exact, so the value -is @code{t}. - -@smallexample -@group -(try-completion - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))) - @result{} "fooba" -@end group - -@group -(try-completion "foo" '(("barfoo" 2) ("foo" 3))) - @result{} t -@end group -@end smallexample - -In the following example, numerous symbols begin with the characters -@samp{forw}, and all of them begin with the word @samp{forward}. In -most of the symbols, this is followed with a @samp{-}, but not in all, -so no more than @samp{forward} can be completed. - -@smallexample -@group -(try-completion "forw" obarray) - @result{} "forward" -@end group -@end smallexample - -Finally, in the following example, only two of the three possible -matches pass the predicate @code{test} (the string @samp{foobaz} is -too short). Both of those begin with the string @samp{foobar}. - -@smallexample -@group -(defun test (s) - (> (length (car s)) 6)) - @result{} test -@end group -@group -(try-completion - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - 'test) - @result{} "foobar" -@end group -@end smallexample -@end defun - -@defun all-completions string collection &optional predicate nospace -This function returns a list of all possible completions of -@var{string}. The parameters to this function are the same as to -@code{try-completion}. - -If @var{collection} is a function, it is called with three arguments: -@var{string}, @var{predicate} and @code{t}; then @code{all-completions} -returns whatever the function returns. @xref{Programmed Completion}. - -If @var{nospace} is non-@code{nil}, completions that start with a space -are ignored unless @var{string} also starts with a space. - -Here is an example, using the function @code{test} shown in the -example for @code{try-completion}: - -@smallexample -@group -(defun test (s) - (> (length (car s)) 6)) - @result{} test -@end group - -@group -(all-completions - "foo" - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - 'test) - @result{} ("foobar1" "foobar2") -@end group -@end smallexample -@end defun - -@defvar completion-ignore-case -If the value of this variable is -non-@code{nil}, Emacs does not consider case significant in completion. -@end defvar - -@node Minibuffer Completion -@subsection Completion and the Minibuffer - - This section describes the basic interface for reading from the -minibuffer with completion. - -@defun completing-read prompt collection &optional predicate require-match initial hist -This function reads a string in the minibuffer, assisting the user by -providing completion. It activates the minibuffer with prompt -@var{prompt}, which must be a string. If @var{initial} is -non-@code{nil}, @code{completing-read} inserts it into the minibuffer as -part of the input. Then it allows the user to edit the input, providing -several commands to attempt completion. - -The actual completion is done by passing @var{collection} and -@var{predicate} to the function @code{try-completion}. This happens in -certain commands bound in the local keymaps used for completion. - -If @var{require-match} is @code{t}, the usual minibuffer exit commands -won't exit unless the input completes to an element of @var{collection}. -If @var{require-match} is neither @code{nil} nor @code{t}, then the exit -commands won't exit unless the input typed is itself an element of -@var{collection}. If @var{require-match} is @code{nil}, the exit -commands work regardless of the input in the minibuffer. - -The user can exit with null input by typing @key{RET} with an empty -minibuffer. Then @code{completing-read} returns @code{""}. This is how -the user requests whatever default the command uses for the value being -read. The user can return using @key{RET} in this way regardless of the -value of @var{require-match}, and regardless of whether the empty string -is included in @var{collection}. - -The function @code{completing-read} works by calling -@code{read-minibuffer}. It uses @code{minibuffer-local-completion-map} -as the keymap if @var{require-match} is @code{nil}, and uses -@code{minibuffer-local-must-match-map} if @var{require-match} is -non-@code{nil}. @xref{Completion Commands}. - -The argument @var{hist} specifies which history list variable to use for -saving the input and for minibuffer history commands. It defaults to -@code{minibuffer-history}. @xref{Minibuffer History}. - -Completion ignores case when comparing the input against the possible -matches, if the built-in variable @code{completion-ignore-case} is -non-@code{nil}. @xref{Basic Completion}. - -Here's an example of using @code{completing-read}: - -@smallexample -@group -(completing-read - "Complete a foo: " - '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) - nil t "fo") -@end group - -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} - ----------- Buffer: Minibuffer ---------- -Complete a foo: fo@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end smallexample - -@noindent -If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}}, -@code{completing-read} returns @code{barfoo}. - -The @code{completing-read} function binds three variables to pass -information to the commands that actually do completion. These -variables are @code{minibuffer-completion-table}, -@code{minibuffer-completion-predicate} and -@code{minibuffer-completion-confirm}. For more information about them, -see @ref{Completion Commands}. -@end defun - -@node Completion Commands -@subsection Minibuffer Commands That Do Completion - - This section describes the keymaps, commands and user options used in -the minibuffer to do completion. - -@defvar minibuffer-local-completion-map -@code{completing-read} uses this value as the local keymap when an -exact match of one of the completions is not required. By default, this -keymap makes the following bindings: - -@table @asis -@item @kbd{?} -@code{minibuffer-completion-help} - -@item @key{SPC} -@code{minibuffer-complete-word} - -@item @key{TAB} -@code{minibuffer-complete} -@end table - -@noindent -with other characters bound as in @code{minibuffer-local-map} -(@pxref{Text from Minibuffer}). -@end defvar - -@defvar minibuffer-local-must-match-map -@code{completing-read} uses this value as the local keymap when an -exact match of one of the completions is required. Therefore, no keys -are bound to @code{exit-minibuffer}, the command that exits the -minibuffer unconditionally. By default, this keymap makes the following -bindings: - -@table @asis -@item @kbd{?} -@code{minibuffer-completion-help} - -@item @key{SPC} -@code{minibuffer-complete-word} - -@item @key{TAB} -@code{minibuffer-complete} - -@item @key{LFD} -@code{minibuffer-complete-and-exit} - -@item @key{RET} -@code{minibuffer-complete-and-exit} -@end table - -@noindent -with other characters bound as in @code{minibuffer-local-map}. -@end defvar - -@defvar minibuffer-completion-table -The value of this variable is the alist or obarray used for completion -in the minibuffer. This is the global variable that contains what -@code{completing-read} passes to @code{try-completion}. It is used by -minibuffer completion commands such as @code{minibuffer-complete-word}. -@end defvar - -@defvar minibuffer-completion-predicate -This variable's value is the predicate that @code{completing-read} -passes to @code{try-completion}. The variable is also used by the other -minibuffer completion functions. -@end defvar - -@deffn Command minibuffer-complete-word -This function completes the minibuffer contents by at most a single -word. Even if the minibuffer contents have only one completion, -@code{minibuffer-complete-word} does not add any characters beyond the -first character that is not a word constituent. @xref{Syntax Tables}. -@end deffn - -@deffn Command minibuffer-complete -This function completes the minibuffer contents as far as possible. -@end deffn - -@deffn Command minibuffer-complete-and-exit -This function completes the minibuffer contents, and exits if -confirmation is not required, i.e., if -@code{minibuffer-completion-confirm} is @code{nil}. If confirmation -@emph{is} required, it is given by repeating this command -immediately---the command is programmed to work without confirmation -when run twice in succession. -@end deffn - -@defvar minibuffer-completion-confirm -When the value of this variable is non-@code{nil}, Emacs asks for -confirmation of a completion before exiting the minibuffer. The -function @code{minibuffer-complete-and-exit} checks the value of this -variable before it exits. -@end defvar - -@deffn Command minibuffer-completion-help -This function creates a list of the possible completions of the -current minibuffer contents. It works by calling @code{all-completions} -using the value of the variable @code{minibuffer-completion-table} as -the @var{collection} argument, and the value of -@code{minibuffer-completion-predicate} as the @var{predicate} argument. -The list of completions is displayed as text in a buffer named -@samp{*Completions*}. -@end deffn - -@defun display-completion-list completions -This function displays @var{completions} to the stream in -@code{standard-output}, usually a buffer. (@xref{Read and Print}, for more -information about streams.) The argument @var{completions} is normally -a list of completions just returned by @code{all-completions}, but it -does not have to be. Each element may be a symbol or a string, either -of which is simply printed, or a list of two strings, which is printed -as if the strings were concatenated. - -This function is called by @code{minibuffer-completion-help}. The -most common way to use it is together with -@code{with-output-to-temp-buffer}, like this: - -@example -(with-output-to-temp-buffer "*Completions*" - (display-completion-list - (all-completions (buffer-string) my-alist))) -@end example -@end defun - -@defopt completion-auto-help -If this variable is non-@code{nil}, the completion commands -automatically display a list of possible completions whenever nothing -can be completed because the next character is not uniquely determined. -@end defopt - -@node High-Level Completion -@subsection High-Level Completion Functions - - This section describes the higher-level convenient functions for -reading certain sorts of names with completion. - - In most cases, you should not call these functions in the middle of a -Lisp function. When possible, do all minibuffer input as part of -reading the arguments for a command, in the @code{interactive} spec. -@xref{Defining Commands}. - -@defun read-buffer prompt &optional default existing -This function reads the name of a buffer and returns it as a string. -The argument @var{default} is the default name to use, the value to -return if the user exits with an empty minibuffer. If non-@code{nil}, -it should be a string or a buffer. It is mentioned in the prompt, but -is not inserted in the minibuffer as initial input. - -If @var{existing} is non-@code{nil}, then the name specified must be -that of an existing buffer. The usual commands to exit the minibuffer -do not exit if the text is not valid, and @key{RET} does completion to -attempt to find a valid name. (However, @var{default} is not checked -for validity; it is returned, whatever it is, if the user exits with the -minibuffer empty.) - -In the following example, the user enters @samp{minibuffer.t}, and -then types @key{RET}. The argument @var{existing} is @code{t}, and the -only buffer name starting with the given input is -@samp{minibuffer.texi}, so that name is the value. - -@example -(read-buffer "Buffer name? " "foo" t) -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Buffer name? (default foo) @point{} ----------- Buffer: Minibuffer ---------- -@end group - -@group -;; @r{The user types @kbd{minibuffer.t @key{RET}}.} - @result{} "minibuffer.texi" -@end group -@end example -@end defun - -@defun read-command prompt -This function reads the name of a command and returns it as a Lisp -symbol. The argument @var{prompt} is used as in -@code{read-from-minibuffer}. Recall that a command is anything for -which @code{commandp} returns @code{t}, and a command name is a symbol -for which @code{commandp} returns @code{t}. @xref{Interactive Call}. - -@example -(read-command "Command name? ") - -@group -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Command name? ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -If the user types @kbd{forward-c @key{RET}}, then this function returns -@code{forward-char}. - -The @code{read-command} function is a simplified interface to -@code{completing-read}. It uses the variable @code{obarray} so as to -complete in the set of extant Lisp symbols, and it uses the -@code{commandp} predicate so as to accept only command names: - -@cindex @code{commandp} example -@example -@group -(read-command @var{prompt}) -@equiv{} -(intern (completing-read @var{prompt} obarray - 'commandp t nil)) -@end group -@end example -@end defun - -@defun read-variable prompt -This function reads the name of a user variable and returns it as a -symbol. - -@example -@group -(read-variable "Variable name? ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -Variable name? @point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -If the user then types @kbd{fill-p @key{RET}}, @code{read-variable} -returns @code{fill-prefix}. - -This function is similar to @code{read-command}, but uses the -predicate @code{user-variable-p} instead of @code{commandp}: - -@cindex @code{user-variable-p} example -@example -@group -(read-variable @var{prompt}) -@equiv{} -(intern - (completing-read @var{prompt} obarray - 'user-variable-p t nil)) -@end group -@end example -@end defun - -@node Reading File Names -@subsection Reading File Names - - Here is another high-level completion function, designed for reading a -file name. It provides special features including automatic insertion -of the default directory. - -@defun read-file-name prompt &optional directory default existing initial -This function reads a file name in the minibuffer, prompting with -@var{prompt} and providing completion. If @var{default} is -non-@code{nil}, then the function returns @var{default} if the user just -types @key{RET}. @var{default} is not checked for validity; it is -returned, whatever it is, if the user exits with the minibuffer empty. - -If @var{existing} is non-@code{nil}, then the user must specify the name -of an existing file; @key{RET} performs completion to make the name -valid if possible, and then refuses to exit if it is not valid. If the -value of @var{existing} is neither @code{nil} nor @code{t}, then -@key{RET} also requires confirmation after completion. If -@var{existing} is @code{nil}, then the name of a nonexistent file is -acceptable. - -The argument @var{directory} specifies the directory to use for -completion of relative file names. If @code{insert-default-directory} -is non-@code{nil}, @var{directory} is also inserted in the minibuffer as -initial input. It defaults to the current buffer's value of -@code{default-directory}. - -@c Emacs 19 feature -If you specify @var{initial}, that is an initial file name to insert in -the buffer (after with @var{directory}, if that is inserted). In this -case, point goes at the beginning of @var{initial}. The default for -@var{initial} is @code{nil}---don't insert any file name. To see what -@var{initial} does, try the command @kbd{C-x C-v}. - -Here is an example: - -@example -@group -(read-file-name "The file is ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following appears in the minibuffer:} -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is /gp/gnu/elisp/@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@noindent -Typing @kbd{manual @key{TAB}} results in the following: - -@example -@group ----------- Buffer: Minibuffer ---------- -The file is /gp/gnu/elisp/manual.texi@point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example - -@c Wordy to avoid overfull hbox in smallbook mode. -@noindent -If the user types @key{RET}, @code{read-file-name} returns the file name -as the string @code{"/gp/gnu/elisp/manual.texi"}. -@end defun - -@defopt insert-default-directory -This variable is used by @code{read-file-name}. Its value controls -whether @code{read-file-name} starts by placing the name of the default -directory in the minibuffer, plus the initial file name if any. If the -value of this variable is @code{nil}, then @code{read-file-name} does -not place any initial input in the minibuffer (unless you specify -initial input with the @var{initial} argument). In that case, the -default directory is still used for completion of relative file names, -but is not displayed. - -For example: - -@example -@group -;; @r{Here the minibuffer starts out with the default directory.} -(let ((insert-default-directory t)) - (read-file-name "The file is ")) -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is ~lewis/manual/@point{} ----------- Buffer: Minibuffer ---------- -@end group - -@group -;; @r{Here the minibuffer is empty and only the prompt} -;; @r{appears on its line.} -(let ((insert-default-directory nil)) - (read-file-name "The file is ")) -@end group - -@group ----------- Buffer: Minibuffer ---------- -The file is @point{} ----------- Buffer: Minibuffer ---------- -@end group -@end example -@end defopt - -@node Programmed Completion -@subsection Programmed Completion -@cindex programmed completion - - Sometimes it is not possible to create an alist or an obarray -containing all the intended possible completions. In such a case, you -can supply your own function to compute the completion of a given string. -This is called @dfn{programmed completion}. - - To use this feature, pass a symbol with a function definition as the -@var{collection} argument to @code{completing-read}. The function -@code{completing-read} arranges to pass your completion function along -to @code{try-completion} and @code{all-completions}, which will then let -your function do all the work. - - The completion function should accept three arguments: - -@itemize @bullet -@item -The string to be completed. - -@item -The predicate function to filter possible matches, or @code{nil} if -none. Your function should call the predicate for each possible match, -and ignore the possible match if the predicate returns @code{nil}. - -@item -A flag specifying the type of operation. -@end itemize - - There are three flag values for three operations: - -@itemize @bullet -@item -@code{nil} specifies @code{try-completion}. The completion function -should return the completion of the specified string, or @code{t} if the -string is a unique and exact match already, or @code{nil} if the string -matches no possibility. - -If the string is an exact match for one possibility, but also matches -other longer possibilities, the function shuold return the string, not -@code{t}. - -@item -@code{t} specifies @code{all-completions}. The completion function -should return a list of all possible completions of the specified -string. - -@item -@code{lambda} specifies a test for an exact match. The completion -function should return @code{t} if the specified string is an exact -match for some possibility; @code{nil} otherwise. -@end itemize - - It would be consistent and clean for completion functions to allow -lambda expressions (lists that are functions) as well as function -symbols as @var{collection}, but this is impossible. Lists as -completion tables are already assigned another meaning---as alists. It -would be unreliable to fail to handle an alist normally because it is -also a possible function. So you must arrange for any function you wish -to use for completion to be encapsulated in a symbol. - - Emacs uses programmed completion when completing file names. -@xref{File Name Completion}. - -@node Yes-or-No Queries -@section Yes-or-No Queries -@cindex asking the user questions -@cindex querying the user -@cindex yes-or-no questions - - This section describes functions used to ask the user a yes-or-no -question. The function @code{y-or-n-p} can be answered with a single -character; it is useful for questions where an inadvertent wrong answer -will not have serious consequences. @code{yes-or-no-p} is suitable for -more momentous questions, since it requires three or four characters to -answer. - - If either of these functions is called in a command that was invoked -using the mouse---more precisely, if @code{last-nonmenu-event} -(@pxref{Command Loop Info}) is either @code{nil} or a list---then it -uses a dialog box or pop-up menu to ask the question. Otherwise, it -uses keyboard input. You can force use of the mouse or use of keyboard -input by binding @code{last-nonmenu-event} to a suitable value around -the call. - - Strictly speaking, @code{yes-or-no-p} uses the minibuffer and -@code{y-or-n-p} does not; but it seems best to describe them together. - -@defun y-or-n-p prompt -This function asks the user a question, expecting input in the echo -area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the -user types @kbd{n}. This function also accepts @key{SPC} to mean yes -and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like -@kbd{C-g}, because the question might look like a minibuffer and for -that reason the user might try to use @kbd{C-]} to get out. The answer -is a single character, with no @key{RET} needed to terminate it. Upper -and lower case are equivalent. - -``Asking the question'' means printing @var{prompt} in the echo area, -followed by the string @w{@samp{(y or n) }}. If the input is not one of -the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}}, -@kbd{@key{DEL}}, or something that quits), the function responds -@samp{Please answer y or n.}, and repeats the request. - -This function does not actually use the minibuffer, since it does not -allow editing of the answer. It actually uses the echo area (@pxref{The -Echo Area}), which uses the same screen space as the minibuffer. The -cursor moves to the echo area while the question is being asked. - -The answers and their meanings, even @samp{y} and @samp{n}, are not -hardwired. The keymap @code{query-replace-map} specifies them. -@xref{Search and Replace}. - -In the following example, the user first types @kbd{q}, which is -invalid. At the next prompt the user types @kbd{y}. - -@smallexample -@group -(y-or-n-p "Do you need a lift? ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears in the echo area:} -@end group - -@group ----------- Echo area ---------- -Do you need a lift? (y or n) ----------- Echo area ---------- -@end group - -;; @r{If the user then types @kbd{q}, the following appears:} - -@group ----------- Echo area ---------- -Please answer y or n. Do you need a lift? (y or n) ----------- Echo area ---------- -@end group - -;; @r{When the user types a valid answer,} -;; @r{it is displayed after the question:} - -@group ----------- Echo area ---------- -Do you need a lift? (y or n) y ----------- Echo area ---------- -@end group -@end smallexample - -@noindent -We show successive lines of echo area messages, but only one actually -appears on the screen at a time. -@end defun - -@defun y-or-n-p-with-timeout prompt seconds default-value -Like @code{y-or-n-p}, except that if the user fails to answer within -@var{seconds} seconds, this function stops waiting and returns -@var{default-value}. It works by setting up a timer; see @ref{Timers}. -The argument @var{seconds} may be an integer or a floating point number. -@end defun - -@defun yes-or-no-p prompt -This function asks the user a question, expecting input in the -minibuffer. It returns @code{t} if the user enters @samp{yes}, -@code{nil} if the user types @samp{no}. The user must type @key{RET} to -finalize the response. Upper and lower case are equivalent. - -@code{yes-or-no-p} starts by displaying @var{prompt} in the echo area, -followed by @w{@samp{(yes or no) }}. The user must type one of the -expected responses; otherwise, the function responds @samp{Please answer -yes or no.}, waits about two seconds and repeats the request. - -@code{yes-or-no-p} requires more work from the user than -@code{y-or-n-p} and is appropriate for more crucial decisions. - -Here is an example: - -@smallexample -@group -(yes-or-no-p "Do you really want to remove everything? ") - -;; @r{After evaluation of the preceding expression,} -;; @r{the following prompt appears,} -;; @r{with an empty minibuffer:} -@end group - -@group ----------- Buffer: minibuffer ---------- -Do you really want to remove everything? (yes or no) ----------- Buffer: minibuffer ---------- -@end group -@end smallexample - -@noindent -If the user first types @kbd{y @key{RET}}, which is invalid because this -function demands the entire word @samp{yes}, it responds by displaying -these prompts, with a brief pause between them: - -@smallexample -@group ----------- Buffer: minibuffer ---------- -Please answer yes or no. -Do you really want to remove everything? (yes or no) ----------- Buffer: minibuffer ---------- -@end group -@end smallexample -@end defun - -@node Multiple Queries -@section Asking Multiple Y-or-N Questions - - When you have a series of similar questions to ask, such as ``Do you -want to save this buffer'' for each buffer in turn, you should use -@code{map-y-or-n-p} to ask the collection of questions, rather than -asking each question individually. This gives the user certain -convenient facilities such as the ability to answer the whole series at -once. - -@defun map-y-or-n-p prompter actor list &optional help action-alist -This function, new in Emacs 19, asks the user a series of questions, -reading a single-character answer in the echo area for each one. - -The value of @var{list} specifies the objects to ask questions about. -It should be either a list of objects or a generator function. If it is -a function, it should expect no arguments, and should return either the -next object to ask about, or @code{nil} meaning stop asking questions. - -The argument @var{prompter} specifies how to ask each question. If -@var{prompter} is a string, the question text is computed like this: - -@example -(format @var{prompter} @var{object}) -@end example - -@noindent -where @var{object} is the next object to ask about (as obtained from -@var{list}). - -If not a string, @var{prompter} should be a function of one argument -(the next object to ask about) and should return the question text. If -the value is a string, that is the question to ask the user. The -function can also return @code{t} meaning do act on this object (and -don't ask the user), or @code{nil} meaning ignore this object (and don't -ask the user). - -The argument @var{actor} says how to act on the answers that the user -gives. It should be a function of one argument, and it is called with -each object that the user says yes for. Its argument is always an -object obtained from @var{list}. - -If the argument @var{help} is given, it should be a list of this form: - -@example -(@var{singular} @var{plural} @var{action}) -@end example - -@noindent -where @var{singular} is a string containing a singular noun that -describes the objects conceptually being acted on, @var{plural} is the -corresponding plural noun, and @var{action} is a transitive verb -describing what @var{actor} does. - -If you don't specify @var{help}, the default is @code{("object" -"objects" "act on")}. - -Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or -@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip -that object; @kbd{!} to act on all following objects; @key{ESC} or -@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on -the current object and then exit; or @kbd{C-h} to get help. These are -the same answers that @code{query-replace} accepts. The keymap -@code{query-replace-map} defines their meaning for @code{map-y-or-n-p} -as well as for @code{query-replace}; see @ref{Search and Replace}. - -You can use @var{action-alist} to specify additional possible answers -and what they mean. It is an alist of elements of the form -@code{(@var{char} @var{function} @var{help})}, each of which defines one -additional answer. In this element, @var{char} is a character (the -answer); @var{function} is a function of one argument (an object from -@var{list}); @var{help} is a string. - -When the user responds with @var{char}, @code{map-y-or-n-p} calls -@var{function}. If it returns non-@code{nil}, the object is considered -``acted upon'', and @code{map-y-or-n-p} advances to the next object in -@var{list}. If it returns @code{nil}, the prompt is repeated for the -same object. - -If @code{map-y-or-n-p} is called in a command that was invoked using the -mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command -Loop Info}) is either @code{nil} or a list---then it uses a dialog box -or pop-up menu to ask the question. In this case, it does not use -keyboard input or the echo area. You can force use of the mouse or use -of keyboard input by binding @code{last-nonmenu-event} to a suitable -value around the call. - -The return value of @code{map-y-or-n-p} is the number of objects acted on. -@end defun - -@node Minibuffer Misc -@comment node-name, next, previous, up -@section Minibuffer Miscellany - - This section describes some basic functions and variables related to -minibuffers. - -@deffn Command exit-minibuffer -This command exits the active minibuffer. It is normally bound to -keys in minibuffer local keymaps. -@end deffn - -@deffn Command self-insert-and-exit -This command exits the active minibuffer after inserting the last -character typed on the keyboard (found in @code{last-command-char}; -@pxref{Command Loop Info}). -@end deffn - -@deffn Command previous-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th previous (older) history element. -@end deffn - -@deffn Command next-history-element n -This command replaces the minibuffer contents with the value of the -@var{n}th more recent history element. -@end deffn - -@deffn Command previous-matching-history-element pattern -This command replaces the minibuffer contents with the value of the -previous (older) history element that matches @var{pattern} (a regular -expression). -@end deffn - -@deffn Command next-matching-history-element pattern -This command replaces the minibuffer contents with the value of the next -(newer) history element that matches @var{pattern} (a regular -expression). -@end deffn - -@defun minibuffer-prompt -This function returns the prompt string of the currently active -minibuffer. If no minibuffer is active, it returns @code{nil}. -@end defun - -@defun minibuffer-prompt-width -This function returns the display width of the prompt string of the -currently active minibuffer. If no minibuffer is active, it returns 0. -@end defun - -@defvar minibuffer-setup-hook -This is a normal hook that is run whenever the minibuffer is entered. -@xref{Hooks}. -@end defvar - -@defvar minibuffer-exit-hook -This is a normal hook that is run whenever the minibuffer is exited. -@xref{Hooks}. -@end defvar - -@defvar minibuffer-help-form -The current value of this variable is used to rebind @code{help-form} -locally inside the minibuffer (@pxref{Help Functions}). -@end defvar - -@defun active-minibuffer-window -This function returns the currently active minibuffer window, or -@code{nil} if none is currently active. -@end defun - -@defun minibuffer-window &optional frame -This function returns the minibuffer window used for frame @var{frame}. -If @var{frame} is @code{nil}, that stands for the current frame. Note -that the minibuffer window used by a frame need not be part of that -frame---a frame that has no minibuffer of its own necessarily uses some -other frame's minibuffer window. -@end defun - -@c Emacs 19 feature -@defun window-minibuffer-p window -This function returns non-@code{nil} if @var{window} is a minibuffer window. -@end defun - -It is not correct to determine whether a given window is a minibuffer by -comparing it with the result of @code{(minibuffer-window)}, because -there can be more than one minibuffer window if there is more than one -frame. - -@defun minibuffer-window-active-p window -This function returns non-@code{nil} if @var{window}, assumed to be -a minibuffer window, is currently active. -@end defun - -@defvar minibuffer-scroll-window -If the value of this variable is non-@code{nil}, it should be a window -object. When the function @code{scroll-other-window} is called in the -minibuffer, it scrolls this window. -@end defvar - -Finally, some functions and variables deal with recursive minibuffers -(@pxref{Recursive Editing}): - -@defun minibuffer-depth -This function returns the current depth of activations of the -minibuffer, a nonnegative integer. If no minibuffers are active, it -returns zero. -@end defun - -@defopt enable-recursive-minibuffers -If this variable is non-@code{nil}, you can invoke commands (such as -@code{find-file}) that use minibuffers even while in the minibuffer -window. Such invocation produces a recursive editing level for a new -minibuffer. The outer-level minibuffer is invisible while you are -editing the inner one. - -This variable only affects invoking the minibuffer while the -minibuffer window is selected. If you switch windows while in the -minibuffer, you can always invoke minibuffer commands while some other -window is selected. -@end defopt - -@c Emacs 19 feature -If a command name has a property @code{enable-recursive-minibuffers} -that is non-@code{nil}, then the command can use the minibuffer to read -arguments even if it is invoked from the minibuffer. The minibuffer -command @code{next-matching-history-element} (normally @kbd{M-s} in the -minibuffer) uses this feature. diff --git a/lispref/modes.texi b/lispref/modes.texi deleted file mode 100644 index dda63c9c0e5..00000000000 --- a/lispref/modes.texi +++ /dev/null @@ -1,1425 +0,0 @@ -@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/modes -@node Modes, Documentation, Keymaps, Top -@chapter Major and Minor Modes -@cindex mode - - A @dfn{mode} is a set of definitions that customize Emacs and can be -turned on and off while you edit. There are two varieties of modes: -@dfn{major modes}, which are mutually exclusive and used for editing -particular kinds of text, and @dfn{minor modes}, which provide features -that users can enable individually. - - This chapter describes how to write both major and minor modes, how to -indicate them in the mode line, and how they run hooks supplied by the -user. For related topics such as keymaps and syntax tables, see -@ref{Keymaps}, and @ref{Syntax Tables}. - -@menu -* Major Modes:: Defining major modes. -* Minor Modes:: Defining minor modes. -* Mode Line Format:: Customizing the text that appears in the mode line. -* Hooks:: How to use hooks; how to write code that provides hooks. -@end menu - -@node Major Modes -@section Major Modes -@cindex major mode -@cindex Fundamental mode - - Major modes specialize Emacs for editing particular kinds of text. -Each buffer has only one major mode at a time. - - The least specialized major mode is called @dfn{Fundamental mode}. -This mode has no mode-specific definitions or variable settings, so each -Emacs command behaves in its default manner, and each option is in its -default state. All other major modes redefine various keys and options. -For example, Lisp Interaction mode provides special key bindings for -@key{LFD} (@code{eval-print-last-sexp}), @key{TAB} -(@code{lisp-indent-line}), and other keys. - - When you need to write several editing commands to help you perform a -specialized editing task, creating a new major mode is usually a good -idea. In practice, writing a major mode is easy (in contrast to -writing a minor mode, which is often difficult). - - If the new mode is similar to an old one, it is often unwise to modify -the old one to serve two purposes, since it may become harder to use and -maintain. Instead, copy and rename an existing major mode definition -and alter the copy---or define a @dfn{derived mode} (@pxref{Derived -Modes}). For example, Rmail Edit mode, which is in -@file{emacs/lisp/rmailedit.el}, is a major mode that is very similar to -Text mode except that it provides three additional commands. Its -definition is distinct from that of Text mode, but was derived from it. - - Rmail Edit mode is an example of a case where one piece of text is put -temporarily into a different major mode so it can be edited in a -different way (with ordinary Emacs commands rather than Rmail). In such -cases, the temporary major mode usually has a command to switch back to -the buffer's usual mode (Rmail mode, in this case). You might be -tempted to present the temporary redefinitions inside a recursive edit -and restore the usual ones when the user exits; but this is a bad idea -because it constrains the user's options when it is done in more than -one buffer: recursive edits must be exited most-recently-entered first. -Using alternative major modes avoids this limitation. @xref{Recursive -Editing}. - - The standard GNU Emacs Lisp library directory contains the code for -several major modes, in files including @file{text-mode.el}, -@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and -@file{rmail.el}. You can look at these libraries to see how modes are -written. Text mode is perhaps the simplest major mode aside from -Fundamental mode. Rmail mode is a complicated and specialized mode. - -@menu -* Major Mode Conventions:: Coding conventions for keymaps, etc. -* Example Major Modes:: Text mode and Lisp modes. -* Auto Major Mode:: How Emacs chooses the major mode automatically. -* Mode Help:: Finding out how to use a mode. -* Derived Modes:: Defining a new major mode based on another major - mode. -@end menu - -@node Major Mode Conventions -@subsection Major Mode Conventions - - The code for existing major modes follows various coding conventions, -including conventions for local keymap and syntax table initialization, -global names, and hooks. Please follow these conventions when you -define a new major mode: - -@itemize @bullet -@item -Define a command whose name ends in @samp{-mode}, with no arguments, -that switches to the new mode in the current buffer. This command -should set up the keymap, syntax table, and local variables in an -existing buffer without changing the buffer's text. - -@item -Write a documentation string for this command that describes the -special commands available in this mode. @kbd{C-h m} -(@code{describe-mode}) in your mode will display this string. - -The documentation string may include the special documentation -substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and -@samp{\<@var{keymap}>}, that enable the documentation to adapt -automatically to the user's own key bindings. @xref{Keys in -Documentation}. - -@item -The major mode command should start by calling -@code{kill-all-local-variables}. This is what gets rid of the local -variables of the major mode previously in effect. - -@item -The major mode command should set the variable @code{major-mode} to the -major mode command symbol. This is how @code{describe-mode} discovers -which documentation to print. - -@item -The major mode command should set the variable @code{mode-name} to the -``pretty'' name of the mode, as a string. This appears in the mode -line. - -@item -@cindex functions in modes -Since all global names are in the same name space, all the global -variables, constants, and functions that are part of the mode should -have names that start with the major mode name (or with an abbreviation -of it if the name is long). @xref{Style Tips}. - -@item -@cindex keymaps in modes -The major mode should usually have its own keymap, which is used as the -local keymap in all buffers in that mode. The major mode function -should call @code{use-local-map} to install this local map. -@xref{Active Keymaps}, for more information. - -This keymap should be kept in a global variable named -@code{@var{modename}-mode-map}. Normally the library that defines the -mode sets this variable. - -@xref{Tips for Defining}, for advice about how to write the code to set -up the mode's keymap variable. - -@item -@cindex syntax tables in modes -The mode may have its own syntax table or may share one with other -related modes. If it has its own syntax table, it should store this in -a variable named @code{@var{modename}-mode-syntax-table}. @xref{Syntax -Tables}. - -@item -If the mode handles a language that has a syntax for comments, it should -set the variables that define the comment syntax. @xref{Options for -Comments,, Options Controlling Comments, emacs, The GNU Emacs Manual}. - -@item -@cindex abbrev tables in modes -The mode may have its own abbrev table or may share one with other -related modes. If it has its own abbrev table, it should store this in -a variable named @code{@var{modename}-mode-abbrev-table}. @xref{Abbrev -Tables}. - -@item -@vindex font-lock-defaults -The mode should specify how to do highlighting for Font Lock mode, by -setting up a buffer-local value for the variable -@code{font-lock-defaults}. - -@item -@vindex imenu-generic-expression -@vindex imenu-create-index-function -The mode should specify how Imenu should find the definitions or -sections of a buffer, by setting up a buffer-local value for the -variable @code{imenu-generic-expression} or -@code{imenu-create-index-function}. - -@item -Use @code{defvar} to set mode-related variables, so that they are not -reinitialized if they already have a value. (Such reinitialization -could discard customizations made by the user.) - -@item -@cindex buffer-local variables in modes -To make a buffer-local binding for an Emacs customization variable, use -@code{make-local-variable} in the major mode command, not -@code{make-variable-buffer-local}. The latter function would make the -variable local to every buffer in which it is subsequently set, which -would affect buffers that do not use this mode. It is undesirable for a -mode to have such global effects. @xref{Buffer-Local Variables}. - -It's ok to use @code{make-variable-buffer-local}, if you wish, for a -variable used only within a single Lisp package. - -@item -@cindex mode hook -@cindex major mode hook -Each major mode should have a @dfn{mode hook} named -@code{@var{modename}-mode-hook}. The major mode command should run that -hook, with @code{run-hooks}, as the very last thing it -does. @xref{Hooks}. - -@item -The major mode command may also run the hooks of some more basic modes. -For example, @code{indented-text-mode} runs @code{text-mode-hook} as -well as @code{indented-text-mode-hook}. It may run these other hooks -immediately before the mode's own hook (that is, after everything else), -or it may run them earlier. - -@item -If something special should be done if the user switches a buffer from -this mode to any other major mode, the mode can set a local value for -@code{change-major-mode-hook}. - -@item -If this mode is appropriate only for specially-prepared text, then the -major mode command symbol should have a property named @code{mode-class} -with value @code{special}, put on as follows: - -@cindex @code{mode-class} property -@cindex @code{special} -@example -(put 'funny-mode 'mode-class 'special) -@end example - -@noindent -This tells Emacs that new buffers created while the current buffer has -Funny mode should not inherit Funny mode. Modes such as Dired, Rmail, -and Buffer List use this feature. - -@item -If you want to make the new mode the default for files with certain -recognizable names, add an element to @code{auto-mode-alist} to select -the mode for those file names. If you define the mode command to -autoload, you should add this element in the same file that calls -@code{autoload}. Otherwise, it is sufficient to add the element in the -file that contains the mode definition. @xref{Auto Major Mode}. - -@item -@cindex @file{.emacs} customization -In the documentation, you should provide a sample @code{autoload} form -and an example of how to add to @code{auto-mode-alist}, that users can -include in their @file{.emacs} files. - -@item -@cindex mode loading -The top-level forms in the file defining the mode should be written so -that they may be evaluated more than once without adverse consequences. -Even if you never load the file more than once, someone else will. -@end itemize - -@defvar change-major-mode-hook -This normal hook is run by @code{kill-all-local-variables} before it -does anything else. This gives major modes a way to arrange for -something special to be done if the user switches to a different major -mode. For best results, make this variable buffer-local, so that it -will disappear after doing its job and will not interfere with the -subsequent major mode. @xref{Hooks}. -@end defvar - -@node Example Major Modes -@subsection Major Mode Examples - - Text mode is perhaps the simplest mode besides Fundamental mode. -Here are excerpts from @file{text-mode.el} that illustrate many of -the conventions listed above: - -@smallexample -@group -;; @r{Create mode-specific tables.} -(defvar text-mode-syntax-table nil - "Syntax table used while in text mode.") -@end group - -@group -(if text-mode-syntax-table - () ; @r{Do not change the table if it is already set up.} - (setq text-mode-syntax-table (make-syntax-table)) - (modify-syntax-entry ?\" ". " text-mode-syntax-table) - (modify-syntax-entry ?\\ ". " text-mode-syntax-table) - (modify-syntax-entry ?' "w " text-mode-syntax-table)) -@end group - -@group -(defvar text-mode-abbrev-table nil - "Abbrev table used while in text mode.") -(define-abbrev-table 'text-mode-abbrev-table ()) -@end group - -@group -(defvar text-mode-map nil) ; @r{Create a mode-specific keymap.} - -(if text-mode-map - () ; @r{Do not change the keymap if it is already set up.} - (setq text-mode-map (make-sparse-keymap)) - (define-key text-mode-map "\t" 'tab-to-tab-stop) - (define-key text-mode-map "\es" 'center-line) - (define-key text-mode-map "\eS" 'center-paragraph)) -@end group -@end smallexample - - Here is the complete major mode function definition for Text mode: - -@smallexample -@group -(defun text-mode () - "Major mode for editing text intended for humans to read. - Special commands: \\@{text-mode-map@} -@end group -@group -Turning on text-mode runs the hook `text-mode-hook'." - (interactive) - (kill-all-local-variables) -@end group -@group - (use-local-map text-mode-map) ; @r{This provides the local keymap.} - (setq mode-name "Text") ; @r{This name goes into the mode line.} - (setq major-mode 'text-mode) ; @r{This is how @code{describe-mode}} - ; @r{finds the doc string to print.} - (setq local-abbrev-table text-mode-abbrev-table) - (set-syntax-table text-mode-syntax-table) - (run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to} - ; @r{customize the mode with a hook.} -@end group -@end smallexample - -@cindex @file{lisp-mode.el} - The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp -Interaction mode) have more features than Text mode and the code is -correspondingly more complicated. Here are excerpts from -@file{lisp-mode.el} that illustrate how these modes are written. - -@cindex syntax table example -@smallexample -@group -;; @r{Create mode-specific table variables.} -(defvar lisp-mode-syntax-table nil "") -(defvar emacs-lisp-mode-syntax-table nil "") -(defvar lisp-mode-abbrev-table nil "") -@end group - -@group -(if (not emacs-lisp-mode-syntax-table) ; @r{Do not change the table} - ; @r{if it is already set.} - (let ((i 0)) - (setq emacs-lisp-mode-syntax-table (make-syntax-table)) -@end group - -@group - ;; @r{Set syntax of chars up to 0 to class of chars that are} - ;; @r{part of symbol names but not words.} - ;; @r{(The number 0 is @code{48} in the @sc{ASCII} character set.)} - (while (< i ?0) - (modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table) - (setq i (1+ i))) - @dots{} -@end group -@group - ;; @r{Set the syntax for other characters.} - (modify-syntax-entry ? " " emacs-lisp-mode-syntax-table) - (modify-syntax-entry ?\t " " emacs-lisp-mode-syntax-table) - @dots{} -@end group -@group - (modify-syntax-entry ?\( "() " emacs-lisp-mode-syntax-table) - (modify-syntax-entry ?\) ")( " emacs-lisp-mode-syntax-table) - @dots{})) -;; @r{Create an abbrev table for lisp-mode.} -(define-abbrev-table 'lisp-mode-abbrev-table ()) -@end group -@end smallexample - - Much code is shared among the three Lisp modes. The following -function sets various variables; it is called by each of the major Lisp -mode functions: - -@smallexample -@group -(defun lisp-mode-variables (lisp-syntax) - ;; @r{The @code{lisp-syntax} argument is @code{nil} in Emacs Lisp mode,} - ;; @r{and @code{t} in the other two Lisp modes.} - (cond (lisp-syntax - (if (not lisp-mode-syntax-table) - ;; @r{The Emacs Lisp mode syntax table always exists, but} - ;; @r{the Lisp Mode syntax table is created the first time a} - ;; @r{mode that needs it is called. This is to save space.} -@end group -@group - (progn (setq lisp-mode-syntax-table - (copy-syntax-table emacs-lisp-mode-syntax-table)) - ;; @r{Change some entries for Lisp mode.} - (modify-syntax-entry ?\| "\" " - lisp-mode-syntax-table) - (modify-syntax-entry ?\[ "_ " - lisp-mode-syntax-table) - (modify-syntax-entry ?\] "_ " - lisp-mode-syntax-table))) -@end group -@group - (set-syntax-table lisp-mode-syntax-table))) - (setq local-abbrev-table lisp-mode-abbrev-table) - @dots{}) -@end group -@end smallexample - - Functions such as @code{forward-paragraph} use the value of the -@code{paragraph-start} variable. Since Lisp code is different from -ordinary text, the @code{paragraph-start} variable needs to be set -specially to handle Lisp. Also, comments are indented in a special -fashion in Lisp and the Lisp modes need their own mode-specific -@code{comment-indent-function}. The code to set these variables is the -rest of @code{lisp-mode-variables}. - -@smallexample -@group - (make-local-variable 'paragraph-start) - ;; @r{Having @samp{^} is not clean, but @code{page-delimiter}} - ;; @r{has them too, and removing those is a pain.} - (setq paragraph-start (concat "^$\\|" page-delimiter)) - @dots{} -@end group -@group - (make-local-variable 'comment-indent-function) - (setq comment-indent-function 'lisp-comment-indent)) -@end group -@end smallexample - - Each of the different Lisp modes has a slightly different keymap. For -example, Lisp mode binds @kbd{C-c C-l} to @code{run-lisp}, but the other -Lisp modes do not. However, all Lisp modes have some commands in -common. The following function adds these common commands to a given -keymap. - -@smallexample -@group -(defun lisp-mode-commands (map) - (define-key map "\e\C-q" 'indent-sexp) - (define-key map "\177" 'backward-delete-char-untabify) - (define-key map "\t" 'lisp-indent-line)) -@end group -@end smallexample - - Here is an example of using @code{lisp-mode-commands} to initialize a -keymap, as part of the code for Emacs Lisp mode. First we declare a -variable with @code{defvar} to hold the mode-specific keymap. When this -@code{defvar} executes, it sets the variable to @code{nil} if it was -void. Then we set up the keymap if the variable is @code{nil}. - - This code avoids changing the keymap or the variable if it is already -set up. This lets the user customize the keymap. - -@smallexample -@group -(defvar emacs-lisp-mode-map () "") -(if emacs-lisp-mode-map - () - (setq emacs-lisp-mode-map (make-sparse-keymap)) - (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun) - (lisp-mode-commands emacs-lisp-mode-map)) -@end group -@end smallexample - - Finally, here is the complete major mode function definition for -Emacs Lisp mode. - -@smallexample -@group -(defun emacs-lisp-mode () - "Major mode for editing Lisp code to run in Emacs. -Commands: -Delete converts tabs to spaces as it moves back. -Blank lines separate paragraphs. Semicolons start comments. -\\@{emacs-lisp-mode-map@} -@end group -@group -Entry to this mode runs the hook `emacs-lisp-mode-hook'." - (interactive) - (kill-all-local-variables) - (use-local-map emacs-lisp-mode-map) ; @r{This provides the local keymap.} - (set-syntax-table emacs-lisp-mode-syntax-table) -@end group -@group - (setq major-mode 'emacs-lisp-mode) ; @r{This is how @code{describe-mode}} - ; @r{finds out what to describe.} - (setq mode-name "Emacs-Lisp") ; @r{This goes into the mode line.} - (lisp-mode-variables nil) ; @r{This defines various variables.} - (run-hooks 'emacs-lisp-mode-hook)) ; @r{This permits the user to use a} - ; @r{hook to customize the mode.} -@end group -@end smallexample - -@node Auto Major Mode -@subsection How Emacs Chooses a Major Mode - - Based on information in the file name or in the file itself, Emacs -automatically selects a major mode for the new buffer when a file is -visited. - -@deffn Command fundamental-mode - Fundamental mode is a major mode that is not specialized for anything -in particular. Other major modes are defined in effect by comparison -with this one---their definitions say what to change, starting from -Fundamental mode. The @code{fundamental-mode} function does @emph{not} -run any hooks; you're not supposed to customize it. (If you want Emacs -to behave differently in Fundamental mode, change the @emph{global} -state of Emacs.) -@end deffn - -@deffn Command normal-mode &optional find-file -This function establishes the proper major mode and local variable -bindings for the current buffer. First it calls @code{set-auto-mode}, -then it runs @code{hack-local-variables} to parse, and bind or -evaluate as appropriate, any local variables. - -If the @var{find-file} argument to @code{normal-mode} is -non-@code{nil}, @code{normal-mode} assumes that the @code{find-file} -function is calling it. In this case, it may process a local variables -list at the end of the file and in the @samp{-*-} line. The variable -@code{enable-local-variables} controls whether to do so. - -If you run @code{normal-mode} interactively, the argument -@var{find-file} is normally @code{nil}. In this case, -@code{normal-mode} unconditionally processes any local variables list. -@xref{File variables, , Local Variables in Files, emacs, The GNU Emacs -Manual}, for the syntax of the local variables section of a file. - -@cindex file mode specification error -@code{normal-mode} uses @code{condition-case} around the call to the -major mode function, so errors are caught and reported as a @samp{File -mode specification error}, followed by the original error message. -@end deffn - -@defopt enable-local-variables -This variable controls processing of local variables lists in files -being visited. A value of @code{t} means process the local variables -lists unconditionally; @code{nil} means ignore them; anything else means -ask the user what to do for each file. The default value is @code{t}. -@end defopt - -@defvar ignored-local-variables -This variable holds a list of variables that should not be -set by a local variables list. Any value specified -for one of these variables is ignored. -@end defvar - -In addition to this list, any variable whose name has a non-@code{nil} -@code{risky-local-variable} property is also ignored. - -@defopt enable-local-eval -This variable controls processing of @samp{Eval:} in local variables -lists in files being visited. A value of @code{t} means process them -unconditionally; @code{nil} means ignore them; anything else means ask -the user what to do for each file. The default value is @code{maybe}. -@end defopt - -@defun set-auto-mode -@cindex visited file mode - This function selects the major mode that is appropriate for the -current buffer. It may base its decision on the value of the @w{@samp{-*-}} -line, on the visited file name (using @code{auto-mode-alist}), on the -@w{@samp{#!}} line (using @code{interpreter-mode-alist}), or on the -value of a local variable. However, this function does not look for -the @samp{mode:} local variable near the end of a file; the -@code{hack-local-variables} function does that. @xref{Choosing Modes, , -How Major Modes are Chosen, emacs, The GNU Emacs Manual}. -@end defun - -@defopt default-major-mode - This variable holds the default major mode for new buffers. The -standard value is @code{fundamental-mode}. - - If the value of @code{default-major-mode} is @code{nil}, Emacs uses -the (previously) current buffer's major mode for the major mode of a new -buffer. However, if the major mode symbol has a @code{mode-class} -property with value @code{special}, then it is not used for new buffers; -Fundamental mode is used instead. The modes that have this property are -those such as Dired and Rmail that are useful only with text that has -been specially prepared. -@end defopt - -@defun set-buffer-major-mode buffer -This function sets the major mode of @var{buffer} to the value of -@code{default-major-mode}. If that variable is @code{nil}, it uses -the current buffer's major mode (if that is suitable). - -The low-level primitives for creating buffers do not use this function, -but medium-level commands such as @code{switch-to-buffer} and -@code{find-file-noselect} use it whenever they create buffers. -@end defun - -@defvar initial-major-mode -@cindex @samp{*scratch*} -The value of this variable determines the major mode of the initial -@samp{*scratch*} buffer. The value should be a symbol that is a major -mode command name. The default value is @code{lisp-interaction-mode}. -@end defvar - -@defvar auto-mode-alist -This variable contains an association list of file name patterns -(regular expressions; @pxref{Regular Expressions}) and corresponding -major mode functions. Usually, the file name patterns test for -suffixes, such as @samp{.el} and @samp{.c}, but this need not be the -case. An ordinary element of the alist looks like @code{(@var{regexp} . -@var{mode-function})}. - -For example, - -@smallexample -@group -(("^/tmp/fol/" . text-mode) - ("\\.texinfo\\'" . texinfo-mode) - ("\\.texi\\'" . texinfo-mode) -@end group -@group - ("\\.el\\'" . emacs-lisp-mode) - ("\\.c\\'" . c-mode) - ("\\.h\\'" . c-mode) - @dots{}) -@end group -@end smallexample - -When you visit a file whose expanded file name (@pxref{File Name -Expansion}) matches a @var{regexp}, @code{set-auto-mode} calls the -corresponding @var{mode-function}. This feature enables Emacs to select -the proper major mode for most files. - -If an element of @code{auto-mode-alist} has the form @code{(@var{regexp} -@var{function} t)}, then after calling @var{function}, Emacs searches -@code{auto-mode-alist} again for a match against the portion of the file -name that did not match before. - -This match-again feature is useful for uncompression packages: an entry -of the form @code{("\\.gz\\'" . @var{function})} can uncompress the file -and then put the uncompressed file in the proper mode according to the -name sans @samp{.gz}. - -Here is an example of how to prepend several pattern pairs to -@code{auto-mode-alist}. (You might use this sort of expression in your -@file{.emacs} file.) - -@smallexample -@group -(setq auto-mode-alist - (append - ;; @r{File name starts with a dot.} - '(("/\\.[^/]*\\'" . fundamental-mode) - ;; @r{File name has no dot.} - ("[^\\./]*\\'" . fundamental-mode) - ;; @r{File name ends in @samp{.C}.} - ("\\.C\\'" . c++-mode)) - auto-mode-alist)) -@end group -@end smallexample -@end defvar - -@defvar interpreter-mode-alist -This variable specifes major modes to use for scripts that specify a -command interpreter in an @samp{#!} line. Its value is a list of -elements of the form @code{(@var{interpreter} . @var{mode})}; for -example, @code{("perl" . perl-mode)} is one element present by default. -The element says to use mode @var{mode} if the file specifies -@var{interpreter}. - -This variable is applicable only when the @code{auto-mode-alist} does -not indicate which major mode to use. -@end defvar - -@defun hack-local-variables &optional force - This function parses, and binds or evaluates as appropriate, any local -variables for the current buffer. - - The handling of @code{enable-local-variables} documented for -@code{normal-mode} actually takes place here. The argument @var{force} -usually comes from the argument @var{find-file} given to -@code{normal-mode}. -@end defun - -@node Mode Help -@subsection Getting Help about a Major Mode -@cindex mode help -@cindex help for major mode -@cindex documentation for major mode - - The @code{describe-mode} function is used to provide information -about major modes. It is normally called with @kbd{C-h m}. The -@code{describe-mode} function uses the value of @code{major-mode}, -which is why every major mode function needs to set the -@code{major-mode} variable. - -@deffn Command describe-mode -This function displays the documentation of the current major mode. - -The @code{describe-mode} function calls the @code{documentation} -function using the value of @code{major-mode} as an argument. Thus, it -displays the documentation string of the major mode function. -(@xref{Accessing Documentation}.) -@end deffn - -@defvar major-mode -This variable holds the symbol for the current buffer's major mode. -This symbol should have a function definition that is the command to -switch to that major mode. The @code{describe-mode} function uses the -documentation string of the function as the documentation of the major -mode. -@end defvar - -@node Derived Modes -@subsection Defining Derived Modes - - It's often useful to define a new major mode in terms of an existing -one. An easy way to do this is to use @code{define-derived-mode}. - -@defmac define-derived-mode variant parent name docstring body@dots{} -This construct defines @var{variant} as a major mode command, using -@var{name} as the string form of the mode name. - -The new command @var{variant} is defined to call the function -@var{parent}, then override certain aspects of that parent mode: - -@itemize @bullet -@item -The new mode has its own keymap, named @code{@var{variant}-map}. -@code{define-derived-mode} initializes this map to inherit from -@code{@var{parent}-map}, if it is not already set. - -@item -The new mode has its own syntax table, kept in the variable -@code{@var{variant}-syntax-table}. -@code{define-derived-mode} initializes this variable by copying -@code{@var{parent}-syntax-table}, if it is not already set. - -@item -The new mode has its own abbrev table, kept in the variable -@code{@var{variant}-abbrev-table}. -@code{define-derived-mode} initializes this variable by copying -@code{@var{parent}-abbrev-table}, if it is not already set. - -@item -The new mode has its own mode hook, @code{@var{variant}-hook}, -which it runs in standard fashion as the very last thing that it does. -(The new mode also runs the mode hook of @var{parent} as part -of calling @var{parent}.) -@end itemize - -In addition, you can specify how to override other aspects of -@var{parent} with @var{body}. The command @var{variant} -evaluates the forms in @var{body} after setting up all its usual -overrides, just before running @code{@var{variant}-hook}. - -The argument @var{docstring} specifies the documentation string for the -new mode. If you omit @var{docstring}, @code{define-derived-mode} -generates a documentation string. - -Here is a hypothetical example: - -@example -(define-derived-mode hypertext-mode - text-mode "Hypertext" - "Major mode for hypertext. -\\@{hypertext-mode-map@}" - (setq case-fold-search nil)) - -(define-key hypertext-mode-map - [down-mouse-3] 'do-hyper-link) -@end example -@end defmac - -@node Minor Modes -@section Minor Modes -@cindex minor mode - - A @dfn{minor mode} provides features that users may enable or disable -independently of the choice of major mode. Minor modes can be enabled -individually or in combination. Minor modes would be better named -``Generally available, optional feature modes'' except that such a name is -unwieldy. - - A minor mode is not usually a modification of single major mode. For -example, Auto Fill mode may be used in any major mode that permits text -insertion. To be general, a minor mode must be effectively independent -of the things major modes do. - - A minor mode is often much more difficult to implement than a major -mode. One reason is that you should be able to activate and deactivate -minor modes in any order. A minor mode should be able to have its -desired effect regardless of the major mode and regardless of the other -minor modes in effect. - - Often the biggest problem in implementing a minor mode is finding a -way to insert the necessary hook into the rest of Emacs. Minor mode -keymaps make this easier than it used to be. - -@menu -* Minor Mode Conventions:: Tips for writing a minor mode. -* Keymaps and Minor Modes:: How a minor mode can have its own keymap. -@end menu - -@node Minor Mode Conventions -@subsection Conventions for Writing Minor Modes -@cindex minor mode conventions -@cindex conventions for writing minor modes - - There are conventions for writing minor modes just as there are for -major modes. Several of the major mode conventions apply to minor -modes as well: those regarding the name of the mode initialization -function, the names of global symbols, and the use of keymaps and -other tables. - - In addition, there are several conventions that are specific to -minor modes. - -@itemize @bullet -@item -@cindex mode variable -Make a variable whose name ends in @samp{-mode} to represent the minor -mode. Its value should enable or disable the mode (@code{nil} to -disable; anything else to enable.) We call this the @dfn{mode -variable}. - -This variable is used in conjunction with the @code{minor-mode-alist} to -display the minor mode name in the mode line. It can also enable -or disable a minor mode keymap. Individual commands or hooks can also -check the variable's value. - -If you want the minor mode to be enabled separately in each buffer, -make the variable buffer-local. - -@item -Define a command whose name is the same as the mode variable. -Its job is to enable and disable the mode by setting the variable. - -The command should accept one optional argument. If the argument is -@code{nil}, it should toggle the mode (turn it on if it is off, and off -if it is on). Otherwise, it should turn the mode on if the argument is -a positive integer, a symbol other than @code{nil} or @code{-}, or a -list whose @sc{car} is such an integer or symbol; it should turn the -mode off otherwise. - -Here is an example taken from the definition of @code{transient-mark-mode}. -It shows the use of @code{transient-mark-mode} as a variable that enables or -disables the mode's behavior, and also shows the proper way to toggle, -enable or disable the minor mode based on the raw prefix argument value. - -@smallexample -@group -(setq transient-mark-mode - (if (null arg) (not transient-mark-mode) - (> (prefix-numeric-value arg) 0))) -@end group -@end smallexample - -@item -Add an element to @code{minor-mode-alist} for each minor mode -(@pxref{Mode Line Variables}). This element should be a list of the -following form: - -@smallexample -(@var{mode-variable} @var{string}) -@end smallexample - -Here @var{mode-variable} is the variable that controls enabling of the -minor mode, and @var{string} is a short string, starting with a space, -to represent the mode in the mode line. These strings must be short so -that there is room for several of them at once. - -When you add an element to @code{minor-mode-alist}, use @code{assq} to -check for an existing element, to avoid duplication. For example: - -@smallexample -@group -(or (assq 'leif-mode minor-mode-alist) - (setq minor-mode-alist - (cons '(leif-mode " Leif") minor-mode-alist))) -@end group -@end smallexample -@end itemize - -@node Keymaps and Minor Modes -@subsection Keymaps and Minor Modes - - Each minor mode can have its own keymap, which is active when the mode -is enabled. To set up a keymap for a minor mode, add an element to the -alist @code{minor-mode-map-alist}. @xref{Active Keymaps}. - -@cindex @code{self-insert-command}, minor modes -One use of minor mode keymaps is to modify the behavior of certain -self-inserting characters so that they do something else as well as -self-insert. In general, this is the only way to do that, since the -facilities for customizing @code{self-insert-command} are limited to -special cases (designed for abbrevs and Auto Fill mode). (Do not try -substituting your own definition of @code{self-insert-command} for the -standard one. The editor command loop handles this function specially.) - -@node Mode Line Format -@section Mode Line Format -@cindex mode line - - Each Emacs window (aside from minibuffer windows) includes a mode line, -which displays status information about the buffer displayed in the -window. The mode line contains information about the buffer, such as its -name, associated file, depth of recursive editing, and the major and -minor modes. - - This section describes how the contents of the mode line are -controlled. It is in the chapter on modes because much of the -information displayed in the mode line relates to the enabled major and -minor modes. - - @code{mode-line-format} is a buffer-local variable that holds a -template used to display the mode line of the current buffer. All -windows for the same buffer use the same @code{mode-line-format} and -their mode lines appear the same (except for scrolling percentages and -line numbers). - - The mode line of a window is normally updated whenever a different -buffer is shown in the window, or when the buffer's modified-status -changes from @code{nil} to @code{t} or vice-versa. If you modify any of -the variables referenced by @code{mode-line-format} (@pxref{Mode Line -Variables}), you may want to force an update of the mode line so as to -display the new information. - -@c Emacs 19 feature -@defun force-mode-line-update -Force redisplay of the current buffer's mode line. -@end defun - - The mode line is usually displayed in inverse video; see -@code{mode-line-inverse-video} in @ref{Inverse Video}. - -@menu -* Mode Line Data:: The data structure that controls the mode line. -* Mode Line Variables:: Variables used in that data structure. -* %-Constructs:: Putting information into a mode line. -@end menu - -@node Mode Line Data -@subsection The Data Structure of the Mode Line -@cindex mode line construct - - The mode line contents are controlled by a data structure of lists, -strings, symbols, and numbers kept in the buffer-local variable -@code{mode-line-format}. The data structure is called a @dfn{mode line -construct}, and it is built in recursive fashion out of simpler mode line -constructs. The same data structure is used for constructing -frame titles (@pxref{Frame Titles}). - -@defvar mode-line-format -The value of this variable is a mode line construct with overall -responsibility for the mode line format. The value of this variable -controls which other variables are used to form the mode line text, and -where they appear. -@end defvar - - A mode line construct may be as simple as a fixed string of text, but -it usually specifies how to use other variables to construct the text. -Many of these variables are themselves defined to have mode line -constructs as their values. - - The default value of @code{mode-line-format} incorporates the values -of variables such as @code{mode-name} and @code{minor-mode-alist}. -Because of this, very few modes need to alter @code{mode-line-format}. -For most purposes, it is sufficient to alter the variables referenced by -@code{mode-line-format}. - - A mode line construct may be a list, a symbol, or a string. If the -value is a list, each element may be a list, a symbol, or a string. - -@table @code -@cindex percent symbol in mode line -@item @var{string} -A string as a mode line construct is displayed verbatim in the mode line -except for @dfn{@code{%}-constructs}. Decimal digits after the @samp{%} -specify the field width for space filling on the right (i.e., the data -is left justified). @xref{%-Constructs}. - -@item @var{symbol} -A symbol as a mode line construct stands for its value. The value of -@var{symbol} is used as a mode line construct, in place of @var{symbol}. -However, the symbols @code{t} and @code{nil} are ignored; so is any -symbol whose value is void. - -There is one exception: if the value of @var{symbol} is a string, it is -displayed verbatim: the @code{%}-constructs are not recognized. - -@item (@var{string} @var{rest}@dots{}) @r{or} (@var{list} @var{rest}@dots{}) -A list whose first element is a string or list means to process all the -elements recursively and concatenate the results. This is the most -common form of mode line construct. - -@item (@var{symbol} @var{then} @var{else}) -A list whose first element is a symbol is a conditional. Its meaning -depends on the value of @var{symbol}. If the value is non-@code{nil}, -the second element, @var{then}, is processed recursively as a mode line -element. But if the value of @var{symbol} is @code{nil}, the third -element, @var{else}, is processed recursively. You may omit @var{else}; -then the mode line element displays nothing if the value of @var{symbol} -is @code{nil}. - -@item (@var{width} @var{rest}@dots{}) -A list whose first element is an integer specifies truncation or -padding of the results of @var{rest}. The remaining elements -@var{rest} are processed recursively as mode line constructs and -concatenated together. Then the result is space filled (if -@var{width} is positive) or truncated (to @minus{}@var{width} columns, -if @var{width} is negative) on the right. - -For example, the usual way to show what percentage of a buffer is above -the top of the window is to use a list like this: @code{(-3 "%p")}. -@end table - - If you do alter @code{mode-line-format} itself, the new value should -use the same variables that appear in the default value (@pxref{Mode -Line Variables}), rather than duplicating their contents or displaying -the information in another fashion. This way, customizations made by -the user or by Lisp programs (such as @code{display-time} and major -modes) via changes to those variables remain effective. - -@cindex Shell mode @code{mode-line-format} - Here is an example of a @code{mode-line-format} that might be -useful for @code{shell-mode}, since it contains the hostname and default -directory. - -@example -@group -(setq mode-line-format - (list "" - 'mode-line-modified - "%b--" -@end group - (getenv "HOST") ; @r{One element is not constant.} - ":" - 'default-directory - " " - 'global-mode-string - " %[(" - 'mode-name - 'mode-line-process - 'minor-mode-alist - "%n" - ")%]----" -@group - '(line-number-mode "L%l--") - '(-3 . "%p") - "-%-")) -@end group -@end example - -@node Mode Line Variables -@subsection Variables Used in the Mode Line - - This section describes variables incorporated by the -standard value of @code{mode-line-format} into the text of the mode -line. There is nothing inherently special about these variables; any -other variables could have the same effects on the mode line if -@code{mode-line-format} were changed to use them. - -@defvar mode-line-modified -This variable holds the value of the mode-line construct that displays -whether the current buffer is modified. - -The default value of @code{mode-line-modified} is @code{("--%1*%1+-")}. -This means that the mode line displays @samp{--**-} if the buffer is -modified, @samp{-----} if the buffer is not modified, @samp{--%%-} if -the buffer is read only, and @samp{--%*--} if the buffer is read only -and modified. - -Changing this variable does not force an update of the mode line. -@end defvar - -@defvar mode-line-buffer-identification -This variable identifies the buffer being displayed in the window. Its -default value is @code{("%F: %17b")}, which means that it usually -displays @samp{Emacs:} followed by seventeen characters of the buffer -name. (In a terminal frame, it displays the frame name instead of -@samp{Emacs}; this has the effect of showing the frame number.) You may -want to change this in modes such as Rmail that do not behave like a -``normal'' Emacs. -@end defvar - -@defvar global-mode-string -This variable holds a mode line spec that appears in the mode line by -default, just after the buffer name. The command @code{display-time} -sets @code{global-mode-string} to refer to the variable -@code{display-time-string}, which holds a string containing the time and -load information. - -The @samp{%M} construct substitutes the value of -@code{global-mode-string}, but this is obsolete, since the variable is -included directly in the mode line. -@end defvar - -@defvar mode-name -This buffer-local variable holds the ``pretty'' name of the current -buffer's major mode. Each major mode should set this variable so that the -mode name will appear in the mode line. -@end defvar - -@defvar minor-mode-alist -This variable holds an association list whose elements specify how the -mode line should indicate that a minor mode is active. Each element of -the @code{minor-mode-alist} should be a two-element list: - -@example -(@var{minor-mode-variable} @var{mode-line-string}) -@end example - -More generally, @var{mode-line-string} can be any mode line spec. It -appears in the mode line when the value of @var{minor-mode-variable} is -non-@code{nil}, and not otherwise. These strings should begin with -spaces so that they don't run together. Conventionally, the -@var{minor-mode-variable} for a specific mode is set to a non-@code{nil} -value when that minor mode is activated. - -The default value of @code{minor-mode-alist} is: - -@example -@group -minor-mode-alist -@result{} ((vc-mode vc-mode) - (abbrev-mode " Abbrev") - (overwrite-mode overwrite-mode) - (auto-fill-function " Fill") - (defining-kbd-macro " Def") - (isearch-mode isearch-mode)) -@end group -@end example - -@code{minor-mode-alist} is not buffer-local. The variables mentioned -in the alist should be buffer-local if the minor mode can be enabled -separately in each buffer. -@end defvar - -@defvar mode-line-process -This buffer-local variable contains the mode line information on process -status in modes used for communicating with subprocesses. It is -displayed immediately following the major mode name, with no intervening -space. For example, its value in the @samp{*shell*} buffer is -@code{(":@: %s")}, which allows the shell to display its status along -with the major mode as: @samp{(Shell:@: run)}. Normally this variable -is @code{nil}. -@end defvar - -@defvar default-mode-line-format -This variable holds the default @code{mode-line-format} for buffers -that do not override it. This is the same as @code{(default-value -'mode-line-format)}. - -The default value of @code{default-mode-line-format} is: - -@example -@group -("" - mode-line-modified - mode-line-buffer-identification - " " - global-mode-string - " %[(" - mode-name -@end group -@group - mode-line-process - minor-mode-alist - "%n" - ")%]----" - (line-number-mode "L%l--") - (-3 . "%p") - "-%-") -@end group -@end example -@end defvar - -@defvar vc-mode -The variable @code{vc-mode}, local in each buffer, records whether the -buffer's visited file is maintained with version control, and, if so, -which kind. Its value is @code{nil} for no version control, or a string -that appears in the mode line. -@end defvar - -@node %-Constructs -@subsection @code{%}-Constructs in the Mode Line - - The following table lists the recognized @code{%}-constructs and what -they mean. In any construct except @samp{%%}, you can add a decimal -integer after the @samp{%} to specify how many characters to display. - -@table @code -@item %b -The current buffer name, obtained with the @code{buffer-name} function. -@xref{Buffer Names}. - -@item %f -The visited file name, obtained with the @code{buffer-file-name} -function. @xref{Buffer File Name}. - -@item %F -The name of the selected frame. - -@item %c -The current column number of point. - -@item %l -The current line number of point. - -@item %* -@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* -@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* -@samp{-} otherwise. @xref{Buffer Modification}. - -@item %+ -@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @* -@samp{%} if the buffer is read only (see @code{buffer-read-only}); @* -@samp{-} otherwise. This differs from @samp{%*} only for a modified -read-only buffer. @xref{Buffer Modification}. - -@item %& -@samp{*} if the buffer is modified, and @samp{-} otherwise. - -@item %s -The status of the subprocess belonging to the current buffer, obtained with -@code{process-status}. @xref{Process Information}. - -@item %t -Whether the visited file is a text file or a binary file. (This is a -meaningful distinction only on certain operating systems.) - -@item %p -The percentage of the buffer text above the @strong{top} of window, or -@samp{Top}, @samp{Bottom} or @samp{All}. - -@item %P -The percentage of the buffer text that is above the @strong{bottom} of -the window (which includes the text visible in the window, as well as -the text above the top), plus @samp{Top} if the top of the buffer is -visible on screen; or @samp{Bottom} or @samp{All}. - -@item %n -@samp{Narrow} when narrowing is in effect; nothing otherwise (see -@code{narrow-to-region} in @ref{Narrowing}). - -@item %[ -An indication of the depth of recursive editing levels (not counting -minibuffer levels): one @samp{[} for each editing level. -@xref{Recursive Editing}. - -@item %] -One @samp{]} for each recursive editing level (not counting minibuffer -levels). - -@item %% -The character @samp{%}---this is how to include a literal @samp{%} in a -string in which @code{%}-constructs are allowed. - -@item %- -Dashes sufficient to fill the remainder of the mode line. -@end table - -The following two @code{%}-constructs are still supported, but they are -obsolete, since you can get the same results with the variables -@code{mode-name} and @code{global-mode-string}. - -@table @code -@item %m -The value of @code{mode-name}. - -@item %M -The value of @code{global-mode-string}. Currently, only -@code{display-time} modifies the value of @code{global-mode-string}. -@end table - -@node Hooks -@section Hooks -@cindex hooks - - A @dfn{hook} is a variable where you can store a function or functions -to be called on a particular occasion by an existing program. Emacs -provides hooks for the sake of customization. Most often, hooks are set -up in the @file{.emacs} file, but Lisp programs can set them also. -@xref{Standard Hooks}, for a list of standard hook variables. - - Most of the hooks in Emacs are @dfn{normal hooks}. These variables -contain lists of functions to be called with no arguments. When the -hook name ends in @samp{-hook}, that tells you it is normal. We try to -make all hooks normal, as much as possible, so that you can use them in -a uniform way. - - Every major mode function is supposed to run a normal hook called the -@dfn{mode hook} as the last step of initialization. This makes it easy -for a user to customize the behavior of the mode, by overriding the -local variable assignments already made by the mode. But hooks are used -in other contexts too. For example, the hook @code{suspend-hook} runs -just before Emacs suspends itself (@pxref{Suspending Emacs}). - - The recommended way to add a hook function to a normal hook is by -calling @code{add-hook} (see below). The hook functions may be any of -the valid kinds of functions that @code{funcall} accepts (@pxref{What Is -a Function}). Most normal hook variables are initially void; -@code{add-hook} knows how to deal with this. - - If the hook variable's name does not end with @samp{-hook}, that -indicates it is probably an abnormal hook; you should look at its -documentation to see how to use the hook properly. - - If the variable's name ends in @samp{-functions} or @samp{-hooks}, -then the value is a list of functions, but it is abnormal in that either -these functions are called with arguments or their values are used in -some way. You can use @code{add-hook} to add a function to the list, -but you must take care in writing the function. (A few of these -variables are actually normal hooks which were named before we -established the convention of using @samp{-hook} for them.) - - If the variable's name ends in @samp{-function}, then its value -is just a single function, not a list of functions. - - Here's an expression that uses a mode hook to turn on Auto Fill mode -when in Lisp Interaction mode: - -@example -(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill) -@end example - - The next example shows how to use a hook to customize the way Emacs -formats C code. (People often have strong personal preferences for one -format or another.) Here the hook function is an anonymous lambda -expression. - -@cindex lambda expression in hook -@example -@group -(add-hook 'c-mode-hook - (function (lambda () - (setq c-indent-level 4 - c-argdecl-indent 0 - c-label-offset -4 -@end group -@group - c-continued-statement-indent 0 - c-brace-offset 0 - comment-column 40)))) - -(setq c++-mode-hook c-mode-hook) -@end group -@end example - - At the appropriate time, Emacs uses the @code{run-hooks} function to -run particular hooks. This function calls the hook functions that have -been added with @code{add-hook}. - -@defun run-hooks &rest hookvar -This function takes one or more hook variable names as arguments, and -runs each hook in turn. Each @var{hookvar} argument should be a symbol -that is a hook variable. These arguments are processed in the order -specified. - -If a hook variable has a non-@code{nil} value, that value may be a -function or a list of functions. If the value is a function (either a -lambda expression or a symbol with a function definition), it is -called. If it is a list, the elements are called, in order. -The hook functions are called with no arguments. - -For example, here's how @code{emacs-lisp-mode} runs its mode hook: - -@example -(run-hooks 'emacs-lisp-mode-hook) -@end example -@end defun - -@defun add-hook hook function &optional append local -This function is the handy way to add function @var{function} to hook -variable @var{hook}. The argument @var{function} may be any valid Lisp -function with the proper number of arguments. For example, - -@example -(add-hook 'text-mode-hook 'my-text-hook-function) -@end example - -@noindent -adds @code{my-text-hook-function} to the hook called @code{text-mode-hook}. - -You can use @code{add-hook} for abnormal hooks as well as for normal -hooks. - -It is best to design your hook functions so that the order in which they -are executed does not matter. Any dependence on the order is ``asking -for trouble.'' However, the order is predictable: normally, -@var{function} goes at the front of the hook list, so it will be -executed first (barring another @code{add-hook} call). - -If the optional argument @var{append} is non-@code{nil}, the new hook -function goes at the end of the hook list and will be executed last. - -If @var{local} is non-@code{nil}, that says to make the new hook -function local to the current buffer. Before you can do this, you must -make the hook itself buffer-local by calling @code{make-local-hook} -(@strong{not} @code{make-local-variable}). If the hook itself is not -buffer-local, then the value of @var{local} makes no difference---the -hook function is always global. -@end defun - -@defun remove-hook hook function &optional local -This function removes @var{function} from the hook variable @var{hook}. - -If @var{local} is non-@code{nil}, that says to remove @var{function} -from the local hook list instead of from the global hook list. If the -hook itself is not buffer-local, then the value of @var{local} makes no -difference. -@end defun - -@defun make-local-hook hook -This function makes the hook variable @code{hook} local to the current -buffer. When a hook variable is local, it can have local and global -hook functions, and @code{run-hooks} runs all of them. - -This function works by making @code{t} an element of the buffer-local -value. That serves as a flag to use the hook functions in the default -value of the hook variable as well as those in the local value. Since -@code{run-hooks} understands this flag, @code{make-local-hook} works -with all normal hooks. It works for only some non-normal hooks---those -whose callers have been updated to understand this meaning of @code{t}. - -Do not use @code{make-local-variable} directly for hook variables; it is -not sufficient. -@end defun diff --git a/lispref/numbers.texi b/lispref/numbers.texi deleted file mode 100644 index 6189e3da42f..00000000000 --- a/lispref/numbers.texi +++ /dev/null @@ -1,1034 +0,0 @@ -@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/numbers -@node Numbers, Strings and Characters, Lisp Data Types, Top -@chapter Numbers -@cindex integers -@cindex numbers - - GNU Emacs supports two numeric data types: @dfn{integers} and -@dfn{floating point numbers}. Integers are whole numbers such as -@minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point -numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or -2.71828. They can also be expressed in exponential notation: -1.5e2 equals 150; in this example, @samp{e2} stands for ten to the -second power, and is multiplied by 1.5. Floating point values are not -exact; they have a fixed, limited amount of precision. - - Support for floating point numbers is a new feature in Emacs 19, and it -is controlled by a separate compilation option, so you may encounter a site -where Emacs does not support them. - -@menu -* Integer Basics:: Representation and range of integers. -* Float Basics:: Representation and range of floating point. -* Predicates on Numbers:: Testing for numbers. -* Comparison of Numbers:: Equality and inequality predicates. -* Numeric Conversions:: Converting float to integer and vice versa. -* Arithmetic Operations:: How to add, subtract, multiply and divide. -* Rounding Operations:: Explicitly rounding floating point numbers. -* Bitwise Operations:: Logical and, or, not, shifting. -* Math Functions:: Trig, exponential and logarithmic functions. -* Random Numbers:: Obtaining random integers, predictable or not. -@end menu - -@node Integer Basics -@comment node-name, next, previous, up -@section Integer Basics - - The range of values for an integer depends on the machine. The -minimum range is @minus{}134217728 to 134217727 (28 bits; i.e., -@ifinfo --2**27 -@end ifinfo -@tex -$-2^{27}$ -@end tex -to -@ifinfo -2**27 - 1), -@end ifinfo -@tex -$2^{27}-1$), -@end tex -but some machines may provide a wider range. Many examples in this -chapter assume an integer has 28 bits. -@cindex overflow - - The Lisp reader reads an integer as a sequence of digits with optional -initial sign and optional final period. - -@example - 1 ; @r{The integer 1.} - 1. ; @r{The integer 1.} -+1 ; @r{Also the integer 1.} --1 ; @r{The integer @minus{}1.} - 268435457 ; @r{Also the integer 1, due to overflow.} - 0 ; @r{The integer 0.} --0 ; @r{The integer 0.} -@end example - - To understand how various functions work on integers, especially the -bitwise operators (@pxref{Bitwise Operations}), it is often helpful to -view the numbers in their binary form. - - In 28-bit binary, the decimal integer 5 looks like this: - -@example -0000 0000 0000 0000 0000 0000 0101 -@end example - -@noindent -(We have inserted spaces between groups of 4 bits, and two spaces -between groups of 8 bits, to make the binary integer easier to read.) - - The integer @minus{}1 looks like this: - -@example -1111 1111 1111 1111 1111 1111 1111 -@end example - -@noindent -@cindex two's complement -@minus{}1 is represented as 28 ones. (This is called @dfn{two's -complement} notation.) - - The negative integer, @minus{}5, is creating by subtracting 4 from -@minus{}1. In binary, the decimal integer 4 is 100. Consequently, -@minus{}5 looks like this: - -@example -1111 1111 1111 1111 1111 1111 1011 -@end example - - In this implementation, the largest 28-bit binary integer value is -134,217,727 in decimal. In binary, it looks like this: - -@example -0111 1111 1111 1111 1111 1111 1111 -@end example - - Since the arithmetic functions do not check whether integers go -outside their range, when you add 1 to 134,217,727, the value is the -negative integer @minus{}134,217,728: - -@example -(+ 1 134217727) - @result{} -134217728 - @result{} 1000 0000 0000 0000 0000 0000 0000 -@end example - - Many of the following functions accept markers for arguments as well -as integers. (@xref{Markers}.) More precisely, the actual arguments to -such functions may be either integers or markers, which is why we often -give these arguments the name @var{int-or-marker}. When the argument -value is a marker, its position value is used and its buffer is ignored. - -@ignore - In version 19, except where @emph{integer} is specified as an -argument, all of the functions for markers and integers also work for -floating point numbers. -@end ignore - -@node Float Basics -@section Floating Point Basics - -@cindex @code{LISP_FLOAT_TYPE} configuration macro - Emacs version 19 supports floating point numbers, if compiled with the -macro @code{LISP_FLOAT_TYPE} defined. The precise range of floating -point numbers is machine-specific; it is the same as the range of the C -data type @code{double} on the machine in question. - - The printed representation for floating point numbers requires either -a decimal point (with at least one digit following), an exponent, or -both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, -@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point -number whose value is 1500. They are all equivalent. You can also use -a minus sign to write negative floating point numbers, as in -@samp{-1.0}. - -@cindex IEEE floating point -@cindex positive infinity -@cindex negative infinity -@cindex infinity -@cindex NaN - Most modern computers support the IEEE floating point standard, which -provides for positive infinity and negative infinity as floating point -values. It also provides for a class of values called NaN or -``not-a-number''; numerical functions return such values in cases where -there is no correct answer. For example, @code{(sqrt -1.0)} returns a -NaN. For practical purposes, there's no significant difference between -different NaN values in Emacs Lisp, and there's no rule for precisely -which NaN value should be used in a particular case, so this manual -doesn't try to distinguish them. Emacs Lisp has no read syntax for NaNs -or infinities; perhaps we should create a syntax in the future. - - You can use @code{logb} to extract the binary exponent of a floating -point number (or estimate the logarithm of an integer): - -@defun logb number -This function returns the binary exponent of @var{number}. More -precisely, the value is the logarithm of @var{number} base 2, rounded -down to an integer. -@end defun - -@node Predicates on Numbers -@section Type Predicates for Numbers - - The functions in this section test whether the argument is a number or -whether it is a certain sort of number. The functions @code{integerp} -and @code{floatp} can take any type of Lisp object as argument (the -predicates would not be of much use otherwise); but the @code{zerop} -predicate requires a number as its argument. See also -@code{integer-or-marker-p} and @code{number-or-marker-p}, in -@ref{Predicates on Markers}. - -@defun floatp object -This predicate tests whether its argument is a floating point -number and returns @code{t} if so, @code{nil} otherwise. - -@code{floatp} does not exist in Emacs versions 18 and earlier. -@end defun - -@defun integerp object -This predicate tests whether its argument is an integer, and returns -@code{t} if so, @code{nil} otherwise. -@end defun - -@defun numberp object -This predicate tests whether its argument is a number (either integer or -floating point), and returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun wholenump object -@cindex natural numbers -The @code{wholenump} predicate (whose name comes from the phrase -``whole-number-p'') tests to see whether its argument is a nonnegative -integer, and returns @code{t} if so, @code{nil} otherwise. 0 is -considered non-negative. - -@findex natnump -@code{natnump} is an obsolete synonym for @code{wholenump}. -@end defun - -@defun zerop number -This predicate tests whether its argument is zero, and returns @code{t} -if so, @code{nil} otherwise. The argument must be a number. - -These two forms are equivalent: @code{(zerop x)} @equiv{} @code{(= x 0)}. -@end defun - -@node Comparison of Numbers -@section Comparison of Numbers -@cindex number equality - - To test numbers for numerical equality, you should normally use -@code{=}, not @code{eq}. There can be many distinct floating point -number objects with the same numeric value. If you use @code{eq} to -compare them, then you test whether two values are the same -@emph{object}. By contrast, @code{=} compares only the numeric values -of the objects. - - At present, each integer value has a unique Lisp object in Emacs Lisp. -Therefore, @code{eq} is equivalent @code{=} where integers are -concerned. It is sometimes convenient to use @code{eq} for comparing an -unknown value with an integer, because @code{eq} does not report an -error if the unknown value is not a number---it accepts arguments of any -type. By contrast, @code{=} signals an error if the arguments are not -numbers or markers. However, it is a good idea to use @code{=} if you -can, even for comparing integers, just in case we change the -representation of integers in a future Emacs version. - - There is another wrinkle: because floating point arithmetic is not -exact, it is often a bad idea to check for equality of two floating -point values. Usually it is better to test for approximate equality. -Here's a function to do this: - -@example -(defvar fuzz-factor 1.0e-6) -(defun approx-equal (x y) - (or (and (= x 0) (= y 0)) - (< (/ (abs (- x y)) - (max (abs x) (abs y))) - fuzz-factor))) -@end example - -@cindex CL note---integers vrs @code{eq} -@quotation -@b{Common Lisp note:} Comparing numbers in Common Lisp always requires -@code{=} because Common Lisp implements multi-word integers, and two -distinct integer objects can have the same numeric value. Emacs Lisp -can have just one integer object for any given value because it has a -limited range of integer values. -@end quotation - -@defun = number-or-marker1 number-or-marker2 -This function tests whether its arguments are numerically equal, and -returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun /= number-or-marker1 number-or-marker2 -This function tests whether its arguments are numerically equal, and -returns @code{t} if they are not, and @code{nil} if they are. -@end defun - -@defun < number-or-marker1 number-or-marker2 -This function tests whether its first argument is strictly less than -its second argument. It returns @code{t} if so, @code{nil} otherwise. -@end defun - -@defun <= number-or-marker1 number-or-marker2 -This function tests whether its first argument is less than or equal -to its second argument. It returns @code{t} if so, @code{nil} -otherwise. -@end defun - -@defun > number-or-marker1 number-or-marker2 -This function tests whether its first argument is strictly greater -than its second argument. It returns @code{t} if so, @code{nil} -otherwise. -@end defun - -@defun >= number-or-marker1 number-or-marker2 -This function tests whether its first argument is greater than or -equal to its second argument. It returns @code{t} if so, @code{nil} -otherwise. -@end defun - -@defun max number-or-marker &rest numbers-or-markers -This function returns the largest of its arguments. - -@example -(max 20) - @result{} 20 -(max 1 2.5) - @result{} 2.5 -(max 1 3 2.5) - @result{} 3 -@end example -@end defun - -@defun min number-or-marker &rest numbers-or-markers -This function returns the smallest of its arguments. - -@example -(min -4 1) - @result{} -4 -@end example -@end defun - -@node Numeric Conversions -@section Numeric Conversions -@cindex rounding in conversions - -To convert an integer to floating point, use the function @code{float}. - -@defun float number -This returns @var{number} converted to floating point. -If @var{number} is already a floating point number, @code{float} returns -it unchanged. -@end defun - -There are four functions to convert floating point numbers to integers; -they differ in how they round. These functions accept integer arguments -also, and return such arguments unchanged. - -@defun truncate number -This returns @var{number}, converted to an integer by rounding towards -zero. -@end defun - -@defun floor number &optional divisor -This returns @var{number}, converted to an integer by rounding downward -(towards negative infinity). - -If @var{divisor} is specified, @var{number} is divided by @var{divisor} -before the floor is taken; this is the division operation that -corresponds to @code{mod}. An @code{arith-error} results if -@var{divisor} is 0. -@end defun - -@defun ceiling number -This returns @var{number}, converted to an integer by rounding upward -(towards positive infinity). -@end defun - -@defun round number -This returns @var{number}, converted to an integer by rounding towards the -nearest integer. Rounding a value equidistant between two integers -may choose the integer closer to zero, or it may prefer an even integer, -depending on your machine. -@end defun - -@node Arithmetic Operations -@section Arithmetic Operations - - Emacs Lisp provides the traditional four arithmetic operations: -addition, subtraction, multiplication, and division. Remainder and modulus -functions supplement the division functions. The functions to -add or subtract 1 are provided because they are traditional in Lisp and -commonly used. - - All of these functions except @code{%} return a floating point value -if any argument is floating. - - It is important to note that in GNU Emacs Lisp, arithmetic functions -do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to -@minus{}134217728, depending on your hardware. - -@defun 1+ number-or-marker -This function returns @var{number-or-marker} plus 1. -For example, - -@example -(setq foo 4) - @result{} 4 -(1+ foo) - @result{} 5 -@end example - -This function is not analogous to the C operator @code{++}---it does not -increment a variable. It just computes a sum. Thus, if we continue, - -@example -foo - @result{} 4 -@end example - -If you want to increment the variable, you must use @code{setq}, -like this: - -@example -(setq foo (1+ foo)) - @result{} 5 -@end example -@end defun - -@defun 1- number-or-marker -This function returns @var{number-or-marker} minus 1. -@end defun - -@defun abs number -This returns the absolute value of @var{number}. -@end defun - -@defun + &rest numbers-or-markers -This function adds its arguments together. When given no arguments, -@code{+} returns 0. - -@example -(+) - @result{} 0 -(+ 1) - @result{} 1 -(+ 1 2 3 4) - @result{} 10 -@end example -@end defun - -@defun - &optional number-or-marker &rest other-numbers-or-markers -The @code{-} function serves two purposes: negation and subtraction. -When @code{-} has a single argument, the value is the negative of the -argument. When there are multiple arguments, @code{-} subtracts each of -the @var{other-numbers-or-markers} from @var{number-or-marker}, -cumulatively. If there are no arguments, the result is 0. - -@example -(- 10 1 2 3 4) - @result{} 0 -(- 10) - @result{} -10 -(-) - @result{} 0 -@end example -@end defun - -@defun * &rest numbers-or-markers -This function multiplies its arguments together, and returns the -product. When given no arguments, @code{*} returns 1. - -@example -(*) - @result{} 1 -(* 1) - @result{} 1 -(* 1 2 3 4) - @result{} 24 -@end example -@end defun - -@defun / dividend divisor &rest divisors -This function divides @var{dividend} by @var{divisor} and returns the -quotient. If there are additional arguments @var{divisors}, then it -divides @var{dividend} by each divisor in turn. Each argument may be a -number or a marker. - -If all the arguments are integers, then the result is an integer too. -This means the result has to be rounded. On most machines, the result -is rounded towards zero after each division, but some machines may round -differently with negative arguments. This is because the Lisp function -@code{/} is implemented using the C division operator, which also -permits machine-dependent rounding. As a practical matter, all known -machines round in the standard fashion. - -@cindex @code{arith-error} in division -If you divide by 0, an @code{arith-error} error is signaled. -(@xref{Errors}.) - -@example -@group -(/ 6 2) - @result{} 3 -@end group -(/ 5 2) - @result{} 2 -(/ 25 3 2) - @result{} 4 -(/ -17 6) - @result{} -2 -@end example - -The result of @code{(/ -17 6)} could in principle be -3 on some -machines. -@end defun - -@defun % dividend divisor -@cindex remainder -This function returns the integer remainder after division of @var{dividend} -by @var{divisor}. The arguments must be integers or markers. - -For negative arguments, the remainder is in principle machine-dependent -since the quotient is; but in practice, all known machines behave alike. - -An @code{arith-error} results if @var{divisor} is 0. - -@example -(% 9 4) - @result{} 1 -(% -9 4) - @result{} -1 -(% 9 -4) - @result{} 1 -(% -9 -4) - @result{} -1 -@end example - -For any two integers @var{dividend} and @var{divisor}, - -@example -@group -(+ (% @var{dividend} @var{divisor}) - (* (/ @var{dividend} @var{divisor}) @var{divisor})) -@end group -@end example - -@noindent -always equals @var{dividend}. -@end defun - -@defun mod dividend divisor -@cindex modulus -This function returns the value of @var{dividend} modulo @var{divisor}; -in other words, the remainder after division of @var{dividend} -by @var{divisor}, but with the same sign as @var{divisor}. -The arguments must be numbers or markers. - -Unlike @code{%}, @code{mod} returns a well-defined result for negative -arguments. It also permits floating point arguments; it rounds the -quotient downward (towards minus infinity) to an integer, and uses that -quotient to compute the remainder. - -An @code{arith-error} results if @var{divisor} is 0. - -@example -@group -(mod 9 4) - @result{} 1 -@end group -@group -(mod -9 4) - @result{} 3 -@end group -@group -(mod 9 -4) - @result{} -3 -@end group -@group -(mod -9 -4) - @result{} -1 -@end group -@group -(mod 5.5 2.5) - @result{} .5 -@end group -@end example - -For any two numbers @var{dividend} and @var{divisor}, - -@example -@group -(+ (mod @var{dividend} @var{divisor}) - (* (floor @var{dividend} @var{divisor}) @var{divisor})) -@end group -@end example - -@noindent -always equals @var{dividend}, subject to rounding error if either -argument is floating point. For @code{floor}, see @ref{Numeric -Conversions}. -@end defun - -@node Rounding Operations -@section Rounding Operations -@cindex rounding without conversion - -The functions @code{ffloor}, @code{fceiling}, @code{fround} and -@code{ftruncate} take a floating point argument and return a floating -point result whose value is a nearby integer. @code{ffloor} returns the -nearest integer below; @code{fceiling}, the nearest integer above; -@code{ftruncate}, the nearest integer in the direction towards zero; -@code{fround}, the nearest integer. - -@defun ffloor float -This function rounds @var{float} to the next lower integral value, and -returns that value as a floating point number. -@end defun - -@defun fceiling float -This function rounds @var{float} to the next higher integral value, and -returns that value as a floating point number. -@end defun - -@defun ftruncate float -This function rounds @var{float} towards zero to an integral value, and -returns that value as a floating point number. -@end defun - -@defun fround float -This function rounds @var{float} to the nearest integral value, -and returns that value as a floating point number. -@end defun - -@node Bitwise Operations -@section Bitwise Operations on Integers - - In a computer, an integer is represented as a binary number, a -sequence of @dfn{bits} (digits which are either zero or one). A bitwise -operation acts on the individual bits of such a sequence. For example, -@dfn{shifting} moves the whole sequence left or right one or more places, -reproducing the same pattern ``moved over''. - - The bitwise operations in Emacs Lisp apply only to integers. - -@defun lsh integer1 count -@cindex logical shift -@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the -bits in @var{integer1} to the left @var{count} places, or to the right -if @var{count} is negative, bringing zeros into the vacated bits. If -@var{count} is negative, @code{lsh} shifts zeros into the leftmost -(most-significant) bit, producing a positive result even if -@var{integer1} is negative. Contrast this with @code{ash}, below. - -Here are two examples of @code{lsh}, shifting a pattern of bits one -place to the left. We show only the low-order eight bits of the binary -pattern; the rest are all zero. - -@example -@group -(lsh 5 1) - @result{} 10 -;; @r{Decimal 5 becomes decimal 10.} -00000101 @result{} 00001010 - -(lsh 7 1) - @result{} 14 -;; @r{Decimal 7 becomes decimal 14.} -00000111 @result{} 00001110 -@end group -@end example - -@noindent -As the examples illustrate, shifting the pattern of bits one place to -the left produces a number that is twice the value of the previous -number. - -Shifting a pattern of bits two places to the left produces results -like this (with 8-bit binary numbers): - -@example -@group -(lsh 3 2) - @result{} 12 -;; @r{Decimal 3 becomes decimal 12.} -00000011 @result{} 00001100 -@end group -@end example - -On the other hand, shifting one place to the right looks like this: - -@example -@group -(lsh 6 -1) - @result{} 3 -;; @r{Decimal 6 becomes decimal 3.} -00000110 @result{} 00000011 -@end group - -@group -(lsh 5 -1) - @result{} 2 -;; @r{Decimal 5 becomes decimal 2.} -00000101 @result{} 00000010 -@end group -@end example - -@noindent -As the example illustrates, shifting one place to the right divides the -value of a positive integer by two, rounding downward. - -The function @code{lsh}, like all Emacs Lisp arithmetic functions, does -not check for overflow, so shifting left can discard significant bits -and change the sign of the number. For example, left shifting -134,217,727 produces @minus{}2 on a 28-bit machine: - -@example -(lsh 134217727 1) ; @r{left shift} - @result{} -2 -@end example - -In binary, in the 28-bit implementation, the argument looks like this: - -@example -@group -;; @r{Decimal 134,217,727} -0111 1111 1111 1111 1111 1111 1111 -@end group -@end example - -@noindent -which becomes the following when left shifted: - -@example -@group -;; @r{Decimal @minus{}2} -1111 1111 1111 1111 1111 1111 1110 -@end group -@end example -@end defun - -@defun ash integer1 count -@cindex arithmetic shift -@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} -to the left @var{count} places, or to the right if @var{count} -is negative. - -@code{ash} gives the same results as @code{lsh} except when -@var{integer1} and @var{count} are both negative. In that case, -@code{ash} puts ones in the empty bit positions on the left, while -@code{lsh} puts zeros in those bit positions. - -Thus, with @code{ash}, shifting the pattern of bits one place to the right -looks like this: - -@example -@group -(ash -6 -1) @result{} -3 -;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} -1111 1111 1111 1111 1111 1111 1010 - @result{} -1111 1111 1111 1111 1111 1111 1101 -@end group -@end example - -In contrast, shifting the pattern of bits one place to the right with -@code{lsh} looks like this: - -@example -@group -(lsh -6 -1) @result{} 134217725 -;; @r{Decimal @minus{}6 becomes decimal 134,217,725.} -1111 1111 1111 1111 1111 1111 1010 - @result{} -0111 1111 1111 1111 1111 1111 1101 -@end group -@end example - -Here are other examples: - -@c !!! Check if lined up in smallbook format! XDVI shows problem -@c with smallbook but not with regular book! --rjc 16mar92 -@smallexample -@group - ; @r{ 28-bit binary values} - -(lsh 5 2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} - @result{} 20 ; = @r{0000 0000 0000 0000 0000 0001 0100} -@end group -@group -(ash 5 2) - @result{} 20 -(lsh -5 2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011} - @result{} -20 ; = @r{1111 1111 1111 1111 1111 1110 1100} -(ash -5 2) - @result{} -20 -@end group -@group -(lsh 5 -2) ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} - @result{} 1 ; = @r{0000 0000 0000 0000 0000 0000 0001} -@end group -@group -(ash 5 -2) - @result{} 1 -@end group -@group -(lsh -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011} - @result{} 4194302 ; = @r{0011 1111 1111 1111 1111 1111 1110} -@end group -@group -(ash -5 -2) ; -5 = @r{1111 1111 1111 1111 1111 1111 1011} - @result{} -2 ; = @r{1111 1111 1111 1111 1111 1111 1110} -@end group -@end smallexample -@end defun - -@defun logand &rest ints-or-markers -@cindex logical and -@cindex bitwise and -This function returns the ``logical and'' of the arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in all the arguments. (``Set'' means that the value of the bit is 1 -rather than 0.) - -For example, using 4-bit binary numbers, the ``logical and'' of 13 and -12 is 12: 1101 combined with 1100 produces 1100. -In both the binary numbers, the leftmost two bits are set (i.e., they -are 1's), so the leftmost two bits of the returned value are set. -However, for the rightmost two bits, each is zero in at least one of -the arguments, so the rightmost two bits of the returned value are 0's. - -@noindent -Therefore, - -@example -@group -(logand 13 12) - @result{} 12 -@end group -@end example - -If @code{logand} is not passed any argument, it returns a value of -@minus{}1. This number is an identity element for @code{logand} -because its binary representation consists entirely of ones. If -@code{logand} is passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 28-bit binary values} - -(logand 14 13) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} - ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} - @result{} 12 ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} -@end group - -@group -(logand 14 13 4) ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} - ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} - ; 4 = @r{0000 0000 0000 0000 0000 0000 0100} - @result{} 4 ; 4 = @r{0000 0000 0000 0000 0000 0000 0100} -@end group - -@group -(logand) - @result{} -1 ; -1 = @r{1111 1111 1111 1111 1111 1111 1111} -@end group -@end smallexample -@end defun - -@defun logior &rest ints-or-markers -@cindex logical inclusive or -@cindex bitwise or -This function returns the ``inclusive or'' of its arguments: the @var{n}th bit -is set in the result if, and only if, the @var{n}th bit is set in at least -one of the arguments. If there are no arguments, the result is zero, -which is an identity element for this operation. If @code{logior} is -passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 28-bit binary values} - -(logior 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} - @result{} 13 ; 13 = @r{0000 0000 0000 0000 0000 0000 1101} -@end group - -@group -(logior 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} - ; 7 = @r{0000 0000 0000 0000 0000 0000 0111} - @result{} 15 ; 15 = @r{0000 0000 0000 0000 0000 0000 1111} -@end group -@end smallexample -@end defun - -@defun logxor &rest ints-or-markers -@cindex bitwise exclusive or -@cindex logical exclusive or -This function returns the ``exclusive or'' of its arguments: the -@var{n}th bit is set in the result if, and only if, the @var{n}th bit is -set in an odd number of the arguments. If there are no arguments, the -result is 0, which is an identity element for this operation. If -@code{logxor} is passed just one argument, it returns that argument. - -@smallexample -@group - ; @r{ 28-bit binary values} - -(logxor 12 5) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} - @result{} 9 ; 9 = @r{0000 0000 0000 0000 0000 0000 1001} -@end group - -@group -(logxor 12 5 7) ; 12 = @r{0000 0000 0000 0000 0000 0000 1100} - ; 5 = @r{0000 0000 0000 0000 0000 0000 0101} - ; 7 = @r{0000 0000 0000 0000 0000 0000 0111} - @result{} 14 ; 14 = @r{0000 0000 0000 0000 0000 0000 1110} -@end group -@end smallexample -@end defun - -@defun lognot integer -@cindex logical not -@cindex bitwise not -This function returns the logical complement of its argument: the @var{n}th -bit is one in the result if, and only if, the @var{n}th bit is zero in -@var{integer}, and vice-versa. - -@example -(lognot 5) - @result{} -6 -;; 5 = @r{0000 0000 0000 0000 0000 0000 0101} -;; @r{becomes} -;; -6 = @r{1111 1111 1111 1111 1111 1111 1010} -@end example -@end defun - -@node Math Functions -@section Standard Mathematical Functions -@cindex transcendental functions -@cindex mathematical functions - -These mathematical functions are available if floating point is -supported. They allow integers as well as floating point numbers -as arguments. - -@defun sin arg -@defunx cos arg -@defunx tan arg -These are the ordinary trigonometric functions, with argument measured -in radians. -@end defun - -@defun asin arg -The value of @code{(asin @var{arg})} is a number between @minus{}pi/2 -and pi/2 (inclusive) whose sine is @var{arg}; if, however, @var{arg} -is out of range (outside [-1, 1]), then the result is a NaN. -@end defun - -@defun acos arg -The value of @code{(acos @var{arg})} is a number between 0 and pi -(inclusive) whose cosine is @var{arg}; if, however, @var{arg} -is out of range (outside [-1, 1]), then the result is a NaN. -@end defun - -@defun atan arg -The value of @code{(atan @var{arg})} is a number between @minus{}pi/2 -and pi/2 (exclusive) whose tangent is @var{arg}. -@end defun - -@defun exp arg -This is the exponential function; it returns @i{e} to the power -@var{arg}. @i{e} is a fundamental mathematical constant also called the -base of natural logarithms. -@end defun - -@defun log arg &optional base -This function returns the logarithm of @var{arg}, with base @var{base}. -If you don't specify @var{base}, the base @var{e} is used. If @var{arg} -is negative, the result is a NaN. -@end defun - -@ignore -@defun expm1 arg -This function returns @code{(1- (exp @var{arg}))}, but it is more -accurate than that when @var{arg} is negative and @code{(exp @var{arg})} -is close to 1. -@end defun - -@defun log1p arg -This function returns @code{(log (1+ @var{arg}))}, but it is more -accurate than that when @var{arg} is so small that adding 1 to it would -lose accuracy. -@end defun -@end ignore - -@defun log10 arg -This function returns the logarithm of @var{arg}, with base 10. If -@var{arg} is negative, the result is a NaN. @code{(log10 @var{x})} -@equiv{} @code{(log @var{x} 10)}, at least approximately. -@end defun - -@defun expt x y -This function returns @var{x} raised to power @var{y}. If both -arguments are integers and @var{y} is positive, the result is an -integer; in this case, it is truncated to fit the range of possible -integer values. -@end defun - -@defun sqrt arg -This returns the square root of @var{arg}. If @var{arg} is negative, -the value is a NaN. -@end defun - -@node Random Numbers -@section Random Numbers -@cindex random numbers - -A deterministic computer program cannot generate true random numbers. -For most purposes, @dfn{pseudo-random numbers} suffice. A series of -pseudo-random numbers is generated in a deterministic fashion. The -numbers are not truly random, but they have certain properties that -mimic a random series. For example, all possible values occur equally -often in a pseudo-random series. - -In Emacs, pseudo-random numbers are generated from a ``seed'' number. -Starting from any given seed, the @code{random} function always -generates the same sequence of numbers. Emacs always starts with the -same seed value, so the sequence of values of @code{random} is actually -the same in each Emacs run! For example, in one operating system, the -first call to @code{(random)} after you start Emacs always returns --1457731, and the second one always returns -7692030. This -repeatability is helpful for debugging. - -If you want truly unpredictable random numbers, execute @code{(random -t)}. This chooses a new seed based on the current time of day and on -Emacs's process @sc{id} number. - -@defun random &optional limit -This function returns a pseudo-random integer. Repeated calls return a -series of pseudo-random integers. - -If @var{limit} is a positive integer, the value is chosen to be -nonnegative and less than @var{limit}. - -If @var{limit} is @code{t}, it means to choose a new seed based on the -current time of day and on Emacs's process @sc{id} number. -@c "Emacs'" is incorrect usage! - -On some machines, any integer representable in Lisp may be the result -of @code{random}. On other machines, the result can never be larger -than a certain maximum or less than a certain (negative) minimum. -@end defun diff --git a/lispref/objects.texi b/lispref/objects.texi deleted file mode 100644 index 78412e2c312..00000000000 --- a/lispref/objects.texi +++ /dev/null @@ -1,1592 +0,0 @@ -@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/objects -@node Lisp Data Types, Numbers, Introduction, Top -@chapter Lisp Data Types -@cindex object -@cindex Lisp object -@cindex type -@cindex data type - - A Lisp @dfn{object} is a piece of data used and manipulated by Lisp -programs. For our purposes, a @dfn{type} or @dfn{data type} is a set of -possible objects. - - Every object belongs to at least one type. Objects of the same type -have similar structures and may usually be used in the same contexts. -Types can overlap, and objects can belong to two or more types. -Consequently, we can ask whether an object belongs to a particular type, -but not for ``the'' type of an object. - -@cindex primitive type - A few fundamental object types are built into Emacs. These, from -which all other types are constructed, are called @dfn{primitive -types}. Each object belongs to one and only one primitive type. These -types include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol}, -@dfn{string}, @dfn{vector}, @dfn{subr}, @dfn{byte-code function}, and -several special types, such as @dfn{buffer}, that are related to -editing. (@xref{Editing Types}.) - - Each primitive type has a corresponding Lisp function that checks -whether an object is a member of that type. - - Note that Lisp is unlike many other languages in that Lisp objects are -@dfn{self-typing}: the primitive type of the object is implicit in the -object itself. For example, if an object is a vector, nothing can treat -it as a number; Lisp knows it is a vector, not a number. - - In most languages, the programmer must declare the data type of each -variable, and the type is known by the compiler but not represented in -the data. Such type declarations do not exist in Emacs Lisp. A Lisp -variable can have any type of value, and it remembers whatever value -you store in it, type and all. - - This chapter describes the purpose, printed representation, and read -syntax of each of the standard types in GNU Emacs Lisp. Details on how -to use these types can be found in later chapters. - -@menu -* Printed Representation:: How Lisp objects are represented as text. -* Comments:: Comments and their formatting conventions. -* Programming Types:: Types found in all Lisp systems. -* Editing Types:: Types specific to Emacs. -* Type Predicates:: Tests related to types. -* Equality Predicates:: Tests of equality between any two objects. -@end menu - -@node Printed Representation -@comment node-name, next, previous, up -@section Printed Representation and Read Syntax -@cindex printed representation -@cindex read syntax - - The @dfn{printed representation} of an object is the format of the -output generated by the Lisp printer (the function @code{prin1}) for -that object. The @dfn{read syntax} of an object is the format of the -input accepted by the Lisp reader (the function @code{read}) for that -object. Most objects have more than one possible read syntax. Some -types of object have no read syntax; except for these cases, the printed -representation of an object is also a read syntax for it. - - In other languages, an expression is text; it has no other form. In -Lisp, an expression is primarily a Lisp object and only secondarily the -text that is the object's read syntax. Often there is no need to -emphasize this distinction, but you must keep it in the back of your -mind, or you will occasionally be very confused. - -@cindex hash notation - Every type has a printed representation. Some types have no read -syntax, since it may not make sense to enter objects of these types -directly in a Lisp program. For example, the buffer type does not have -a read syntax. Objects of these types are printed in @dfn{hash -notation}: the characters @samp{#<} followed by a descriptive string -(typically the type name followed by the name of the object), and closed -with a matching @samp{>}. Hash notation cannot be read at all, so the -Lisp reader signals the error @code{invalid-read-syntax} whenever it -encounters @samp{#<}. -@kindex invalid-read-syntax - -@example -(current-buffer) - @result{} #<buffer objects.texi> -@end example - - When you evaluate an expression interactively, the Lisp interpreter -first reads the textual representation of it, producing a Lisp object, -and then evaluates that object (@pxref{Evaluation}). However, -evaluation and reading are separate activities. Reading returns the -Lisp object represented by the text that is read; the object may or may -not be evaluated later. @xref{Input Functions}, for a description of -@code{read}, the basic function for reading objects. - -@node Comments -@comment node-name, next, previous, up -@section Comments -@cindex comments -@cindex @samp{;} in comment - - A @dfn{comment} is text that is written in a program only for the sake -of humans that read the program, and that has no effect on the meaning -of the program. In Lisp, a semicolon (@samp{;}) starts a comment if it -is not within a string or character constant. The comment continues to -the end of line. The Lisp reader discards comments; they do not become -part of the Lisp objects which represent the program within the Lisp -system. - - The @samp{#@@@var{count}} construct, which skips the next @var{count} -characters, is useful for program-generated comments containing binary -data. The Emacs Lisp byte compiler uses this in its output files -(@pxref{Byte Compilation}). It isn't meant for source files, however. - - @xref{Comment Tips}, for conventions for formatting comments. - -@node Programming Types -@section Programming Types -@cindex programming types - - There are two general categories of types in Emacs Lisp: those having -to do with Lisp programming, and those having to do with editing. The -former exist in many Lisp implementations, in one form or another. The -latter are unique to Emacs Lisp. - -@menu -* Integer Type:: Numbers without fractional parts. -* Floating Point Type:: Numbers with fractional parts and with a large range. -* Character Type:: The representation of letters, numbers and - control characters. -* Symbol Type:: A multi-use object that refers to a function, - variable, or property list, and has a unique identity. -* Sequence Type:: Both lists and arrays are classified as sequences. -* Cons Cell Type:: Cons cells, and lists (which are made from cons cells). -* Array Type:: Arrays include strings and vectors. -* String Type:: An (efficient) array of characters. -* Vector Type:: One-dimensional arrays. -* Function Type:: A piece of executable code you can call from elsewhere. -* Macro Type:: A method of expanding an expression into another - expression, more fundamental but less pretty. -* Primitive Function Type:: A function written in C, callable from Lisp. -* Byte-Code Type:: A function written in Lisp, then compiled. -* Autoload Type:: A type used for automatically loading seldom-used - functions. -@end menu - -@node Integer Type -@subsection Integer Type - - The range of values for integers in Emacs Lisp is @minus{}134217728 to -134217727 (28 bits; i.e., -@ifinfo --2**27 -@end ifinfo -@tex -$-2^{27}$ -@end tex -to -@ifinfo -2**27 - 1) -@end ifinfo -@tex -$2^{28}-1$) -@end tex -on most machines. (Some machines may provide a wider range.) It is -important to note that the Emacs Lisp arithmetic functions do not check -for overflow. Thus @code{(1+ 134217727)} is @minus{}134217728 on most -machines. - - The read syntax for integers is a sequence of (base ten) digits with an -optional sign at the beginning and an optional period at the end. The -printed representation produced by the Lisp interpreter never has a -leading @samp{+} or a final @samp{.}. - -@example -@group --1 ; @r{The integer -1.} -1 ; @r{The integer 1.} -1. ; @r{Also The integer 1.} -+1 ; @r{Also the integer 1.} -268435457 ; @r{Also the integer 1!} - ; @r{ (on a 28-bit implementation)} -@end group -@end example - - @xref{Numbers}, for more information. - -@node Floating Point Type -@subsection Floating Point Type - - Emacs version 19 supports floating point numbers (though there is a -compilation option to disable them). The precise range of floating -point numbers is machine-specific. - - The printed representation for floating point numbers requires either -a decimal point (with at least one digit following), an exponent, or -both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, -@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point -number whose value is 1500. They are all equivalent. - - @xref{Numbers}, for more information. - -@node Character Type -@subsection Character Type -@cindex @sc{ASCII} character codes - - A @dfn{character} in Emacs Lisp is nothing more than an integer. In -other words, characters are represented by their character codes. For -example, the character @kbd{A} is represented as the @w{integer 65}. - - Individual characters are not often used in programs. It is far more -common to work with @emph{strings}, which are sequences composed of -characters. @xref{String Type}. - - Characters in strings, buffers, and files are currently limited to the -range of 0 to 255---eight bits. If you store a larger integer into a -string, buffer or file, it is truncated to that range. Characters that -represent keyboard input have a much wider range. - -@cindex read syntax for characters -@cindex printed representation for characters -@cindex syntax for characters - Since characters are really integers, the printed representation of a -character is a decimal number. This is also a possible read syntax for -a character, but writing characters that way in Lisp programs is a very -bad idea. You should @emph{always} use the special read syntax formats -that Emacs Lisp provides for characters. These syntax formats start -with a question mark. - - The usual read syntax for alphanumeric characters is a question mark -followed by the character; thus, @samp{?A} for the character -@kbd{A}, @samp{?B} for the character @kbd{B}, and @samp{?a} for the -character @kbd{a}. - - For example: - -@example -?Q @result{} 81 ?q @result{} 113 -@end example - - You can use the same syntax for punctuation characters, but it is -often a good idea to add a @samp{\} so that the Emacs commands for -editing Lisp code don't get confused. For example, @samp{?\ } is the -way to write the space character. If the character is @samp{\}, you -@emph{must} use a second @samp{\} to quote it: @samp{?\\}. - -@cindex whitespace -@cindex bell character -@cindex @samp{\a} -@cindex backspace -@cindex @samp{\b} -@cindex tab -@cindex @samp{\t} -@cindex vertical tab -@cindex @samp{\v} -@cindex formfeed -@cindex @samp{\f} -@cindex newline -@cindex @samp{\n} -@cindex return -@cindex @samp{\r} -@cindex escape -@cindex @samp{\e} - You can express the characters Control-g, backspace, tab, newline, -vertical tab, formfeed, return, and escape as @samp{?\a}, @samp{?\b}, -@samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e}, -respectively. Those values are 7, 8, 9, 10, 11, 12, 13, and 27 in -decimal. Thus, - -@example -?\a @result{} 7 ; @r{@kbd{C-g}} -?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}} -?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}} -?\n @result{} 10 ; @r{newline, @key{LFD}, @kbd{C-j}} -?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}} -?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}} -?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}} -?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}} -?\\ @result{} 92 ; @r{backslash character, @kbd{\}} -@end example - -@cindex escape sequence - These sequences which start with backslash are also known as -@dfn{escape sequences}, because backslash plays the role of an escape -character; this usage has nothing to do with the character @key{ESC}. - -@cindex control characters - Control characters may be represented using yet another read syntax. -This consists of a question mark followed by a backslash, caret, and the -corresponding non-control character, in either upper or lower case. For -example, both @samp{?\^I} and @samp{?\^i} are valid read syntax for the -character @kbd{C-i}, the character whose value is 9. - - Instead of the @samp{^}, you can use @samp{C-}; thus, @samp{?\C-i} is -equivalent to @samp{?\^I} and to @samp{?\^i}: - -@example -?\^I @result{} 9 ?\C-I @result{} 9 -@end example - - For use in strings and buffers, you are limited to the control -characters that exist in @sc{ASCII}, but for keyboard input purposes, -you can turn any character into a control character with @samp{C-}. The -character codes for these non-@sc{ASCII} control characters include the -@iftex -$2^{26}$ -@end iftex -@ifinfo -2**26 -@end ifinfo -bit as well as the code for the corresponding non-control -character. Ordinary terminals have no way of generating non-@sc{ASCII} -control characters, but you can generate them straightforwardly using an -X terminal. - - For historical reasons, Emacs treats the @key{DEL} character as -the control equivalent of @kbd{?}: - -@example -?\^? @result{} 127 ?\C-? @result{} 127 -@end example - -@noindent -As a result, it is currently not possible to represent the character -@kbd{Control-?}, which is a meaningful input character under X. It is -not easy to change this as various Lisp files refer to @key{DEL} in this -way. - - For representing control characters to be found in files or strings, -we recommend the @samp{^} syntax; for control characters in keyboard -input, we prefer the @samp{C-} syntax. This does not affect the meaning -of the program, but may guide the understanding of people who read it. - -@cindex meta characters - A @dfn{meta character} is a character typed with the @key{META} -modifier key. The integer that represents such a character has the -@iftex -$2^{27}$ -@end iftex -@ifinfo -2**27 -@end ifinfo -bit set (which on most machines makes it a negative number). We -use high bits for this and other modifiers to make possible a wide range -of basic character codes. - - In a string, the -@iftex -$2^{7}$ -@end iftex -@ifinfo -2**7 -@end ifinfo -bit indicates a meta character, so the meta -characters that can fit in a string have codes in the range from 128 to -255, and are the meta versions of the ordinary @sc{ASCII} characters. -(In Emacs versions 18 and older, this convention was used for characters -outside of strings as well.) - - The read syntax for meta characters uses @samp{\M-}. For example, -@samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with -octal character codes (see below), with @samp{\C-}, or with any other -syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A}, -or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as -@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}. - - The case of an ordinary letter is indicated by its character code as -part of @sc{ASCII}, but @sc{ASCII} has no way to represent whether a -control character is upper case or lower case. Emacs uses the -@iftex -$2^{25}$ -@end iftex -@ifinfo -2**25 -@end ifinfo -bit to indicate that the shift key was used for typing a control -character. This distinction is possible only when you use X terminals -or other special terminals; ordinary terminals do not indicate the -distinction to the computer in any way. - -@cindex hyper characters -@cindex super characters -@cindex alt characters - The X Window System defines three other modifier bits that can be set -in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes -for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus, -@samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}. -@iftex -Numerically, the -bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper. -@end iftex -@ifinfo -Numerically, the -bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper. -@end ifinfo - -@cindex @samp{?} in character constant -@cindex question mark in character constant -@cindex @samp{\} in character constant -@cindex backslash in character constant -@cindex octal character code - Finally, the most general read syntax consists of a question mark -followed by a backslash and the character code in octal (up to three -octal digits); thus, @samp{?\101} for the character @kbd{A}, -@samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the -character @kbd{C-b}. Although this syntax can represent any @sc{ASCII} -character, it is preferred only when the precise octal value is more -important than the @sc{ASCII} representation. - -@example -@group -?\012 @result{} 10 ?\n @result{} 10 ?\C-j @result{} 10 -?\101 @result{} 65 ?A @result{} 65 -@end group -@end example - - A backslash is allowed, and harmless, preceding any character without -a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}. -There is no reason to add a backslash before most characters. However, -you should add a backslash before any of the characters -@samp{()\|;'`"#.,} to avoid confusing the Emacs commands for editing -Lisp code. Also add a backslash before whitespace characters such as -space, tab, newline and formfeed. However, it is cleaner to use one of -the easily readable escape sequences, such as @samp{\t}, instead of an -actual whitespace character such as a tab. - -@node Symbol Type -@subsection Symbol Type - - A @dfn{symbol} in GNU Emacs Lisp is an object with a name. The symbol -name serves as the printed representation of the symbol. In ordinary -use, the name is unique---no two symbols have the same name. - - A symbol can serve as a variable, as a function name, or to hold a -property list. Or it may serve only to be distinct from all other Lisp -objects, so that its presence in a data structure may be recognized -reliably. In a given context, usually only one of these uses is -intended. But you can use one symbol in all of these ways, -independently. - -@cindex @samp{\} in symbols -@cindex backslash in symbols - A symbol name can contain any characters whatever. Most symbol names -are written with letters, digits, and the punctuation characters -@samp{-+=*/}. Such names require no special punctuation; the characters -of the name suffice as long as the name does not look like a number. -(If it does, write a @samp{\} at the beginning of the name to force -interpretation as a symbol.) The characters @samp{_~!@@$%^&:<>@{@}} are -less often used but also require no special punctuation. Any other -characters may be included in a symbol's name by escaping them with a -backslash. In contrast to its use in strings, however, a backslash in -the name of a symbol simply quotes the single character that follows the -backslash. For example, in a string, @samp{\t} represents a tab -character; in the name of a symbol, however, @samp{\t} merely quotes the -letter @kbd{t}. To have a symbol with a tab character in its name, you -must actually use a tab (preceded with a backslash). But it's rare to -do such a thing. - -@cindex CL note---case of letters -@quotation -@b{Common Lisp note:} In Common Lisp, lower case letters are always -``folded'' to upper case, unless they are explicitly escaped. In Emacs -Lisp, upper case and lower case letters are distinct. -@end quotation - - Here are several examples of symbol names. Note that the @samp{+} in -the fifth example is escaped to prevent it from being read as a number. -This is not necessary in the sixth example because the rest of the name -makes it invalid as a number. - -@example -@group -foo ; @r{A symbol named @samp{foo}.} -FOO ; @r{A symbol named @samp{FOO}, different from @samp{foo}.} -char-to-string ; @r{A symbol named @samp{char-to-string}.} -@end group -@group -1+ ; @r{A symbol named @samp{1+}} - ; @r{(not @samp{+1}, which is an integer).} -@end group -@group -\+1 ; @r{A symbol named @samp{+1}} - ; @r{(not a very readable name).} -@end group -@group -\(*\ 1\ 2\) ; @r{A symbol named @samp{(* 1 2)} (a worse name).} -@c the @'s in this next line use up three characters, hence the -@c apparent misalignment of the comment. -+-*/_~!@@$%^&=:<>@{@} ; @r{A symbol named @samp{+-*/_~!@@$%^&=:<>@{@}}.} - ; @r{These characters need not be escaped.} -@end group -@end example - -@node Sequence Type -@subsection Sequence Types - - A @dfn{sequence} is a Lisp object that represents an ordered set of -elements. There are two kinds of sequence in Emacs Lisp, lists and -arrays. Thus, an object of type list or of type array is also -considered a sequence. - - Arrays are further subdivided into strings and vectors. Vectors can -hold elements of any type, but string elements must be characters in the -range from 0 to 255. However, the characters in a string can have text -properties like characters in a buffer (@pxref{Text Properties}); -vectors do not support text properties even when their elements happen -to be characters. - - Lists, strings and vectors are different, but they have important -similarities. For example, all have a length @var{l}, and all have -elements which can be indexed from zero to @var{l} minus one. Also, -several functions, called sequence functions, accept any kind of -sequence. For example, the function @code{elt} can be used to extract -an element of a sequence, given its index. @xref{Sequences Arrays -Vectors}. - - It is impossible to read the same sequence twice, since sequences are -always created anew upon reading. If you read the read syntax for a -sequence twice, you get two sequences with equal contents. There is one -exception: the empty list @code{()} always stands for the same object, -@code{nil}. - -@node Cons Cell Type -@subsection Cons Cell and List Types -@cindex address field of register -@cindex decrement field of register - - A @dfn{cons cell} is an object comprising two pointers named the -@sc{car} and the @sc{cdr}. Each of them can point to any Lisp object. - - A @dfn{list} is a series of cons cells, linked together so that the -@sc{cdr} of each cons cell points either to another cons cell or to the -empty list. @xref{Lists}, for functions that work on lists. Because -most cons cells are used as part of lists, the phrase @dfn{list -structure} has come to refer to any structure made out of cons cells. - - The names @sc{car} and @sc{cdr} have only historical meaning now. The -original Lisp implementation ran on an @w{IBM 704} computer which -divided words into two parts, called the ``address'' part and the -``decrement''; @sc{car} was an instruction to extract the contents of -the address part of a register, and @sc{cdr} an instruction to extract -the contents of the decrement. By contrast, ``cons cells'' are named -for the function @code{cons} that creates them, which in turn is named -for its purpose, the construction of cells. - -@cindex atom - Because cons cells are so central to Lisp, we also have a word for -``an object which is not a cons cell''. These objects are called -@dfn{atoms}. - -@cindex parenthesis - The read syntax and printed representation for lists are identical, and -consist of a left parenthesis, an arbitrary number of elements, and a -right parenthesis. - - Upon reading, each object inside the parentheses becomes an element -of the list. That is, a cons cell is made for each element. The -@sc{car} of the cons cell points to the element, and its @sc{cdr} points -to the next cons cell of the list, which holds the next element in the -list. The @sc{cdr} of the last cons cell is set to point to @code{nil}. - -@cindex box diagrams, for lists -@cindex diagrams, boxed, for lists - A list can be illustrated by a diagram in which the cons cells are -shown as pairs of boxes. (The Lisp reader cannot read such an -illustration; unlike the textual notation, which can be understood by -both humans and computers, the box illustrations can be understood only -by humans.) The following represents the three-element list @code{(rose -violet buttercup)}: - -@example -@group - ___ ___ ___ ___ ___ ___ - |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end example - - In this diagram, each box represents a slot that can refer to any Lisp -object. Each pair of boxes represents a cons cell. Each arrow is a -reference to a Lisp object, either an atom or another cons cell. - - In this example, the first box, the @sc{car} of the first cons cell, -refers to or ``contains'' @code{rose} (a symbol). The second box, the -@sc{cdr} of the first cons cell, refers to the next pair of boxes, the -second cons cell. The @sc{car} of the second cons cell refers to -@code{violet} and the @sc{cdr} refers to the third cons cell. The -@sc{cdr} of the third (and last) cons cell refers to @code{nil}. - -Here is another diagram of the same list, @code{(rose violet -buttercup)}, sketched in a different manner: - -@smallexample -@group - --------------- ---------------- ------------------- -| car | cdr | | car | cdr | | car | cdr | -| rose | o-------->| violet | o-------->| buttercup | nil | -| | | | | | | | | - --------------- ---------------- ------------------- -@end group -@end smallexample - -@cindex @samp{(@dots{})} in lists -@cindex @code{nil} in lists -@cindex empty list - A list with no elements in it is the @dfn{empty list}; it is identical -to the symbol @code{nil}. In other words, @code{nil} is both a symbol -and a list. - - Here are examples of lists written in Lisp syntax: - -@example -(A 2 "A") ; @r{A list of three elements.} -() ; @r{A list of no elements (the empty list).} -nil ; @r{A list of no elements (the empty list).} -("A ()") ; @r{A list of one element: the string @code{"A ()"}.} -(A ()) ; @r{A list of two elements: @code{A} and the empty list.} -(A nil) ; @r{Equivalent to the previous.} -((A B C)) ; @r{A list of one element} - ; @r{(which is a list of three elements).} -@end example - - Here is the list @code{(A ())}, or equivalently @code{(A nil)}, -depicted with boxes and arrows: - -@example -@group - ___ ___ ___ ___ - |___|___|--> |___|___|--> nil - | | - | | - --> A --> nil -@end group -@end example - -@menu -* Dotted Pair Notation:: An alternative syntax for lists. -* Association List Type:: A specially constructed list. -@end menu - -@node Dotted Pair Notation -@comment node-name, next, previous, up -@subsubsection Dotted Pair Notation -@cindex dotted pair notation -@cindex @samp{.} in lists - - @dfn{Dotted pair notation} is an alternative syntax for cons cells -that represents the @sc{car} and @sc{cdr} explicitly. In this syntax, -@code{(@var{a} .@: @var{b})} stands for a cons cell whose @sc{car} is -the object @var{a}, and whose @sc{cdr} is the object @var{b}. Dotted -pair notation is therefore more general than list syntax. In the dotted -pair notation, the list @samp{(1 2 3)} is written as @samp{(1 . (2 . (3 -. nil)))}. For @code{nil}-terminated lists, the two notations produce -the same result, but list notation is usually clearer and more -convenient when it is applicable. When printing a list, the dotted pair -notation is only used if the @sc{cdr} of a cell is not a list. - - Here's how box notation can illustrate dotted pairs. This example -shows the pair @code{(rose . violet)}: - -@example -@group - ___ ___ - |___|___|--> violet - | - | - --> rose -@end group -@end example - - Dotted pair notation can be combined with list notation to represent a -chain of cons cells with a non-@code{nil} final @sc{cdr}. For example, -@code{(rose violet . buttercup)} is equivalent to @code{(rose . (violet -. buttercup))}. The object looks like this: - -@example -@group - ___ ___ ___ ___ - |___|___|--> |___|___|--> buttercup - | | - | | - --> rose --> violet -@end group -@end example - - These diagrams make it evident why @w{@code{(rose .@: violet .@: -buttercup)}} is invalid syntax; it would require a cons cell that has -three parts rather than two. - - The list @code{(rose violet)} is equivalent to @code{(rose . (violet))} -and looks like this: - -@example -@group - ___ ___ ___ ___ - |___|___|--> |___|___|--> nil - | | - | | - --> rose --> violet -@end group -@end example - - Similarly, the three-element list @code{(rose violet buttercup)} -is equivalent to @code{(rose . (violet . (buttercup)))}. -@ifinfo -It looks like this: - -@example -@group - ___ ___ ___ ___ ___ ___ - |___|___|--> |___|___|--> |___|___|--> nil - | | | - | | | - --> rose --> violet --> buttercup -@end group -@end example -@end ifinfo - -@node Association List Type -@comment node-name, next, previous, up -@subsubsection Association List Type - - An @dfn{association list} or @dfn{alist} is a specially-constructed -list whose elements are cons cells. In each element, the @sc{car} is -considered a @dfn{key}, and the @sc{cdr} is considered an -@dfn{associated value}. (In some cases, the associated value is stored -in the @sc{car} of the @sc{cdr}.) Association lists are often used as -stacks, since it is easy to add or remove associations at the front of -the list. - - For example, - -@example -(setq alist-of-colors - '((rose . red) (lily . white) (buttercup . yellow))) -@end example - -@noindent -sets the variable @code{alist-of-colors} to an alist of three elements. In the -first element, @code{rose} is the key and @code{red} is the value. - - @xref{Association Lists}, for a further explanation of alists and for -functions that work on alists. - -@node Array Type -@subsection Array Type - - An @dfn{array} is composed of an arbitrary number of slots for -referring to other Lisp objects, arranged in a contiguous block of -memory. Accessing any element of an array takes the same amount of -time. In contrast, accessing an element of a list requires time -proportional to the position of the element in the list. (Elements at -the end of a list take longer to access than elements at the beginning -of a list.) - - Emacs defines two types of array, strings and vectors. A string is an -array of characters and a vector is an array of arbitrary objects. Both -are one-dimensional. (Most other programming languages support -multidimensional arrays, but they are not essential; you can get the -same effect with an array of arrays.) Each type of array has its own -read syntax; see @ref{String Type}, and @ref{Vector Type}. - - An array may have any length up to the largest integer; but once -created, it has a fixed size. The first element of an array has index -zero, the second element has index 1, and so on. This is called -@dfn{zero-origin} indexing. For example, an array of four elements has -indices 0, 1, 2, @w{and 3}. - - The array type is contained in the sequence type and contains both the -string type and the vector type. - -@node String Type -@subsection String Type - - A @dfn{string} is an array of characters. Strings are used for many -purposes in Emacs, as can be expected in a text editor; for example, as -the names of Lisp symbols, as messages for the user, and to represent -text extracted from buffers. Strings in Lisp are constants: evaluation -of a string returns the same string. - -@cindex @samp{"} in strings -@cindex double-quote in strings -@cindex @samp{\} in strings -@cindex backslash in strings - The read syntax for strings is a double-quote, an arbitrary number of -characters, and another double-quote, @code{"like this"}. The Lisp -reader accepts the same formats for reading the characters of a string -as it does for reading single characters (without the question mark that -begins a character literal). You can enter a nonprinting character such -as tab, @kbd{C-a} or @kbd{M-C-A} using the convenient escape sequences, -like this: @code{"\t, \C-a, \M-\C-a"}. You can include a double-quote -in a string by preceding it with a backslash; thus, @code{"\""} is a -string containing just a single double-quote character. -(@xref{Character Type}, for a description of the read syntax for -characters.) - - If you use the @samp{\M-} syntax to indicate a meta character in a -string constant, this sets the -@iftex -$2^{7}$ -@end iftex -@ifinfo -2**7 -@end ifinfo -bit of the character in the string. -This is not the same representation that the meta modifier has in a -character on its own (not inside a string). @xref{Character Type}. - - Strings cannot hold characters that have the hyper, super, or alt -modifiers; they can hold @sc{ASCII} control characters, but no others. -They do not distinguish case in @sc{ASCII} control characters. - - The printed representation of a string consists of a double-quote, the -characters it contains, and another double-quote. However, you must -escape any backslash or double-quote characters in the string with a -backslash, like this: @code{"this \" is an embedded quote"}. - - The newline character is not special in the read syntax for strings; -if you write a new line between the double-quotes, it becomes a -character in the string. But an escaped newline---one that is preceded -by @samp{\}---does not become part of the string; i.e., the Lisp reader -ignores an escaped newline while reading a string. -@cindex newline in strings - -@example -"It is useful to include newlines -in documentation strings, -but the newline is \ -ignored if escaped." - @result{} "It is useful to include newlines -in documentation strings, -but the newline is ignored if escaped." -@end example - - A string can hold properties of the text it contains, in addition to -the characters themselves. This enables programs that copy text between -strings and buffers to preserve the properties with no special effort. -@xref{Text Properties}. Strings with text properties have a special -read and print syntax: - -@example -#("@var{characters}" @var{property-data}...) -@end example - -@noindent -where @var{property-data} consists of zero or more elements, in groups -of three as follows: - -@example -@var{beg} @var{end} @var{plist} -@end example - -@noindent -The elements @var{beg} and @var{end} are integers, and together specify -a range of indices in the string; @var{plist} is the property list for -that range. - - @xref{Strings and Characters}, for functions that work on strings. - -@node Vector Type -@subsection Vector Type - - A @dfn{vector} is a one-dimensional array of elements of any type. It -takes a constant amount of time to access any element of a vector. (In -a list, the access time of an element is proportional to the distance of -the element from the beginning of the list.) - - The printed representation of a vector consists of a left square -bracket, the elements, and a right square bracket. This is also the -read syntax. Like numbers and strings, vectors are considered constants -for evaluation. - -@example -[1 "two" (three)] ; @r{A vector of three elements.} - @result{} [1 "two" (three)] -@end example - - @xref{Vectors}, for functions that work with vectors. - -@node Function Type -@subsection Function Type - - Just as functions in other programming languages are executable, -@dfn{Lisp function} objects are pieces of executable code. However, -functions in Lisp are primarily Lisp objects, and only secondarily the -text which represents them. These Lisp objects are lambda expressions: -lists whose first element is the symbol @code{lambda} (@pxref{Lambda -Expressions}). - - In most programming languages, it is impossible to have a function -without a name. In Lisp, a function has no intrinsic name. A lambda -expression is also called an @dfn{anonymous function} (@pxref{Anonymous -Functions}). A named function in Lisp is actually a symbol with a valid -function in its function cell (@pxref{Defining Functions}). - - Most of the time, functions are called when their names are written in -Lisp expressions in Lisp programs. However, you can construct or obtain -a function object at run time and then call it with the primitive -functions @code{funcall} and @code{apply}. @xref{Calling Functions}. - -@node Macro Type -@subsection Macro Type - - A @dfn{Lisp macro} is a user-defined construct that extends the Lisp -language. It is represented as an object much like a function, but with -different parameter-passing semantics. A Lisp macro has the form of a -list whose first element is the symbol @code{macro} and whose @sc{cdr} -is a Lisp function object, including the @code{lambda} symbol. - - Lisp macro objects are usually defined with the built-in -@code{defmacro} function, but any list that begins with @code{macro} is -a macro as far as Emacs is concerned. @xref{Macros}, for an explanation -of how to write a macro. - -@node Primitive Function Type -@subsection Primitive Function Type -@cindex special forms - - A @dfn{primitive function} is a function callable from Lisp but -written in the C programming language. Primitive functions are also -called @dfn{subrs} or @dfn{built-in functions}. (The word ``subr'' is -derived from ``subroutine''.) Most primitive functions evaluate all -their arguments when they are called. A primitive function that does -not evaluate all its arguments is called a @dfn{special form} -(@pxref{Special Forms}).@refill - - It does not matter to the caller of a function whether the function is -primitive. However, this does matter if you try to substitute a -function written in Lisp for a primitive of the same name. The reason -is that the primitive function may be called directly from C code. -Calls to the redefined function from Lisp will use the new definition, -but calls from C code may still use the built-in definition. - - The term @dfn{function} refers to all Emacs functions, whether written -in Lisp or C. @xref{Function Type}, for information about the -functions written in Lisp. - - Primitive functions have no read syntax and print in hash notation -with the name of the subroutine. - -@example -@group -(symbol-function 'car) ; @r{Access the function cell} - ; @r{of the symbol.} - @result{} #<subr car> -(subrp (symbol-function 'car)) ; @r{Is this a primitive function?} - @result{} t ; @r{Yes.} -@end group -@end example - -@node Byte-Code Type -@subsection Byte-Code Function Type - -The byte compiler produces @dfn{byte-code function objects}. -Internally, a byte-code function object is much like a vector; however, -the evaluator handles this data type specially when it appears as a -function to be called. @xref{Byte Compilation}, for information about -the byte compiler. - -The printed representation and read syntax for a byte-code function -object is like that for a vector, with an additional @samp{#} before the -opening @samp{[}. - -@node Autoload Type -@subsection Autoload Type - - An @dfn{autoload object} is a list whose first element is the symbol -@code{autoload}. It is stored as the function definition of a symbol as -a placeholder for the real definition; it says that the real definition -is found in a file of Lisp code that should be loaded when necessary. -The autoload object contains the name of the file, plus some other -information about the real definition. - - After the file has been loaded, the symbol should have a new function -definition that is not an autoload object. The new definition is then -called as if it had been there to begin with. From the user's point of -view, the function call works as expected, using the function definition -in the loaded file. - - An autoload object is usually created with the function -@code{autoload}, which stores the object in the function cell of a -symbol. @xref{Autoload}, for more details. - -@node Editing Types -@section Editing Types -@cindex editing types - - The types in the previous section are common to many Lisp dialects. -Emacs Lisp provides several additional data types for purposes connected -with editing. - -@menu -* Buffer Type:: The basic object of editing. -* Marker Type:: A position in a buffer. -* Window Type:: Buffers are displayed in windows. -* Frame Type:: Windows subdivide frames. -* Window Configuration Type:: Recording the way a frame is subdivided. -* Process Type:: A process running on the underlying OS. -* Stream Type:: Receive or send characters. -* Keymap Type:: What function a keystroke invokes. -* Syntax Table Type:: What a character means. -* Display Table Type:: How display tables are represented. -* Overlay Type:: How an overlay is represented. -@end menu - -@node Buffer Type -@subsection Buffer Type - - A @dfn{buffer} is an object that holds text that can be edited -(@pxref{Buffers}). Most buffers hold the contents of a disk file -(@pxref{Files}) so they can be edited, but some are used for other -purposes. Most buffers are also meant to be seen by the user, and -therefore displayed, at some time, in a window (@pxref{Windows}). But a -buffer need not be displayed in any window. - - The contents of a buffer are much like a string, but buffers are not -used like strings in Emacs Lisp, and the available operations are -different. For example, insertion of text into a buffer is very -efficient, whereas ``inserting'' text into a string requires -concatenating substrings, and the result is an entirely new string -object. - - Each buffer has a designated position called @dfn{point} -(@pxref{Positions}). At any time, one buffer is the @dfn{current -buffer}. Most editing commands act on the contents of the current -buffer in the neighborhood of point. Many of the standard Emacs -functions manipulate or test the characters in the current buffer; a -whole chapter in this manual is devoted to describing these functions -(@pxref{Text}). - - Several other data structures are associated with each buffer: - -@itemize @bullet -@item -a local syntax table (@pxref{Syntax Tables}); - -@item -a local keymap (@pxref{Keymaps}); and, - -@item -a local variable binding list (@pxref{Buffer-Local Variables}). - -@item -a list of overlays (@pxref{Overlays}). - -@item -text properties for the text in the buffer (@pxref{Text Properties}). -@end itemize - -@noindent -The local keymap and variable list contain entries that individually -override global bindings or values. These are used to customize the -behavior of programs in different buffers, without actually changing the -programs. - - A buffer may be @dfn{indirect}, which means it shares the text -of another buffer. @xref{Indirect Buffers}. - - Buffers have no read syntax. They print in hash notation, showing the -buffer name. - -@example -@group -(current-buffer) - @result{} #<buffer objects.texi> -@end group -@end example - -@node Marker Type -@subsection Marker Type - - A @dfn{marker} denotes a position in a specific buffer. Markers -therefore have two components: one for the buffer, and one for the -position. Changes in the buffer's text automatically relocate the -position value as necessary to ensure that the marker always points -between the same two characters in the buffer. - - Markers have no read syntax. They print in hash notation, giving the -current character position and the name of the buffer. - -@example -@group -(point-marker) - @result{} #<marker at 10779 in objects.texi> -@end group -@end example - -@xref{Markers}, for information on how to test, create, copy, and move -markers. - -@node Window Type -@subsection Window Type - - A @dfn{window} describes the portion of the terminal screen that Emacs -uses to display a buffer. Every window has one associated buffer, whose -contents appear in the window. By contrast, a given buffer may appear -in one window, no window, or several windows. - - Though many windows may exist simultaneously, at any time one window -is designated the @dfn{selected window}. This is the window where the -cursor is (usually) displayed when Emacs is ready for a command. The -selected window usually displays the current buffer, but this is not -necessarily the case. - - Windows are grouped on the screen into frames; each window belongs to -one and only one frame. @xref{Frame Type}. - - Windows have no read syntax. They print in hash notation, giving the -window number and the name of the buffer being displayed. The window -numbers exist to identify windows uniquely, since the buffer displayed -in any given window can change frequently. - -@example -@group -(selected-window) - @result{} #<window 1 on objects.texi> -@end group -@end example - - @xref{Windows}, for a description of the functions that work on windows. - -@node Frame Type -@subsection Frame Type - - A @var{frame} is a rectangle on the screen that contains one or more -Emacs windows. A frame initially contains a single main window (plus -perhaps a minibuffer window) which you can subdivide vertically or -horizontally into smaller windows. - - Frames have no read syntax. They print in hash notation, giving the -frame's title, plus its address in core (useful to identify the frame -uniquely). - -@example -@group -(selected-frame) - @result{} #<frame xemacs@@mole.gnu.ai.mit.edu 0xdac80> -@end group -@end example - - @xref{Frames}, for a description of the functions that work on frames. - -@node Window Configuration Type -@subsection Window Configuration Type -@cindex screen layout - - A @dfn{window configuration} stores information about the positions, -sizes, and contents of the windows in a frame, so you can recreate the -same arrangement of windows later. - - Window configurations do not have a read syntax; their print syntax -looks like @samp{#<window-configuration>}. @xref{Window -Configurations}, for a description of several functions related to -window configurations. - -@node Process Type -@subsection Process Type - - The word @dfn{process} usually means a running program. Emacs itself -runs in a process of this sort. However, in Emacs Lisp, a process is a -Lisp object that designates a subprocess created by the Emacs process. -Programs such as shells, GDB, ftp, and compilers, running in -subprocesses of Emacs, extend the capabilities of Emacs. - - An Emacs subprocess takes textual input from Emacs and returns textual -output to Emacs for further manipulation. Emacs can also send signals -to the subprocess. - - Process objects have no read syntax. They print in hash notation, -giving the name of the process: - -@example -@group -(process-list) - @result{} (#<process shell>) -@end group -@end example - -@xref{Processes}, for information about functions that create, delete, -return information about, send input or signals to, and receive output -from processes. - -@node Stream Type -@subsection Stream Type - - A @dfn{stream} is an object that can be used as a source or sink for -characters---either to supply characters for input or to accept them as -output. Many different types can be used this way: markers, buffers, -strings, and functions. Most often, input streams (character sources) -obtain characters from the keyboard, a buffer, or a file, and output -streams (character sinks) send characters to a buffer, such as a -@file{*Help*} buffer, or to the echo area. - - The object @code{nil}, in addition to its other meanings, may be used -as a stream. It stands for the value of the variable -@code{standard-input} or @code{standard-output}. Also, the object -@code{t} as a stream specifies input using the minibuffer -(@pxref{Minibuffers}) or output in the echo area (@pxref{The Echo -Area}). - - Streams have no special printed representation or read syntax, and -print as whatever primitive type they are. - - @xref{Read and Print}, for a description of functions -related to streams, including parsing and printing functions. - -@node Keymap Type -@subsection Keymap Type - - A @dfn{keymap} maps keys typed by the user to commands. This mapping -controls how the user's command input is executed. A keymap is actually -a list whose @sc{car} is the symbol @code{keymap}. - - @xref{Keymaps}, for information about creating keymaps, handling prefix -keys, local as well as global keymaps, and changing key bindings. - -@node Syntax Table Type -@subsection Syntax Table Type - - A @dfn{syntax table} is a vector of 256 integers. Each element of the -vector defines how one character is interpreted when it appears in a -buffer. For example, in C mode (@pxref{Major Modes}), the @samp{+} -character is punctuation, but in Lisp mode it is a valid character in a -symbol. These modes specify different interpretations by changing the -syntax table entry for @samp{+}, at index 43 in the syntax table. - - Syntax tables are used only for scanning text in buffers, not for -reading Lisp expressions. The table the Lisp interpreter uses to read -expressions is built into the Emacs source code and cannot be changed; -thus, to change the list delimiters to be @samp{@{} and @samp{@}} -instead of @samp{(} and @samp{)} would be impossible. - - @xref{Syntax Tables}, for details about syntax classes and how to make -and modify syntax tables. - -@node Display Table Type -@subsection Display Table Type - - A @dfn{display table} specifies how to display each character code. -Each buffer and each window can have its own display table. A display -table is actually a vector of length 262. @xref{Display Tables}. - -@node Overlay Type -@subsection Overlay Type - - An @dfn{overlay} specifies temporary alteration of the display -appearance of a part of a buffer. It contains markers delimiting a -range of the buffer, plus a property list (a list whose elements are -alternating property names and values). Overlays are used to present -parts of the buffer temporarily in a different display style. They have -no read syntax, and print in hash notation, giving the buffer name and -range of positions. - - @xref{Overlays}, for how to create and use overlays. - -@node Type Predicates -@section Type Predicates -@cindex predicates -@cindex type checking -@kindex wrong-type-argument - - The Emacs Lisp interpreter itself does not perform type checking on -the actual arguments passed to functions when they are called. It could -not do so, since function arguments in Lisp do not have declared data -types, as they do in other programming languages. It is therefore up to -the individual function to test whether each actual argument belongs to -a type that the function can use. - - All built-in functions do check the types of their actual arguments -when appropriate, and signal a @code{wrong-type-argument} error if an -argument is of the wrong type. For example, here is what happens if you -pass an argument to @code{+} that it cannot handle: - -@example -@group -(+ 2 'a) - @error{} Wrong type argument: integer-or-marker-p, a -@end group -@end example - -@cindex type predicates -@cindex testing types - If you want your program to handle different types differently, you -must do explicit type checking. The most common way to check the type -of an object is to call a @dfn{type predicate} function. Emacs has a -type predicate for each type, as well as some predicates for -combinations of types. - - A type predicate function takes one argument; it returns @code{t} if -the argument belongs to the appropriate type, and @code{nil} otherwise. -Following a general Lisp convention for predicate functions, most type -predicates' names end with @samp{p}. - - Here is an example which uses the predicates @code{listp} to check for -a list and @code{symbolp} to check for a symbol. - -@example -(defun add-on (x) - (cond ((symbolp x) - ;; If X is a symbol, put it on LIST. - (setq list (cons x list))) - ((listp x) - ;; If X is a list, add its elements to LIST. - (setq list (append x list))) -@need 3000 - (t - ;; We only handle symbols and lists. - (error "Invalid argument %s in add-on" x)))) -@end example - - Here is a table of predefined type predicates, in alphabetical order, -with references to further information. - -@table @code -@item atom -@xref{List-related Predicates, atom}. - -@item arrayp -@xref{Array Functions, arrayp}. - -@item bufferp -@xref{Buffer Basics, bufferp}. - -@item byte-code-function-p -@xref{Byte-Code Type, byte-code-function-p}. - -@item case-table-p -@xref{Case Table, case-table-p}. - -@item char-or-string-p -@xref{Predicates for Strings, char-or-string-p}. - -@item commandp -@xref{Interactive Call, commandp}. - -@item consp -@xref{List-related Predicates, consp}. - -@item floatp -@xref{Predicates on Numbers, floatp}. - -@item frame-live-p -@xref{Deleting Frames, frame-live-p}. - -@item framep -@xref{Frames, framep}. - -@item integer-or-marker-p -@xref{Predicates on Markers, integer-or-marker-p}. - -@item integerp -@xref{Predicates on Numbers, integerp}. - -@item keymapp -@xref{Creating Keymaps, keymapp}. - -@item listp -@xref{List-related Predicates, listp}. - -@item markerp -@xref{Predicates on Markers, markerp}. - -@item wholenump -@xref{Predicates on Numbers, wholenump}. - -@item nlistp -@xref{List-related Predicates, nlistp}. - -@item numberp -@xref{Predicates on Numbers, numberp}. - -@item number-or-marker-p -@xref{Predicates on Markers, number-or-marker-p}. - -@item overlayp -@xref{Overlays, overlayp}. - -@item processp -@xref{Processes, processp}. - -@item sequencep -@xref{Sequence Functions, sequencep}. - -@item stringp -@xref{Predicates for Strings, stringp}. - -@item subrp -@xref{Function Cells, subrp}. - -@item symbolp -@xref{Symbols, symbolp}. - -@item syntax-table-p -@xref{Syntax Tables, syntax-table-p}. - -@item user-variable-p -@xref{Defining Variables, user-variable-p}. - -@item vectorp -@xref{Vectors, vectorp}. - -@item window-configuration-p -@xref{Window Configurations, window-configuration-p}. - -@item window-live-p -@xref{Deleting Windows, window-live-p}. - -@item windowp -@xref{Basic Windows, windowp}. -@end table - - The most general way to check the type of an object is to call the -function @code{type-of}. Recall that each object belongs to one and -only one primitive type; @code{type-of} tells you which one (@pxref{Lisp -Data Types}). But @code{type-of} knows nothing about non-primitive -types. In most cases, it is more convenient to use type predicates than -@code{type-of}. - -@defun type-of object -This function returns a symbol naming the primitive type of -@var{object}. The value is one of the symbols @code{symbol}, -@code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector}, -@code{marker}, @code{overlay}, @code{window}, @code{buffer}, -@code{subr}, @code{compiled-function}, @code{process}, or -@code{window-configuration}. - -@example -(type-of 1) - @result{} integer -(type-of 'nil) - @result{} symbol -(type-of '()) ; @r{@code{()} is @code{nil}.} - @result{} symbol -(type-of '(x)) - @result{} cons -@end example -@end defun - -@node Equality Predicates -@section Equality Predicates -@cindex equality - - Here we describe two functions that test for equality between any two -objects. Other functions test equality between objects of specific -types, e.g., strings. For these predicates, see the appropriate chapter -describing the data type. - -@defun eq object1 object2 -This function returns @code{t} if @var{object1} and @var{object2} are -the same object, @code{nil} otherwise. The ``same object'' means that a -change in one will be reflected by the same change in the other. - -@code{eq} returns @code{t} if @var{object1} and @var{object2} are -integers with the same value. Also, since symbol names are normally -unique, if the arguments are symbols with the same name, they are -@code{eq}. For other types (e.g., lists, vectors, strings), two -arguments with the same contents or elements are not necessarily -@code{eq} to each other: they are @code{eq} only if they are the same -object. - -(The @code{make-symbol} function returns an uninterned symbol that is -not interned in the standard @code{obarray}. When uninterned symbols -are in use, symbol names are no longer unique. Distinct symbols with -the same name are not @code{eq}. @xref{Creating Symbols}.) - -@example -@group -(eq 'foo 'foo) - @result{} t -@end group - -@group -(eq 456 456) - @result{} t -@end group - -@group -(eq "asdf" "asdf") - @result{} nil -@end group - -@group -(eq '(1 (2 (3))) '(1 (2 (3)))) - @result{} nil -@end group - -@group -(setq foo '(1 (2 (3)))) - @result{} (1 (2 (3))) -(eq foo foo) - @result{} t -(eq foo '(1 (2 (3)))) - @result{} nil -@end group - -@group -(eq [(1 2) 3] [(1 2) 3]) - @result{} nil -@end group - -@group -(eq (point-marker) (point-marker)) - @result{} nil -@end group -@end example - -@end defun - -@defun equal object1 object2 -This function returns @code{t} if @var{object1} and @var{object2} have -equal components, @code{nil} otherwise. Whereas @code{eq} tests if its -arguments are the same object, @code{equal} looks inside nonidentical -arguments to see if their elements are the same. So, if two objects are -@code{eq}, they are @code{equal}, but the converse is not always true. - -@example -@group -(equal 'foo 'foo) - @result{} t -@end group - -@group -(equal 456 456) - @result{} t -@end group - -@group -(equal "asdf" "asdf") - @result{} t -@end group -@group -(eq "asdf" "asdf") - @result{} nil -@end group - -@group -(equal '(1 (2 (3))) '(1 (2 (3)))) - @result{} t -@end group -@group -(eq '(1 (2 (3))) '(1 (2 (3)))) - @result{} nil -@end group - -@group -(equal [(1 2) 3] [(1 2) 3]) - @result{} t -@end group -@group -(eq [(1 2) 3] [(1 2) 3]) - @result{} nil -@end group - -@group -(equal (point-marker) (point-marker)) - @result{} t -@end group - -@group -(eq (point-marker) (point-marker)) - @result{} nil -@end group -@end example - -Comparison of strings is case-sensitive and takes account of text -properties as well as the characters in the strings. To compare -two strings' characters without comparing their text properties, -use @code{string=} (@pxref{Text Comparison}). - -@example -@group -(equal "asdf" "ASDF") - @result{} nil -@end group -@end example - -Two distinct buffers are never @code{equal}, even if their contents -are the same. -@end defun - - The test for equality is implemented recursively, and circular lists may -therefore cause infinite recursion (leading to an error). diff --git a/lispref/os.texi b/lispref/os.texi deleted file mode 100644 index 3c7e46518f3..00000000000 --- a/lispref/os.texi +++ /dev/null @@ -1,1700 +0,0 @@ -@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. -* Time Conversion:: Converting a time from numeric form to a string, or - to calendrical data (or vice versa). -* 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 processes the initial options. (Some of them are handled -even earlier than this.) - -@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 -the 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 the 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 the action arguments from the command line. - -@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}. - -@defvar site-run-file -This variable specifies the site-customization file to load -before the user's init file. Its normal value is @code{"site-start"}. -@end defvar - - 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 that 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 that Emacs was called with, -processes it, loads the user's @file{.emacs} file and displays the -startup messages. -@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 order of appearance, 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, @code{suspend-emacs} 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 possible values: - -@table @code -@item aix-v3 -AIX. - -@item berkeley-unix -Berkeley BSD. - -@item dgux -Data General DGUX operating system. - -@item gnu -A GNU system (using the GNU kernel, which consists of the HURD and Mach). - -@item gnu/linux -A variant GNU system using the Linux kernel. - -@item hpux -Hewlett-Packard HPUX operating system. - -@item irix -Silicon Graphics Irix system. - -@item ms-dos -Microsoft MS-DOS ``operating system.'' - -@item next-mach -NeXT Mach-based 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 windows-nt -Microsoft windows NT. - -@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 - -@vindex system-name - The symbol @code{system-name} is a variable as well as a function. In -fact, the function returns whatever value the variable -@code{system-name} currently holds. Thus, you can set the variable -@code{system-name} in case Emacs is confused about the name of your -system. The variable is also useful for constructing frame titles -(@pxref{Frame Titles}). - -@defvar mail-host-address -If this variable is non-@code{nil}, it is used instead of -@code{system-name} for purposes of generating email addresses. For -example, it is used when constructing the default value of -@code{user-mail-address}. @xref{User Identification}. (Since this is -done when Emacs starts up, the value actually used is the one saved when -Emacs was dumped. @xref{Building Emacs}.) -@end defvar - -@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 - -@defvar path-separator -This variable holds a string which says which character separates -directories in a search path (as found in an environment variable). Its -value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS -and Windows NT. -@end defvar - -@defvar invocation-name -This variable holds the program name under which Emacs was invoked. The -value is a string, and does not include a directory name. -@end defvar - -@defvar invocation-directory -This variable holds the directory from which the Emacs executable was -invoked, or perhaps @code{nil} if that directory cannot be determined. -@end defvar - -@defvar installation-directory -If non-@code{nil}, this is a directory within which to look for the -@file{lib-src} and @file{etc} subdirectories. This is non-@code{nil} -when Emacs can't find those directories in their standard installed -locations, but can find them in a directory related somehow to the one -containing the Emacs executable. -@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 - -@defvar user-mail-address -This holds the nominal email address of the user who is using Emacs. -Emacs normally sets this variable to a default value after reading your -init files, but not if you have already set it. So you can set the -variable to some other value in your @file{~/.emacs} file if you do not -want to use the default value. -@end defvar - -@defun user-login-name &optional uid -If you don't specify @var{uid}, 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}. - -If you specify @var{uid}, the value is the user name that corresponds -to @var{uid} (which should be an integer). - -@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 - -@vindex user-full-name -@vindex user-real-login-name -@vindex user-login-name - The symbols @code{user-login-name}, @code{user-real-login-name} and -@code{user-full-name} are variables as well as functions. The functions -return the same values that the variables hold. These variables allow -you to ``fake out'' Emacs by telling the functions what to return. The -variables are also useful for constructing frame titles (@pxref{Frame -Titles}). - -@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. It is 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 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 above) and from @code{file-attributes} (@pxref{File Attributes}). -@end defun - -@node Time Conversion -@section Time Conversion - - These functions convert time values (lists of two or three integers) -to strings or to calendrical information. There is also a function to -convert calendrical information to a time value. You can get time -values from the functions @code{current-time} (@pxref{Time of Day}) and -@code{file-attributes} (@pxref{File Attributes}). - -Many operating systems are limited to time values that contain 32 bits -of information; these systems typically handle only the times from -1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC. However, some -operating systems have larger time values, and can represent times far -in the past or future. - -Time conversion functions always use the Gregorian calendar, even for -dates before the Gregorian calendar was introduced. Year numbers count -the number of years since the year 1 B.C., and do not skip zero as -traditional Gregorian years do; for example, the year number -37 -represents the Gregorian year 38 B.C@. - -@defun format-time-string format-string time -This function converts @var{time} to a string according to -@var{format-string}. The argument @var{format-string} may contain -@samp{%}-sequences which say to substitute parts of the time. Here is a -table of what the @samp{%}-sequences mean: - -@table @samp -@item %a -This stands for the abbreviated name of the day of week. -@item %A -This stands for the full name of the day of week. -@item %b -This stands for the abbreviated name of the month. -@item %B -This stands for the full name of the month. -@item %c -This is a synonym for @samp{%x %X}. -@item %C -This has a locale-specific meaning. In the default locale (named C), it -is equivalent to @samp{%A, %B %e, %Y}. -@item %d -This stands for the day of month, zero-padded. -@item %D -This is a synonym for @samp{%m/%d/%y}. -@item %e -This stands for the day of month, blank-padded. -@item %h -This is a synonym for @samp{%b}. -@item %H -This stands for the hour (00-23). -@item %I -This stands for the hour (00-12). -@item %j -This stands for the day of the year (001-366). -@item %k -This stands for the hour (0-23), blank padded. -@item %l -This stands for the hour (1-12), blank padded. -@item %m -This stands for the month (01-12). -@item %M -This stands for the minute (00-59). -@item %n -This stands for a newline. -@item %p -This stands for @samp{AM} or @samp{PM}, as appropriate. -@item %r -This is a synonym for @samp{%I:%M:%S %p}. -@item %R -This is a synonym for @samp{%H:%M}. -@item %S -This stands for the seconds (00-60). -@item %t -This stands for a tab character. -@item %T -This is a synonym for @samp{%H:%M:%S}. -@item %U -This stands for the week of the year (01-52), assuming that weeks -start on Sunday. -@item %w -This stands for the numeric day of week (0-6). Sunday is day 0. -@item %W -This stands for the week of the year (01-52), assuming that weeks -start on Monday. -@item %x -This has a locale-specific meaning. In the default locale (named C), it -is equivalent to @samp{%D}. -@item %X -This has a locale-specific meaning. In the default locale (named C), it -is equivalent to @samp{%T}. -@item %y -This stands for the year without century (00-99). -@item %Y -This stands for the year with century. -@item %Z -This stands for the time zone abbreviation. -@end table -@end defun - -@defun decode-time time -This function converts a time value into calendrical information. The -return value is a list of nine elements, as follows: - -@example -(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone}) -@end example - -Here is what the elements mean: - -@table @var -@item sec -The number of seconds past the minute, as an integer between 0 and 59. -@item minute -The number of minutes past the hour, as an integer between 0 and 59. -@item hour -The hour of the day, as an integer between 0 and 23. -@item day -The day of the month, as an integer between 1 and 31. -@item month -The month of the year, as an integer between 1 and 12. -@item year -The year, an integer typically greater than 1900. -@item dow -The day of week, as an integer between 0 and 6, where 0 stands for -Sunday. -@item dst -@code{t} if daylight savings time is effect, otherwise @code{nil}. -@item zone -An integer indicating the time zone, as the number of seconds east of -Greenwich. -@end table - -Note that Common Lisp has different meanings for @var{dow} and -@var{zone}. -@end defun - -@defun encode-time seconds minutes hour day month year &optional @dots{}zone -This function is the inverse of @code{decode-time}. It converts seven -items of calendrical data into a time value. For the meanings of the -arguments, see the table above under @code{decode-time}. - -Year numbers less than 100 are treated just like other year numbers. If -you want them to stand for years above 1900, you must alter them yourself -before you call @code{encode-time}. - -The optional argument @var{zone} defaults to the current time zone and -its daylight savings time rules. If specified, it can be either a list -(as you would get from @code{current-time-zone}) or an integer (as you -would get from @code{decode-time}). The specified zone is used without -any further alteration for daylight savings time. - -If you pass more than seven arguments to @code{encode-time}, the first -six are used as @var{seconds} through @var{year}, the last argument is -used as @var{zone}, and the arguments in between are ignored. This -feature makes it possible to use the elements of a list returned by -@code{decode-time} as the arguments to @code{encode-time}, like this: - -@example -(apply 'encode-time (decode-time @dots{})) -@end example -@end defun - -@node Timers -@section Timers for Delayed Execution -@cindex timer - - You can set up a @dfn{timer} to call a function at a specified future time or -after a certain length of idleness. - - Emacs cannot run a timer at any arbitrary point in a Lisp program; it -can run them only when Emacs could accept output from a subprocess: -namely, while waiting or inside certain primitive functions such as -@code{sit-for} or @code{read-char} which @emph{can} wait. Therefore, a -timer's execution may be delayed if Emacs is busy. However, the time of -execution is very precise if Emacs is idle. - -@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 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 a number (integer or floating point), 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 a number, it -specifies a repetition period measured in seconds. In any case, -@var{repeat} has no effect on when @emph{first} call takes -place---@var{time} alone specifies that. - -The function @code{run-at-time} returns a timer value that identifies -the particular scheduled future action. You can use this value to call -@code{cancel-timer} (see below). -@end defun - -@defmac with-timeout (seconds timeout-forms@dots{}) body@dots{} -Execute @var{body}, but give up after @var{seconds} seconds. If -@var{body} finishes before the time is up, @code{with-timeout} returns -the value of the last form in @var{body}. If, however, the execution of -@var{body} is cut short by the timeout, then @code{with-timeout} -executes all the @var{timeout-forms} and returns the value of the last -of them. - -This macro works by set a timer to run after @var{seconds} seconds. If -@var{body} finishes before that time, it cancels the timer. If the -timer actually runs, it terminates execution of @var{body}, then -executes @var{timeout-forms}. - -Since timers can run within a Lisp program only when the program calls a -primitive that can wait, @code{with-timeout} cannot stop executing -@var{body} while it is in the midst of a computation---only when it -calls one of those primitives. So use @code{with-timeout} only with a -@var{body} that waits for input, not one that does a long computation. -@end defmac - - The function @code{y-or-n-p-with-timeout} provides a simple way to use -a timer to avoid waiting too long for an answer. @xref{Yes-or-No -Queries}. - -@defun run-with-idle-timer secs repeat function &rest args -Set up a timer which runs when Emacs has been idle for @var{secs} -seconds. The value of @var{secs} may be an integer or a floating point -number. - -If @var{repeat} is @code{nil}, the timer runs just once, the first time -Emacs remains idle for a long enough time. More often @var{repeat} is -non-@code{nil}, which means to run the timer @emph{each time} Emacs -remains idle for @var{secs} seconds. - -The function @code{run-with-idle-timer} returns a timer value which you -can use in calling @code{cancel-timer} (see below). -@end defun - -@cindex idleness - Emacs becomes ``idle'' when it starts waiting for user input, and it -remains idle until the user provides some input. If a timer is set for -five seconds of idleness, it runs approximately five seconds after Emacs -first became idle. Even if its @var{repeat} is true, this timer will -not run again as long as Emacs remains idle, because the duration of -idleness will continue to increase and will not go down to five seconds -again. - - Emacs can do various things while idle: garbage collect, autosave or -handle data from a subprocess. But these interludes during idleness -have little effect on idle timers. An idle timer set for 600 seconds -will run when ten minutes have elapsed since the last user command was -finished, even if subprocess output has been accepted thousands of times -within those ten minutes, even if there have been garbage collections -and autosaves. - - When the user supplies input, Emacs becomes non-idle while executing the -input. Then it becomes idle again, and all the idle timers that are -set up to repeat will subsequently run another time, one by one. - -@defun cancel-timer timer -Cancel the requested action for @var{timer}, which should be a value -previously returned by @code{run-at-time} or @code{run-with-idle-timer}. -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. When Emacs communicates -directly with X, it ignores this argument and uses interrupts if that is -the way it knows how to communicate. - -If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} (@kbd{C-q}, -@kbd{C-s}) flow control for output to the 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 @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 - -@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. These -features apply to each event in the order they are described here: each -event is first modified according to @code{extra-keyboard-modifiers}, -then translated through @code{keyboard-translate-table} (if applicable). -If it is being read as part of a key sequence, it is then added to the -sequece being read; then subsequences containing it are checked first -with @code{function-key-map} and then with @code{key-translation-map}. - -@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 using 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 - - The remaining translation features translate subsequences of key -sequences being read. They are implemented in @code{read-key-sequence} -and have no effect on @code{read-char}. - -@defvar function-key-map -This variable holds a keymap that describes the character sequences -sent by function keys on an ordinary character terminal. This keymap -uses the same data structure as other keymaps, but is used differently: it -specifies translations to make while reading event sequences. - -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. For example, -if @kbd{C-x f} has a binding in @code{key-translation-map}, that -translation takes effect even though @kbd{C-x f} also has a key binding -in the global map. -@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 -@group -(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)))) -@end group -@group - (if (symbolp e) - symbol - (cons symbol (cdr e))))) - -(define-key function-key-map "\C-ch" 'hyperify) -@end group -@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 that 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. - -The variable is always local to the current X terminal and cannot be -buffer-local. @xref{Multiple Displays}. -@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! - - As X servers and other window systems replace character-only -terminals, this problem is gradually being cured. For the mean time, -Emacs 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}. 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}. -@end enumerate - -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 error 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 diff --git a/lispref/positions.texi b/lispref/positions.texi deleted file mode 100644 index 1d02377565a..00000000000 --- a/lispref/positions.texi +++ /dev/null @@ -1,897 +0,0 @@ -@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/positions -@node Positions, Markers, Frames, Top -@chapter Positions -@cindex position (in buffer) - - A @dfn{position} is the index of a character in the text of a buffer. -More precisely, a position identifies the place between two characters -(or before the first character, or after the last character), so we can -speak of the character before or after a given position. However, we -often speak of the character ``at'' a position, meaning the character -after that position. - - Positions are usually represented as integers starting from 1, but can -also be represented as @dfn{markers}---special objects that relocate -automatically when text is inserted or deleted so they stay with the -surrounding characters. @xref{Markers}. - -@menu -* Point:: The special position where editing takes place. -* Motion:: Changing point. -* Excursions:: Temporary motion and buffer changes. -* Narrowing:: Restricting editing to a portion of the buffer. -@end menu - -@node Point -@section Point -@cindex point - - @dfn{Point} is a special buffer position used by many editing -commands, including the self-inserting typed characters and text -insertion functions. Other commands move point through the text -to allow editing and insertion at different places. - - Like other positions, point designates a place between two characters -(or before the first character, or after the last character), rather -than a particular character. Usually terminals display the cursor over -the character that immediately follows point; point is actually before -the character on which the cursor sits. - -@cindex point with narrowing - The value of point is a number between 1 and the buffer size plus 1. -If narrowing is in effect (@pxref{Narrowing}), then point is constrained -to fall within the accessible portion of the buffer (possibly at one end -of it). - - Each buffer has its own value of point, which is independent of the -value of point in other buffers. Each window also has a value of point, -which is independent of the value of point in other windows on the same -buffer. This is why point can have different values in various windows -that display the same buffer. When a buffer appears in only one window, -the buffer's point and the window's point normally have the same value, -so the distinction is rarely important. @xref{Window Point}, for more -details. - -@defun point -@cindex current buffer position -This function returns the value of point in the current buffer, -as an integer. - -@need 700 -@example -@group -(point) - @result{} 175 -@end group -@end example -@end defun - -@defun point-min -This function returns the minimum accessible value of point in the -current buffer. This is normally 1, but if narrowing is in effect, it -is the position of the start of the region that you narrowed to. -(@xref{Narrowing}.) -@end defun - -@defun point-max -This function returns the maximum accessible value of point in the -current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is -in effect, in which case it is the position of the end of the region -that you narrowed to. (@xref{Narrowing}). -@end defun - -@defun buffer-end flag -This function returns @code{(point-min)} if @var{flag} is less than 1, -@code{(point-max)} otherwise. The argument @var{flag} must be a number. -@end defun - -@defun buffer-size -This function returns the total number of characters in the current -buffer. In the absence of any narrowing (@pxref{Narrowing}), -@code{point-max} returns a value one larger than this. - -@example -@group -(buffer-size) - @result{} 35 -@end group -@group -(point-max) - @result{} 36 -@end group -@end example -@end defun - -@node Motion -@section Motion - - Motion functions change the value of point, either relative to the -current value of point, relative to the beginning or end of the buffer, -or relative to the edges of the selected window. @xref{Point}. - -@menu -* Character Motion:: Moving in terms of characters. -* Word Motion:: Moving in terms of words. -* Buffer End Motion:: Moving to the beginning or end of the buffer. -* Text Lines:: Moving in terms of lines of text. -* Screen Lines:: Moving in terms of lines as displayed. -* List Motion:: Moving by parsing lists and sexps. -* Skipping Characters:: Skipping characters belonging to a certain set. -@end menu - -@node Character Motion -@subsection Motion by Characters - - These functions move point based on a count of characters. -@code{goto-char} is the fundamental primitive; the other functions use -that. - -@deffn Command goto-char position -This function sets point in the current buffer to the value -@var{position}. If @var{position} is less than 1, it moves point to the -beginning of the buffer. If @var{position} is greater than the length -of the buffer, it moves point to the end. - -If narrowing is in effect, @var{position} still counts from the -beginning of the buffer, but point cannot go outside the accessible -portion. If @var{position} is out of range, @code{goto-char} moves -point to the beginning or the end of the accessible portion. - -When this function is called interactively, @var{position} is the -numeric prefix argument, if provided; otherwise it is read from the -minibuffer. - -@code{goto-char} returns @var{position}. -@end deffn - -@deffn Command forward-char &optional count -@c @kindex beginning-of-buffer -@c @kindex end-of-buffer -This function moves point @var{count} characters forward, towards the -end of the buffer (or backward, towards the beginning of the buffer, if -@var{count} is negative). If the function attempts to move point past -the beginning or end of the buffer (or the limits of the accessible -portion, when narrowing is in effect), an error is signaled with error -code @code{beginning-of-buffer} or @code{end-of-buffer}. - -In an interactive call, @var{count} is the numeric prefix argument. -@end deffn - -@deffn Command backward-char &optional count -This function moves point @var{count} characters backward, towards the -beginning of the buffer (or forward, towards the end of the buffer, if -@var{count} is negative). If the function attempts to move point past -the beginning or end of the buffer (or the limits of the accessible -portion, when narrowing is in effect), an error is signaled with error -code @code{beginning-of-buffer} or @code{end-of-buffer}. - -In an interactive call, @var{count} is the numeric prefix argument. -@end deffn - -@node Word Motion -@subsection Motion by Words - - These functions for parsing words use the syntax table to decide -whether a given character is part of a word. @xref{Syntax Tables}. - -@deffn Command forward-word count -This function moves point forward @var{count} words (or backward if -@var{count} is negative). Normally it returns @code{t}. If this motion -encounters the beginning or end of the buffer, or the limits of the -accessible portion when narrowing is in effect, point stops there -and the value is @code{nil}. - -In an interactive call, @var{count} is set to the numeric prefix -argument. -@end deffn - -@deffn Command backward-word count -This function is just like @code{forward-word}, except that it moves -backward until encountering the front of a word, rather than forward. - -In an interactive call, @var{count} is set to the numeric prefix -argument. - -This function is rarely used in programs, as it is more efficient to -call @code{forward-word} with a negative argument. -@end deffn - -@defvar words-include-escapes -@c Emacs 19 feature -This variable affects the behavior of @code{forward-word} and everything -that uses it. If it is non-@code{nil}, then characters in the -``escape'' and ``character quote'' syntax classes count as part of -words. Otherwise, they do not. -@end defvar - -@node Buffer End Motion -@subsection Motion to an End of the Buffer - - To move point to the beginning of the buffer, write: - -@example -@group -(goto-char (point-min)) -@end group -@end example - -@noindent -Likewise, to move to the end of the buffer, use: - -@example -@group -(goto-char (point-max)) -@end group -@end example - - Here are two commands that users use to do these things. They are -documented here to warn you not to use them in Lisp programs, because -they set the mark and display messages in the echo area. - -@deffn Command beginning-of-buffer &optional n -This function moves point to the beginning of the buffer (or the limits -of the accessible portion, when narrowing is in effect), setting the -mark at the previous position. If @var{n} is non-@code{nil}, then it -puts point @var{n} tenths of the way from the beginning of the buffer. - -In an interactive call, @var{n} is the numeric prefix argument, -if provided; otherwise @var{n} defaults to @code{nil}. - -Don't use this function in Lisp programs! -@end deffn - -@deffn Command end-of-buffer &optional n -This function moves point to the end of the buffer (or the limits of -the accessible portion, when narrowing is in effect), setting the mark -at the previous position. If @var{n} is non-@code{nil}, then it puts -point @var{n} tenths of the way from the end of the buffer. - -In an interactive call, @var{n} is the numeric prefix argument, -if provided; otherwise @var{n} defaults to @code{nil}. - -Don't use this function in Lisp programs! -@end deffn - -@node Text Lines -@subsection Motion by Text Lines -@cindex lines - - Text lines are portions of the buffer delimited by newline characters, -which are regarded as part of the previous line. The first text line -begins at the beginning of the buffer, and the last text line ends at -the end of the buffer whether or not the last character is a newline. -The division of the buffer into text lines is not affected by the width -of the window, by line continuation in display, or by how tabs and -control characters are displayed. - -@deffn Command goto-line line -This function moves point to the front of the @var{line}th line, -counting from line 1 at beginning of the buffer. If @var{line} is less -than 1, it moves point to the beginning of the buffer. If @var{line} is -greater than the number of lines in the buffer, it moves point to the -end of the buffer---that is, the @emph{end of the last line} of the -buffer. This is the only case in which @code{goto-line} does not -necessarily move to the beginning of a line. - -If narrowing is in effect, then @var{line} still counts from the -beginning of the buffer, but point cannot go outside the accessible -portion. So @code{goto-line} moves point to the beginning or end of the -accessible portion, if the line number specifies an inaccessible -position. - -The return value of @code{goto-line} is the difference between -@var{line} and the line number of the line to which point actually was -able to move (in the full buffer, before taking account of narrowing). -Thus, the value is positive if the scan encounters the real end of the -buffer. The value is zero if scan encounters the end of the accessible -portion but not the real end of the buffer. - -In an interactive call, @var{line} is the numeric prefix argument if -one has been provided. Otherwise @var{line} is read in the minibuffer. -@end deffn - -@deffn Command beginning-of-line &optional count -This function moves point to the beginning of the current line. With an -argument @var{count} not @code{nil} or 1, it moves forward -@var{count}@minus{}1 lines and then to the beginning of the line. - -If this function reaches the end of the buffer (or of the accessible -portion, if narrowing is in effect), it positions point there. No error -is signaled. -@end deffn - -@deffn Command end-of-line &optional count -This function moves point to the end of the current line. With an -argument @var{count} not @code{nil} or 1, it moves forward -@var{count}@minus{}1 lines and then to the end of the line. - -If this function reaches the end of the buffer (or of the accessible -portion, if narrowing is in effect), it positions point there. No error -is signaled. -@end deffn - -@deffn Command forward-line &optional count -@cindex beginning of line -This function moves point forward @var{count} lines, to the beginning of -the line. If @var{count} is negative, it moves point -@minus{}@var{count} lines backward, to the beginning of a line. If -@var{count} is zero, it moves point to the beginning of the current -line. - -If @code{forward-line} encounters the beginning or end of the buffer (or -of the accessible portion) before finding that many lines, it sets point -there. No error is signaled. - -@code{forward-line} returns the difference between @var{count} and the -number of lines actually moved. If you attempt to move down five lines -from the beginning of a buffer that has only three lines, point stops at -the end of the last line, and the value will be 2. - -In an interactive call, @var{count} is the numeric prefix argument. -@end deffn - -@defun count-lines start end -@cindex lines in region -This function returns the number of lines between the positions -@var{start} and @var{end} in the current buffer. If @var{start} and -@var{end} are equal, then it returns 0. Otherwise it returns at least -1, even if @var{start} and @var{end} are on the same line. This is -because the text between them, considered in isolation, must contain at -least one line unless it is empty. - -Here is an example of using @code{count-lines}: - -@example -@group -(defun current-line () - "Return the vertical position of point@dots{}" - (+ (count-lines (window-start) (point)) - (if (= (current-column) 0) 1 0) - -1)) -@end group -@end example -@end defun - -@ignore -@c ================ -The @code{previous-line} and @code{next-line} commands are functions -that should not be used in programs. They are for users and are -mentioned here only for completeness. - -@deffn Command previous-line count -@cindex goal column -This function moves point up @var{count} lines (down if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' -(normally the same column that it was at the beginning of the move). - -If there is no character in the target line exactly under the current -column, point is positioned after the character in that line which -spans this column, or at the end of the line if it is not long enough. - -If it attempts to move beyond the top or bottom of the buffer (or clipped -region), then point is positioned in the goal column in the top or -bottom line. No error is signaled. - -In an interactive call, @var{count} will be the numeric -prefix argument. - -The command @code{set-goal-column} can be used to create a semipermanent -goal column to which this command always moves. Then it does not try to -move vertically. - -If you are thinking of using this in a Lisp program, consider using -@code{forward-line} with a negative argument instead. It is usually easier -to use and more reliable (no dependence on goal column, etc.). -@end deffn - -@deffn Command next-line count -This function moves point down @var{count} lines (up if @var{count} -is negative). In moving, it attempts to keep point in the ``goal column'' -(normally the same column that it was at the beginning of the move). - -If there is no character in the target line exactly under the current -column, point is positioned after the character in that line which -spans this column, or at the end of the line if it is not long enough. - -If it attempts to move beyond the top or bottom of the buffer (or clipped -region), then point is positioned in the goal column in the top or -bottom line. No error is signaled. - -In the case where the @var{count} is 1, and point is on the last -line of the buffer (or clipped region), a new empty line is inserted at the -end of the buffer (or clipped region) and point moved there. - -In an interactive call, @var{count} will be the numeric -prefix argument. - -The command @code{set-goal-column} can be used to create a semipermanent -goal column to which this command always moves. Then it does not try to -move vertically. - -If you are thinking of using this in a Lisp program, consider using -@code{forward-line} instead. It is usually easier -to use and more reliable (no dependence on goal column, etc.). -@end deffn - -@c ================ -@end ignore - - Also see the functions @code{bolp} and @code{eolp} in @ref{Near Point}. -These functions do not move point, but test whether it is already at the -beginning or end of a line. - -@node Screen Lines -@subsection Motion by Screen Lines - - The line functions in the previous section count text lines, delimited -only by newline characters. By contrast, these functions count screen -lines, which are defined by the way the text appears on the screen. A -text line is a single screen line if it is short enough to fit the width -of the selected window, but otherwise it may occupy several screen -lines. - - In some cases, text lines are truncated on the screen rather than -continued onto additional screen lines. In these cases, -@code{vertical-motion} moves point much like @code{forward-line}. -@xref{Truncation}. - - Because the width of a given string depends on the flags that control -the appearance of certain characters, @code{vertical-motion} behaves -differently, for a given piece of text, depending on the buffer it is -in, and even on the selected window (because the width, the truncation -flag, and display table may vary between windows). @xref{Usual -Display}. - - These functions scan text to determine where screen lines break, and -thus take time proportional to the distance scanned. If you intend to -use them heavily, Emacs provides caches which may improve the -performance of your code. @xref{Text Lines, cache-long-line-scans}. - - -@defun vertical-motion count &optional window -This function moves point to the start of the screen line @var{count} -screen lines down from the screen line containing point. If @var{count} -is negative, it moves up instead. - -@code{vertical-motion} returns the number of lines moved. The value may -be less in absolute value than @var{count} if the beginning or end of -the buffer was reached. - -The window @var{window} is used for obtaining parameters such as the -width, the horizontal scrolling, and the display table. But -@code{vertical-motion} always operates on the current buffer, even if -@var{window} currently displays some other buffer. -@end defun - -@deffn Command move-to-window-line count -This function moves point with respect to the text currently displayed -in the selected window. It moves point to the beginning of the screen -line @var{count} screen lines from the top of the window. If -@var{count} is negative, that specifies a position -@w{@minus{}@var{count}} lines from the bottom (or the last line of the -buffer, if the buffer ends above the specified screen position). - -If @var{count} is @code{nil}, then point moves to the beginning of the -line in the middle of the window. If the absolute value of @var{count} -is greater than the size of the window, then point moves to the place -that would appear on that screen line if the window were tall enough. -This will probably cause the next redisplay to scroll to bring that -location onto the screen. - -In an interactive call, @var{count} is the numeric prefix argument. - -The value returned is the window line number point has moved to, with -the top line in the window numbered 0. -@end deffn - -@defun compute-motion from frompos to topos width offsets window -This function scans the current buffer, calculating screen positions. -It scans the buffer forward from position @var{from}, assuming that is -at screen coordinates @var{frompos}, to position @var{to} or coordinates -@var{topos}, whichever comes first. It returns the ending buffer -position and screen coordinates. - -The coordinate arguments @var{frompos} and @var{topos} are cons cells of -the form @code{(@var{hpos} . @var{vpos})}. - -The argument @var{width} is the number of columns available to display -text; this affects handling of continuation lines. Use the value -returned by @code{window-width} for the window of your choice; -normally, use @code{(window-width @var{window})}. - -The argument @var{offsets} is either @code{nil} or a cons cell of the -form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is -the number of columns not being displayed at the left margin; most -callers get this from @code{window-hscroll}. Meanwhile, -@var{tab-offset} is the offset between column numbers on the screen and -column numbers in the buffer. This can be nonzero in a continuation -line, when the previous screen lines' widths do not add up to a multiple -of @code{tab-width}. It is always zero in a non-continuation line. - -The window @var{window} serves only to specify which display table to -use. @code{compute-motion} always operates on the current buffer, -regardless of what buffer is displayed in @var{window}. - -The return value is a list of five elements: - -@example -(@var{pos} @var{vpos} @var{hpos} @var{prevhpos} @var{contin}) -@end example - -@noindent -Here @var{pos} is the buffer position where the scan stopped, @var{vpos} -is the vertical screen position, and @var{hpos} is the horizontal screen -position. - -The result @var{prevhpos} is the horizontal position one character back -from @var{pos}. The result @var{contin} is @code{t} if the last line -was continued after (or within) the previous character. - -For example, to find the buffer position of column @var{col} of line -@var{line} of a certain window, pass the window's display start location -as @var{from} and the window's upper-left coordinates as @var{frompos}. -Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to -the end of the accessible portion of the buffer, and pass @var{line} and -@var{col} as @var{topos}. Here's a function that does this: - -@example -(defun coordinates-of-position (col line) - (car (compute-motion (window-start) - '(0 . 0) - (point-max) - (cons col line) - (window-width) - (cons (window-hscroll) 0) - (selected-window)))) -@end example - -When you use @code{compute-motion} for the minibuffer, you need to use -@code{minibuffer-prompt-width} to get the horizontal position of the -beginning of the first screen line. @xref{Minibuffer Misc}. -@end defun - -@node List Motion -@comment node-name, next, previous, up -@subsection Moving over Balanced Expressions -@cindex sexp motion -@cindex Lisp expression motion -@cindex list motion - - Here are several functions concerned with balanced-parenthesis -expressions (also called @dfn{sexps} in connection with moving across -them in Emacs). The syntax table controls how these functions interpret -various characters; see @ref{Syntax Tables}. @xref{Parsing -Expressions}, for lower-level primitives for scanning sexps or parts of -sexps. For user-level commands, see @ref{Lists Commands,,, emacs, GNU -Emacs Manual}. - -@deffn Command forward-list arg -This function moves forward across @var{arg} balanced groups of -parentheses. (Other syntactic entities such as words or paired string -quotes are ignored.) -@end deffn - -@deffn Command backward-list arg -This function moves backward across @var{arg} balanced groups of -parentheses. (Other syntactic entities such as words or paired string -quotes are ignored.) -@end deffn - -@deffn Command up-list arg -This function moves forward out of @var{arg} levels of parentheses. -A negative argument means move backward but still to a less deep spot. -@end deffn - -@deffn Command down-list arg -This function moves forward into @var{arg} levels of parentheses. A -negative argument means move backward but still go -deeper in parentheses (@minus{}@var{arg} levels). -@end deffn - -@deffn Command forward-sexp arg -This function moves forward across @var{arg} balanced expressions. -Balanced expressions include both those delimited by parentheses and -other kinds, such as words and string constants. For example, - -@example -@group ----------- Buffer: foo ---------- -(concat@point{} "foo " (car x) y z) ----------- Buffer: foo ---------- -@end group - -@group -(forward-sexp 3) - @result{} nil - ----------- Buffer: foo ---------- -(concat "foo " (car x) y@point{} z) ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command backward-sexp arg -This function moves backward across @var{arg} balanced expressions. -@end deffn - -@deffn Command beginning-of-defun arg -This function moves back to the @var{arg}th beginning of a defun. If -@var{arg} is negative, this actually moves forward, but it still moves -to the beginning of a defun, not to the end of one. -@end deffn - -@deffn Command end-of-defun arg -This function moves forward to the @var{arg}th end of a defun. If -@var{arg} is negative, this actually moves backward, but it still moves -to the end of a defun, not to the beginning of one. -@end deffn - -@defopt defun-prompt-regexp -If non-@code{nil}, this variable holds a regular expression that -specifies what text can appear before the open-parenthesis that starts a -defun. That is to say, a defun begins on a line that starts with a -match for this regular expression, followed by a character with -open-parenthesis syntax. -@end defopt - -@node Skipping Characters -@comment node-name, next, previous, up -@subsection Skipping Characters -@cindex skipping characters - - The following two functions move point over a specified set of -characters. For example, they are often used to skip whitespace. For -related functions, see @ref{Motion and Syntax}. - -@defun skip-chars-forward character-set &optional limit -This function moves point in the current buffer forward, skipping over a -given set of characters. It examines the character following point, -then advances point if the character matches @var{character-set}. This -continues until it reaches a character that does not match. The -function returns @code{nil}. - -The argument @var{character-set} is like the inside of a -@samp{[@dots{}]} in a regular expression except that @samp{]} is never -special and @samp{\} quotes @samp{^}, @samp{-} or @samp{\}. Thus, -@code{"a-zA-Z"} skips over all letters, stopping before the first -nonletter, and @code{"^a-zA-Z"} skips nonletters stopping before the -first letter. @xref{Regular Expressions}. - -If @var{limit} is supplied (it must be a number or a marker), it -specifies the maximum position in the buffer that point can be skipped -to. Point will stop at or before @var{limit}. - -In the following example, point is initially located directly before the -@samp{T}. After the form is evaluated, point is located at the end of -that line (between the @samp{t} of @samp{hat} and the newline). The -function skips all letters and spaces, but not newlines. - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- -@end group - -@group -(skip-chars-forward "a-zA-Z ") - @result{} nil - ----------- Buffer: foo ---------- -I read "The cat in the hat@point{} -comes back" twice. ----------- Buffer: foo ---------- -@end group -@end example -@end defun - -@defun skip-chars-backward character-set &optional limit -This function moves point backward, skipping characters that match -@var{character-set}, until @var{limit}. It just like -@code{skip-chars-forward} except for the direction of motion. -@end defun - -@node Excursions -@section Excursions -@cindex excursion - - It is often useful to move point ``temporarily'' within a localized -portion of the program, or to switch buffers temporarily. This is -called an @dfn{excursion}, and it is done with the @code{save-excursion} -special form. This construct saves the current buffer and its values of -point and the mark so they can be restored after the completion of the -excursion. - - The forms for saving and restoring the configuration of windows are -described elsewhere (see @ref{Window Configurations}, and @pxref{Frame -Configurations}). - -@defspec save-excursion forms@dots{} -@cindex mark excursion -@cindex point excursion -@cindex current buffer excursion -The @code{save-excursion} special form saves the identity of the current -buffer and the values of point and the mark in it, evaluates -@var{forms}, and finally restores the buffer and its saved values of -point and the mark. All three saved values are restored even in case of -an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). - -The @code{save-excursion} special form is the standard way to switch -buffers or move point within one part of a program and avoid affecting -the rest of the program. It is used more than 500 times in the Lisp -sources of Emacs. - -@code{save-excursion} does not save the values of point and the mark for -other buffers, so changes in other buffers remain in effect after -@code{save-excursion} exits. - -@cindex window excursions -Likewise, @code{save-excursion} does not restore window-buffer -correspondences altered by functions such as @code{switch-to-buffer}. -One way to restore these correspondences, and the selected window, is to -use @code{save-window-excursion} inside @code{save-excursion} -(@pxref{Window Configurations}). - -The value returned by @code{save-excursion} is the result of the last of -@var{forms}, or @code{nil} if no @var{forms} are given. - -@example -@group -(save-excursion - @var{forms}) -@equiv{} -(let ((old-buf (current-buffer)) - (old-pnt (point-marker)) - (old-mark (copy-marker (mark-marker)))) - (unwind-protect - (progn @var{forms}) - (set-buffer old-buf) - (goto-char old-pnt) - (set-marker (mark-marker) old-mark))) -@end group -@end example -@end defspec - -@node Narrowing -@section Narrowing -@cindex narrowing -@cindex restriction (in a buffer) -@cindex accessible portion (of a buffer) - - @dfn{Narrowing} means limiting the text addressable by Emacs editing -commands to a limited range of characters in a buffer. The text that -remains addressable is called the @dfn{accessible portion} of the -buffer. - - Narrowing is specified with two buffer positions which become the -beginning and end of the accessible portion. For most editing commands -and most Emacs primitives, these positions replace the values of the -beginning and end of the buffer. While narrowing is in effect, no text -outside the accessible portion is displayed, and point cannot move -outside the accessible portion. - - Values such as positions or line numbers, which usually count from the -beginning of the buffer, do so despite narrowing, but the functions -which use them refuse to operate on text that is inaccessible. - - The commands for saving buffers are unaffected by narrowing; they save -the entire buffer regardless of any narrowing. - -@deffn Command narrow-to-region start end -This function sets the accessible portion of the current buffer to start -at @var{start} and end at @var{end}. Both arguments should be character -positions. - -In an interactive call, @var{start} and @var{end} are set to the bounds -of the current region (point and the mark, with the smallest first). -@end deffn - -@deffn Command narrow-to-page move-count -This function sets the accessible portion of the current buffer to -include just the current page. An optional first argument -@var{move-count} non-@code{nil} means to move forward or backward by -@var{move-count} pages and then narrow. The variable -@code{page-delimiter} specifies where pages start and end -(@pxref{Standard Regexps}). - -In an interactive call, @var{move-count} is set to the numeric prefix -argument. -@end deffn - -@deffn Command widen -@cindex widening -This function cancels any narrowing in the current buffer, so that the -entire contents are accessible. This is called @dfn{widening}. -It is equivalent to the following expression: - -@example -(narrow-to-region 1 (1+ (buffer-size))) -@end example -@end deffn - -@defspec save-restriction body@dots{} -This special form saves the current bounds of the accessible portion, -evaluates the @var{body} forms, and finally restores the saved bounds, -thus restoring the same state of narrowing (or absence thereof) formerly -in effect. The state of narrowing is restored even in the event of an -abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). -Therefore, this construct is a clean way to narrow a buffer temporarily. - -The value returned by @code{save-restriction} is that returned by the -last form in @var{body}, or @code{nil} if no body forms were given. - -@c Wordy to avoid overfull hbox. --rjc 16mar92 -@strong{Caution:} it is easy to make a mistake when using the -@code{save-restriction} construct. Read the entire description here -before you try it. - -If @var{body} changes the current buffer, @code{save-restriction} still -restores the restrictions on the original buffer (the buffer whose -restructions it saved from), but it does not restore the identity of the -current buffer. - -@code{save-restriction} does @emph{not} restore point and the mark; use -@code{save-excursion} for that. If you use both @code{save-restriction} -and @code{save-excursion} together, @code{save-excursion} should come -first (on the outside). Otherwise, the old point value would be -restored with temporary narrowing still in effect. If the old point -value were outside the limits of the temporary narrowing, this would -fail to restore it accurately. - -The @code{save-restriction} special form records the values of the -beginning and end of the accessible portion as distances from the -beginning and end of the buffer. In other words, it records the amount -of inaccessible text before and after the accessible portion. - -This method yields correct results if @var{body} does further narrowing. -However, @code{save-restriction} can become confused if the body widens -and then make changes outside the range of the saved narrowing. When -this is what you want to do, @code{save-restriction} is not the right -tool for the job. Here is what you must use instead: - -@example -@group -(let ((beg (point-min-marker)) - (end (point-max-marker))) - (unwind-protect - (progn @var{body}) - (save-excursion - (set-buffer (marker-buffer beg)) - (narrow-to-region beg end)))) -@end group -@end example - -Here is a simple example of correct use of @code{save-restriction}: - -@example -@group ----------- Buffer: foo ---------- -This is the contents of foo -This is the contents of foo -This is the contents of foo@point{} ----------- Buffer: foo ---------- -@end group - -@group -(save-excursion - (save-restriction - (goto-char 1) - (forward-line 2) - (narrow-to-region 1 (point)) - (goto-char (point-min)) - (replace-string "foo" "bar"))) - ----------- Buffer: foo ---------- -This is the contents of bar -This is the contents of bar -This is the contents of foo@point{} ----------- Buffer: foo ---------- -@end group -@end example -@end defspec diff --git a/lispref/processes.texi b/lispref/processes.texi deleted file mode 100644 index 359366cf066..00000000000 --- a/lispref/processes.texi +++ /dev/null @@ -1,1233 +0,0 @@ -@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. -* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary - for data sent to and from a subprocess. -* 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. -* Network:: 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{Read and Print}.) 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 destination 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 argument @var{destination} says where to put the process output. -Here are the possibilities: - -@table @asis -@item a buffer -Insert the output in that buffer, before point. This includes both the -standard output stream and the standard error stream of the process. - -@item a string -Find the buffer with that name, then insert the output in that buffer, -before point. - -@item @code{t} -Insert the output in the current buffer, before point. - -@item @code{nil} -Discard the output. - -@item 0 -Discard the output, and return immediately without waiting -for the subprocess to finish. - -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. - -@item (@var{real-destination} @var{error-destination}) -Keep the standard output stream separate from the standard error stream; -deal with the ordinary output as specified by @var{real-destination}, -and dispose of the error output according to @var{error-destination}. -The value @code{nil} means discard it, @code{t} means mix it with the -ordinary output, and a string specifies a file name to redirect error -output into. - -You can't directly specify a buffer to put the error output in; that is -too difficult to implement. But you can achieve this result by sending -the error output to a temporary file and then inserting the file into a -buffer. -@end table - -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 destination 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{destination} 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{destination} 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{destination} 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 MS-DOS Subprocesses -@section MS-DOS Subprocesses - - On MS-DOS, you must indicate whether the data going to and from -a synchronous subprocess are text or binary. Text data requires -translation between the end-of-line convention used within Emacs -(a single newline character) and the convention used outside Emacs -(the two-character sequence, @sc{crlf}). - - The variable @code{binary-process-input} applies to input sent to the -subprocess, and @code{binary-process-output} applies to output received -from it. A non-@code{nil} value means the data is non-text; @code{nil} -means the data is text, and calls for conversion. - -@defvar binary-process-input -If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in -the input to a synchronous subprocess. -@end defvar - -@defvar binary-process-output -If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in -the output from a synchronous subprocess. -@end defvar - - @xref{Files and MS-DOS}, for related information. - -@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 non-@code{nil}, then @sc{pty}s are -used, when available. Otherwise, pipes are used. - -@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 - -To determine whether a given subprocess actually got a pipe or a -@sc{pty}, use the function @code{process-tty-name} (@pxref{Process -Information}). -@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. The -process mark continues to point to the same place as before (usually -into a buffer where output from the process was being inserted). - - 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 that 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 - -@defun process-tty-name process -This function returns the terminal name that @var{process} is using for -its communication with Emacs---or @code{nil} if it is using pipes -instead of a terminal (see @code{process-connection-type} in -@ref{Asynchronous Processes}). -@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 that 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. If -the process has no buffer and no filter function, its output is -discarded. - -@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}, 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. - -@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 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} or -@code{sleep-for} (@pxref{Waiting}), 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}. - - If an error happens during execution of a filter function, it is -caught automatically, so that it doesn't stop the execution of whatever -program was running when the filter function was started. However, if -@code{debug-on-error} is non-@code{nil}, the error-catching is turned -off. This makes it possible to use the Lisp debugger to debug the -filter function. @xref{Debugger}. - - 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. - - In earlier Emacs versions, every filter function that did regexp -searching or matching had to explicitly save and restore the match data. -Now Emacs does this automatically; filter functions never need to do it -explicitly. @xref{Match Data}. - - A filter function that writes the output into the buffer of the -process should check whether the buffer 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. - -The argument @var{seconds} need not be an integer. If it is a floating -point number, this function waits for a fractional number of seconds. -Some systems support only a whole number of seconds; on these systems, -@var{seconds} is rounded down. If the system doesn't support waiting -fractions of a second, you get an error if you specify nonzero -@var{millisec}. - -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} or @code{sleep-for} -(@pxref{Waiting}), 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 buffer 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}. - - If an error happens during execution of a sentinel, it is caught -automatically, so that it doesn't stop the execution of whatever -programs was running when the sentinel was started. However, if -@code{debug-on-error} is non-@code{nil}, the error-catching is turned -off. This makes it possible to use the Lisp debugger to debug the -sentinel. @xref{Debugger}. - - In earlier Emacs versions, every sentinel that did regexp searching or -matching had to explicitly save and restore the match data. Now Emacs -does this automatically; sentinels never need to do it explicitly. -@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 that 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 Network -@section Network Connections -@cindex network connection -@cindex TCP - - Emacs Lisp programs can open TCP network 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. It always returns either @code{open} or @code{closed} for a -network connection, and it never returns either of those values for a -real subprocess. @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 diff --git a/lispref/searching.texi b/lispref/searching.texi deleted file mode 100644 index a9e45998926..00000000000 --- a/lispref/searching.texi +++ /dev/null @@ -1,1368 +0,0 @@ -@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/searching -@node Searching and Matching, Syntax Tables, Text, Top -@chapter Searching and Matching -@cindex searching - - GNU Emacs provides two ways to search through a buffer for specified -text: exact string searches and regular expression searches. After a -regular expression search, you can examine the @dfn{match data} to -determine which text matched the whole regular expression or various -portions of it. - -@menu -* String Search:: Search for an exact match. -* Regular Expressions:: Describing classes of strings. -* Regexp Search:: Searching for a match for a regexp. -* POSIX Regexps:: Searching POSIX-style for the longest match. -* Search and Replace:: Internals of @code{query-replace}. -* Match Data:: Finding out which part of the text matched - various parts of a regexp, after regexp search. -* Searching and Case:: Case-independent or case-significant searching. -* Standard Regexps:: Useful regexps for finding sentences, pages,... -@end menu - - The @samp{skip-chars@dots{}} functions also perform a kind of searching. -@xref{Skipping Characters}. - -@node String Search -@section Searching for Strings -@cindex string search - - These are the primitive functions for searching through the text in a -buffer. They are meant for use in programs, but you may call them -interactively. If you do so, they prompt for the search string; -@var{limit} and @var{noerror} are set to @code{nil}, and @var{repeat} -is set to 1. - -@deffn Command search-forward string &optional limit noerror repeat - This function searches forward from point for an exact match for -@var{string}. If successful, it sets point to the end of the occurrence -found, and returns the new value of point. If no match is found, the -value and side effects depend on @var{noerror} (see below). -@c Emacs 19 feature - - In the following example, point is initially at the beginning of the -line. Then @code{(search-forward "fox")} moves point after the last -letter of @samp{fox}: - -@example -@group ----------- Buffer: foo ---------- -@point{}The quick brown fox jumped over the lazy dog. ----------- Buffer: foo ---------- -@end group - -@group -(search-forward "fox") - @result{} 20 - ----------- Buffer: foo ---------- -The quick brown fox@point{} jumped over the lazy dog. ----------- Buffer: foo ---------- -@end group -@end example - - The argument @var{limit} specifies the upper bound to the search. (It -must be a position in the current buffer.) No match extending after -that position is accepted. If @var{limit} is omitted or @code{nil}, it -defaults to the end of the accessible portion of the buffer. - -@kindex search-failed - What happens when the search fails depends on the value of -@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed} -error is signaled. If @var{noerror} is @code{t}, @code{search-forward} -returns @code{nil} and does nothing. If @var{noerror} is neither -@code{nil} nor @code{t}, then @code{search-forward} moves point to the -upper bound and returns @code{nil}. (It would be more consistent now -to return the new position of point in that case, but some programs -may depend on a value of @code{nil}.) - -If @var{repeat} is supplied (it must be a positive number), then the -search is repeated that many times (each time starting at the end of the -previous time's match). If these successive searches succeed, the -function succeeds, moving point and returning its new value. Otherwise -the search fails. -@end deffn - -@deffn Command search-backward string &optional limit noerror repeat -This function searches backward from point for @var{string}. It is -just like @code{search-forward} except that it searches backwards and -leaves point at the beginning of the match. -@end deffn - -@deffn Command word-search-forward string &optional limit noerror repeat -@cindex word search -This function searches forward from point for a ``word'' match for -@var{string}. If it finds a match, it sets point to the end of the -match found, and returns the new value of point. -@c Emacs 19 feature - -Word matching regards @var{string} as a sequence of words, disregarding -punctuation that separates them. It searches the buffer for the same -sequence of words. Each word must be distinct in the buffer (searching -for the word @samp{ball} does not match the word @samp{balls}), but the -details of punctuation and spacing are ignored (searching for @samp{ball -boy} does match @samp{ball. Boy!}). - -In this example, point is initially at the beginning of the buffer; the -search leaves it between the @samp{y} and the @samp{!}. - -@example -@group ----------- Buffer: foo ---------- -@point{}He said "Please! Find -the ball boy!" ----------- Buffer: foo ---------- -@end group - -@group -(word-search-forward "Please find the ball, boy.") - @result{} 35 - ----------- Buffer: foo ---------- -He said "Please! Find -the ball boy@point{}!" ----------- Buffer: foo ---------- -@end group -@end example - -If @var{limit} is non-@code{nil} (it must be a position in the current -buffer), then it is the upper bound to the search. The match found must -not extend after that position. - -If @var{noerror} is @code{nil}, then @code{word-search-forward} signals -an error if the search fails. If @var{noerror} is @code{t}, then it -returns @code{nil} instead of signaling an error. If @var{noerror} is -neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the -end of the buffer) and returns @code{nil}. - -If @var{repeat} is non-@code{nil}, then the search is repeated that many -times. Point is positioned at the end of the last match. -@end deffn - -@deffn Command word-search-backward string &optional limit noerror repeat -This function searches backward from point for a word match to -@var{string}. This function is just like @code{word-search-forward} -except that it searches backward and normally leaves point at the -beginning of the match. -@end deffn - -@node Regular Expressions -@section Regular Expressions -@cindex regular expression -@cindex regexp - - A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that -denotes a (possibly infinite) set of strings. Searching for matches for -a regexp is a very powerful operation. This section explains how to write -regexps; the following section says how to search for them. - -@menu -* Syntax of Regexps:: Rules for writing regular expressions. -* Regexp Example:: Illustrates regular expression syntax. -@end menu - -@node Syntax of Regexps -@subsection Syntax of Regular Expressions - - Regular expressions have a syntax in which a few characters are -special constructs and the rest are @dfn{ordinary}. An ordinary -character is a simple regular expression that matches that character and -nothing else. The special characters are @samp{.}, @samp{*}, @samp{+}, -@samp{?}, @samp{[}, @samp{]}, @samp{^}, @samp{$}, and @samp{\}; no new -special characters will be defined in the future. Any other character -appearing in a regular expression is ordinary, unless a @samp{\} -precedes it. - -For example, @samp{f} is not a special character, so it is ordinary, and -therefore @samp{f} is a regular expression that matches the string -@samp{f} and no other string. (It does @emph{not} match the string -@samp{ff}.) Likewise, @samp{o} is a regular expression that matches -only @samp{o}.@refill - -Any two regular expressions @var{a} and @var{b} can be concatenated. The -result is a regular expression that matches a string if @var{a} matches -some amount of the beginning of that string and @var{b} matches the rest of -the string.@refill - -As a simple example, we can concatenate the regular expressions @samp{f} -and @samp{o} to get the regular expression @samp{fo}, which matches only -the string @samp{fo}. Still trivial. To do something more powerful, you -need to use one of the special characters. Here is a list of them: - -@need 1200 -@table @kbd -@item .@: @r{(Period)} -@cindex @samp{.} in regexp -is a special character that matches any single character except a newline. -Using concatenation, we can make regular expressions like @samp{a.b}, which -matches any three-character string that begins with @samp{a} and ends with -@samp{b}.@refill - -@item * -@cindex @samp{*} in regexp -is not a construct by itself; it is a suffix operator that means to -repeat the preceding regular expression as many times as possible. In -@samp{fo*}, the @samp{*} applies to the @samp{o}, so @samp{fo*} matches -one @samp{f} followed by any number of @samp{o}s. The case of zero -@samp{o}s is allowed: @samp{fo*} does match @samp{f}.@refill - -@samp{*} always applies to the @emph{smallest} possible preceding -expression. Thus, @samp{fo*} has a repeating @samp{o}, not a -repeating @samp{fo}.@refill - -The matcher processes a @samp{*} construct by matching, immediately, -as many repetitions as can be found. Then it continues with the rest -of the pattern. If that fails, backtracking occurs, discarding some -of the matches of the @samp{*}-modified construct in case that makes -it possible to match the rest of the pattern. For example, in matching -@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first -tries to match all three @samp{a}s; but the rest of the pattern is -@samp{ar} and there is only @samp{r} left to match, so this try fails. -The next alternative is for @samp{a*} to match only two @samp{a}s. -With this choice, the rest of the regexp matches successfully.@refill - -Nested repetition operators can be extremely slow if they specify -backtracking loops. For example, it could take hours for the regular -expression @samp{\(x+y*\)*a} to match the sequence -@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}. The slowness is because -Emacs must try each imaginable way of grouping the 35 @samp{x}'s before -concluding that none of them can work. To make sure your regular -expressions run fast, check nested repetitions carefully. - -@item + -@cindex @samp{+} in regexp -is a suffix operator similar to @samp{*} except that the preceding -expression must match at least once. So, for example, @samp{ca+r} -matches the strings @samp{car} and @samp{caaaar} but not the string -@samp{cr}, whereas @samp{ca*r} matches all three strings. - -@item ? -@cindex @samp{?} in regexp -is a suffix operator similar to @samp{*} except that the preceding -expression can match either once or not at all. For example, -@samp{ca?r} matches @samp{car} or @samp{cr}, but does not match anyhing -else. - -@item [ @dots{} ] -@cindex character set (in regexp) -@cindex @samp{[} in regexp -@cindex @samp{]} in regexp -@samp{[} begins a @dfn{character set}, which is terminated by a -@samp{]}. In the simplest case, the characters between the two brackets -form the set. Thus, @samp{[ad]} matches either one @samp{a} or one -@samp{d}, and @samp{[ad]*} matches any string composed of just @samp{a}s -and @samp{d}s (including the empty string), from which it follows that -@samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr}, -@samp{caddaar}, etc.@refill - -The usual regular expression special characters are not special inside a -character set. A completely different set of special characters exists -inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill - -@samp{-} is used for ranges of characters. To write a range, write two -characters with a @samp{-} between them. Thus, @samp{[a-z]} matches any -lower case letter. Ranges may be intermixed freely with individual -characters, as in @samp{[a-z$%.]}, which matches any lower case letter -or @samp{$}, @samp{%}, or a period.@refill - -To include a @samp{]} in a character set, make it the first character. -For example, @samp{[]a]} matches @samp{]} or @samp{a}. To include a -@samp{-}, write @samp{-} as the first character in the set, or put it -immediately after a range. (You can replace one individual character -@var{c} with the range @samp{@var{c}-@var{c}} to make a place to put the -@samp{-}.) There is no way to write a set containing just @samp{-} and -@samp{]}. - -To include @samp{^} in a set, put it anywhere but at the beginning of -the set. - -@item [^ @dots{} ] -@cindex @samp{^} in regexp -@samp{[^} begins a @dfn{complement character set}, which matches any -character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} -matches all characters @emph{except} letters and digits.@refill - -@samp{^} is not special in a character set unless it is the first -character. The character following the @samp{^} is treated as if it -were first (thus, @samp{-} and @samp{]} are not special there). - -Note that a complement character set can match a newline, unless -newline is mentioned as one of the characters not to match. - -@item ^ -@cindex @samp{^} in regexp -@cindex beginning of line in regexp -is a special character that matches the empty string, but only at the -beginning of a line in the text being matched. Otherwise it fails to -match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at -the beginning of a line. - -When matching a string instead of a buffer, @samp{^} matches at the -beginning of the string or after a newline character @samp{\n}. - -@item $ -@cindex @samp{$} in regexp -is similar to @samp{^} but matches only at the end of a line. Thus, -@samp{x+$} matches a string of one @samp{x} or more at the end of a line. - -When matching a string instead of a buffer, @samp{$} matches at the end -of the string or before a newline character @samp{\n}. - -@item \ -@cindex @samp{\} in regexp -has two functions: it quotes the special characters (including -@samp{\}), and it introduces additional special constructs. - -Because @samp{\} quotes special characters, @samp{\$} is a regular -expression that matches only @samp{$}, and @samp{\[} is a regular -expression that matches only @samp{[}, and so on. - -Note that @samp{\} also has special meaning in the read syntax of Lisp -strings (@pxref{String Type}), and must be quoted with @samp{\}. For -example, the regular expression that matches the @samp{\} character is -@samp{\\}. To write a Lisp string that contains the characters -@samp{\\}, Lisp syntax requires you to quote each @samp{\} with another -@samp{\}. Therefore, the read syntax for a regular expression matching -@samp{\} is @code{"\\\\"}.@refill -@end table - -@strong{Please note:} For historical compatibility, special characters -are treated as ordinary ones if they are in contexts where their special -meanings make no sense. For example, @samp{*foo} treats @samp{*} as -ordinary since there is no preceding expression on which the @samp{*} -can act. It is poor practice to depend on this behavior; quote the -special character anyway, regardless of where it appears.@refill - -For the most part, @samp{\} followed by any character matches only -that character. However, there are several exceptions: characters -that, when preceded by @samp{\}, are special constructs. Such -characters are always ordinary when encountered on their own. Here -is a table of @samp{\} constructs: - -@table @kbd -@item \| -@cindex @samp{|} in regexp -@cindex regexp alternative -specifies an alternative. -Two regular expressions @var{a} and @var{b} with @samp{\|} in -between form an expression that matches anything that either @var{a} or -@var{b} matches.@refill - -Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} -but no other string.@refill - -@samp{\|} applies to the largest possible surrounding expressions. Only a -surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of -@samp{\|}.@refill - -Full backtracking capability exists to handle multiple uses of @samp{\|}. - -@item \( @dots{} \) -@cindex @samp{(} in regexp -@cindex @samp{)} in regexp -@cindex regexp grouping -is a grouping construct that serves three purposes: - -@enumerate -@item -To enclose a set of @samp{\|} alternatives for other operations. Thus, -the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox} -or @samp{barx}. - -@item -To enclose an expression for a suffix operator such as @samp{*} to act -on. Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any -(zero or more) number of @samp{na} strings.@refill - -@item -To record a matched substring for future reference. -@end enumerate - -This last application is not a consequence of the idea of a -parenthetical grouping; it is a separate feature that happens to be -assigned as a second meaning to the same @samp{\( @dots{} \)} construct -because there is no conflict in practice between the two meanings. -Here is an explanation of this feature: - -@item \@var{digit} -matches the same text that matched the @var{digit}th occurrence of a -@samp{\( @dots{} \)} construct. - -In other words, after the end of a @samp{\( @dots{} \)} construct. the -matcher remembers the beginning and end of the text matched by that -construct. Then, later on in the regular expression, you can use -@samp{\} followed by @var{digit} to match that same text, whatever it -may have been. - -The strings matching the first nine @samp{\( @dots{} \)} constructs -appearing in a regular expression are assigned numbers 1 through 9 in -the order that the open parentheses appear in the regular expression. -So you can use @samp{\1} through @samp{\9} to refer to the text matched -by the corresponding @samp{\( @dots{} \)} constructs. - -For example, @samp{\(.*\)\1} matches any newline-free string that is -composed of two identical halves. The @samp{\(.*\)} matches the first -half, which may be anything, but the @samp{\1} that follows must match -the same exact text. - -@item \w -@cindex @samp{\w} in regexp -matches any word-constituent character. The editor syntax table -determines which characters these are. @xref{Syntax Tables}. - -@item \W -@cindex @samp{\W} in regexp -matches any character that is not a word constituent. - -@item \s@var{code} -@cindex @samp{\s} in regexp -matches any character whose syntax is @var{code}. Here @var{code} is a -character that represents a syntax code: thus, @samp{w} for word -constituent, @samp{-} for whitespace, @samp{(} for open parenthesis, -etc. @xref{Syntax Tables}, for a list of syntax codes and the -characters that stand for them. - -@item \S@var{code} -@cindex @samp{\S} in regexp -matches any character whose syntax is not @var{code}. -@end table - - The following regular expression constructs match the empty string---that is, -they don't use up any characters---but whether they match depends on the -context. - -@table @kbd -@item \` -@cindex @samp{\`} in regexp -matches the empty string, but only at the beginning -of the buffer or string being matched against. - -@item \' -@cindex @samp{\'} in regexp -matches the empty string, but only at the end of -the buffer or string being matched against. - -@item \= -@cindex @samp{\=} in regexp -matches the empty string, but only at point. -(This construct is not defined when matching against a string.) - -@item \b -@cindex @samp{\b} in regexp -matches the empty string, but only at the beginning or -end of a word. Thus, @samp{\bfoo\b} matches any occurrence of -@samp{foo} as a separate word. @samp{\bballs?\b} matches -@samp{ball} or @samp{balls} as a separate word.@refill - -@item \B -@cindex @samp{\B} in regexp -matches the empty string, but @emph{not} at the beginning or -end of a word. - -@item \< -@cindex @samp{\<} in regexp -matches the empty string, but only at the beginning of a word. - -@item \> -@cindex @samp{\>} in regexp -matches the empty string, but only at the end of a word. -@end table - -@kindex invalid-regexp - Not every string is a valid regular expression. For example, a string -with unbalanced square brackets is invalid (with a few exceptions, such -as @samp{[]]}), and so is a string that ends with a single @samp{\}. If -an invalid regular expression is passed to any of the search functions, -an @code{invalid-regexp} error is signaled. - -@defun regexp-quote string -This function returns a regular expression string that matches exactly -@var{string} and nothing else. This allows you to request an exact -string match when calling a function that wants a regular expression. - -@example -@group -(regexp-quote "^The cat$") - @result{} "\\^The cat\\$" -@end group -@end example - -One use of @code{regexp-quote} is to combine an exact string match with -context described as a regular expression. For example, this searches -for the string that is the value of @code{string}, surrounded by -whitespace: - -@example -@group -(re-search-forward - (concat "\\s-" (regexp-quote string) "\\s-")) -@end group -@end example -@end defun - -@node Regexp Example -@comment node-name, next, previous, up -@subsection Complex Regexp Example - - Here is a complicated regexp, used by Emacs to recognize the end of a -sentence together with any whitespace that follows. It is the value of -the variable @code{sentence-end}. - - First, we show the regexp as a string in Lisp syntax to distinguish -spaces from tab characters. The string constant begins and ends with a -double-quote. @samp{\"} stands for a double-quote as part of the -string, @samp{\\} for a backslash as part of the string, @samp{\t} for a -tab and @samp{\n} for a newline. - -@example -"[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*" -@end example - - In contrast, if you evaluate the variable @code{sentence-end}, you -will see the following: - -@example -@group -sentence-end -@result{} -"[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[ -]*" -@end group -@end example - -@noindent -In this output, tab and newline appear as themselves. - - This regular expression contains four parts in succession and can be -deciphered as follows: - -@table @code -@item [.?!] -The first part of the pattern is a character set that matches any one of -three characters: period, question mark, and exclamation mark. The -match must begin with one of these three characters. - -@item []\"')@}]* -The second part of the pattern matches any closing braces and quotation -marks, zero or more of them, that may follow the period, question mark -or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in -a string. The @samp{*} at the end indicates that the immediately -preceding regular expression (a character set, in this case) may be -repeated zero or more times. - -@item \\($\\|@ $\\|\t\\|@ @ \\) -The third part of the pattern matches the whitespace that follows the -end of a sentence: the end of a line, or a tab, or two spaces. The -double backslashes mark the parentheses and vertical bars as regular -expression syntax; the parentheses delimit a group and the vertical bars -separate alternatives. The dollar sign is used to match the end of a -line. - -@item [ \t\n]* -Finally, the last part of the pattern matches any additional whitespace -beyond the minimum needed to end a sentence. -@end table - -@node Regexp Search -@section Regular Expression Searching -@cindex regular expression searching -@cindex regexp searching -@cindex searching for regexp - - In GNU Emacs, you can search for the next match for a regexp either -incrementally or not. For incremental search commands, see @ref{Regexp -Search, , Regular Expression Search, emacs, The GNU Emacs Manual}. Here -we describe only the search functions useful in programs. The principal -one is @code{re-search-forward}. - -@deffn Command re-search-forward regexp &optional limit noerror repeat -This function searches forward in the current buffer for a string of -text that is matched by the regular expression @var{regexp}. The -function skips over any amount of text that is not matched by -@var{regexp}, and leaves point at the end of the first match found. -It returns the new value of point. - -If @var{limit} is non-@code{nil} (it must be a position in the current -buffer), then it is the upper bound to the search. No match extending -after that position is accepted. - -What happens when the search fails depends on the value of -@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed} -error is signaled. If @var{noerror} is @code{t}, -@code{re-search-forward} does nothing and returns @code{nil}. If -@var{noerror} is neither @code{nil} nor @code{t}, then -@code{re-search-forward} moves point to @var{limit} (or the end of the -buffer) and returns @code{nil}. - -If @var{repeat} is supplied (it must be a positive number), then the -search is repeated that many times (each time starting at the end of the -previous time's match). If these successive searches succeed, the -function succeeds, moving point and returning its new value. Otherwise -the search fails. - -In the following example, point is initially before the @samp{T}. -Evaluating the search call moves point to the end of that line (between -the @samp{t} of @samp{hat} and the newline). - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- -@end group - -@group -(re-search-forward "[a-z]+" nil t 5) - @result{} 27 - ----------- Buffer: foo ---------- -I read "The cat in the hat@point{} -comes back" twice. ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command re-search-backward regexp &optional limit noerror repeat -This function searches backward in the current buffer for a string of -text that is matched by the regular expression @var{regexp}, leaving -point at the beginning of the first text found. - -This function is analogous to @code{re-search-forward}, but they are not -simple mirror images. @code{re-search-forward} finds the match whose -beginning is as close as possible to the starting point. If -@code{re-search-backward} were a perfect mirror image, it would find the -match whose end is as close as possible. However, in fact it finds the -match whose beginning is as close as possible. The reason is that -matching a regular expression at a given spot always works from -beginning to end, and starts at a specified beginning position. - -A true mirror-image of @code{re-search-forward} would require a special -feature for matching regexps from end to beginning. It's not worth the -trouble of implementing that. -@end deffn - -@defun string-match regexp string &optional start -This function returns the index of the start of the first match for -the regular expression @var{regexp} in @var{string}, or @code{nil} if -there is no match. If @var{start} is non-@code{nil}, the search starts -at that index in @var{string}. - -For example, - -@example -@group -(string-match - "quick" "The quick brown fox jumped quickly.") - @result{} 4 -@end group -@group -(string-match - "quick" "The quick brown fox jumped quickly." 8) - @result{} 27 -@end group -@end example - -@noindent -The index of the first character of the -string is 0, the index of the second character is 1, and so on. - -After this function returns, the index of the first character beyond -the match is available as @code{(match-end 0)}. @xref{Match Data}. - -@example -@group -(string-match - "quick" "The quick brown fox jumped quickly." 8) - @result{} 27 -@end group - -@group -(match-end 0) - @result{} 32 -@end group -@end example -@end defun - -@defun looking-at regexp -This function determines whether the text in the current buffer directly -following point matches the regular expression @var{regexp}. ``Directly -following'' means precisely that: the search is ``anchored'' and it can -succeed only starting with the first character following point. The -result is @code{t} if so, @code{nil} otherwise. - -This function does not move point, but it updates the match data, which -you can access using @code{match-beginning} and @code{match-end}. -@xref{Match Data}. - -In this example, point is located directly before the @samp{T}. If it -were anywhere else, the result would be @code{nil}. - -@example -@group ----------- Buffer: foo ---------- -I read "@point{}The cat in the hat -comes back" twice. ----------- Buffer: foo ---------- - -(looking-at "The cat in the hat$") - @result{} t -@end group -@end example -@end defun - -@node POSIX Regexps -@section POSIX Regular Expression Searching - - The usual regular expression functions do backtracking when necessary -to handle the @samp{\|} and repetition constructs, but they continue -this only until they find @emph{some} match. Then they succeed and -report the first match found. - - This section describes alternative search functions which perform the -full backtracking specified by the POSIX standard for regular expression -matching. They continue backtracking until they have tried all -possibilities and found all matches, so they can report the longest -match, as required by POSIX. This is much slower, so use these -functions only when you really need the longest match. - - In Emacs versions prior to 19.29, these functions did not exist, and -the functions described above implemented full POSIX backtracking. - -@defun posix-search-forward regexp &optional limit noerror repeat -This is like @code{re-search-forward} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@defun posix-search-backward regexp &optional limit noerror repeat -This is like @code{re-search-backward} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@defun posix-looking-at regexp -This is like @code{looking-at} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@defun posix-string-match regexp string &optional start -This is like @code{string-match} except that it performs the full -backtracking specified by the POSIX standard for regular expression -matching. -@end defun - -@ignore -@deffn Command delete-matching-lines regexp -This function is identical to @code{delete-non-matching-lines}, save -that it deletes what @code{delete-non-matching-lines} keeps. - -In the example below, point is located on the first line of text. - -@example -@group ----------- Buffer: foo ---------- -We hold these truths -to be self-evident, -that all men are created -equal, and that they are ----------- Buffer: foo ---------- -@end group - -@group -(delete-matching-lines "the") - @result{} nil - ----------- Buffer: foo ---------- -to be self-evident, -that all men are created ----------- Buffer: foo ---------- -@end group -@end example -@end deffn - -@deffn Command flush-lines regexp -This function is the same as @code{delete-matching-lines}. -@end deffn - -@defun delete-non-matching-lines regexp -This function deletes all lines following point which don't -contain a match for the regular expression @var{regexp}. -@end defun - -@deffn Command keep-lines regexp -This function is the same as @code{delete-non-matching-lines}. -@end deffn - -@deffn Command how-many regexp -This function counts the number of matches for @var{regexp} there are in -the current buffer following point. It prints this number in -the echo area, returning the string printed. -@end deffn - -@deffn Command count-matches regexp -This function is a synonym of @code{how-many}. -@end deffn - -@deffn Command list-matching-lines regexp nlines -This function is a synonym of @code{occur}. -Show all lines following point containing a match for @var{regexp}. -Display each line with @var{nlines} lines before and after, -or @code{-}@var{nlines} before if @var{nlines} is negative. -@var{nlines} defaults to @code{list-matching-lines-default-context-lines}. -Interactively it is the prefix arg. - -The lines are shown in a buffer named @samp{*Occur*}. -It serves as a menu to find any of the occurrences in this buffer. -@kbd{C-h m} (@code{describe-mode} in that buffer gives help. -@end deffn - -@defopt list-matching-lines-default-context-lines -Default value is 0. -Default number of context lines to include around a @code{list-matching-lines} -match. A negative number means to include that many lines before the match. -A positive number means to include that many lines both before and after. -@end defopt -@end ignore - -@node Search and Replace -@section Search and Replace -@cindex replacement - -@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map -This function is the guts of @code{query-replace} and related commands. -It searches for occurrences of @var{from-string} and replaces some or -all of them. If @var{query-flag} is @code{nil}, it replaces all -occurrences; otherwise, it asks the user what to do about each one. - -If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is -considered a regular expression; otherwise, it must match literally. If -@var{delimited-flag} is non-@code{nil}, then only replacements -surrounded by word boundaries are considered. - -The argument @var{replacements} specifies what to replace occurrences -with. If it is a string, that string is used. It can also be a list of -strings, to be used in cyclic order. - -If @var{repeat-count} is non-@code{nil}, it should be an integer. Then -it specifies how many times to use each of the strings in the -@var{replacements} list before advancing cyclicly to the next one. - -Normally, the keymap @code{query-replace-map} defines the possible user -responses for queries. The argument @var{map}, if non-@code{nil}, is a -keymap to use instead of @code{query-replace-map}. -@end defun - -@defvar query-replace-map -This variable holds a special keymap that defines the valid user -responses for @code{query-replace} and related functions, as well as -@code{y-or-n-p} and @code{map-y-or-n-p}. It is unusual in two ways: - -@itemize @bullet -@item -The ``key bindings'' are not commands, just symbols that are meaningful -to the functions that use this map. - -@item -Prefix keys are not supported; each key binding must be for a single event -key sequence. This is because the functions don't use read key sequence to -get the input; instead, they read a single event and look it up ``by hand.'' -@end itemize -@end defvar - -Here are the meaningful ``bindings'' for @code{query-replace-map}. -Several of them are meaningful only for @code{query-replace} and -friends. - -@table @code -@item act -Do take the action being considered---in other words, ``yes.'' - -@item skip -Do not take action for this question---in other words, ``no.'' - -@item exit -Answer this question ``no,'' and give up on the entire series of -questions, assuming that the answers will be ``no.'' - -@item act-and-exit -Answer this question ``yes,'' and give up on the entire series of -questions, assuming that subsequent answers will be ``no.'' - -@item act-and-show -Answer this question ``yes,'' but show the results---don't advance yet -to the next question. - -@item automatic -Answer this question and all subsequent questions in the series with -``yes,'' without further user interaction. - -@item backup -Move back to the previous place that a question was asked about. - -@item edit -Enter a recursive edit to deal with this question---instead of any -other action that would normally be taken. - -@item delete-and-edit -Delete the text being considered, then enter a recursive edit to replace -it. - -@item recenter -Redisplay and center the window, then ask the same question again. - -@item quit -Perform a quit right away. Only @code{y-or-n-p} and related functions -use this answer. - -@item help -Display some help, then ask again. -@end table - -@node Match Data -@section The Match Data -@cindex match data - - Emacs keeps track of the positions of the start and end of segments of -text found during a regular expression search. This means, for example, -that you can search for a complex pattern, such as a date in an Rmail -message, and then extract parts of the match under control of the -pattern. - - Because the match data normally describe the most recent search only, -you must be careful not to do another search inadvertently between the -search you wish to refer back to and the use of the match data. If you -can't avoid another intervening search, you must save and restore the -match data around it, to prevent it from being overwritten. - -@menu -* Simple Match Data:: Accessing single items of match data, - such as where a particular subexpression started. -* Replacing Match:: Replacing a substring that was matched. -* Entire Match Data:: Accessing the entire match data at once, as a list. -* Saving Match Data:: Saving and restoring the match data. -@end menu - -@node Simple Match Data -@subsection Simple Match Data Access - - This section explains how to use the match data to find out what was -matched by the last search or match operation. - - You can ask about the entire matching text, or about a particular -parenthetical subexpression of a regular expression. The @var{count} -argument in the functions below specifies which. If @var{count} is -zero, you are asking about the entire match. If @var{count} is -positive, it specifies which subexpression you want. - - Recall that the subexpressions of a regular expression are those -expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The -@var{count}th subexpression is found by counting occurrences of -@samp{\(} from the beginning of the whole regular expression. The first -subexpression is numbered 1, the second 2, and so on. Only regular -expressions can have subexpressions---after a simple string search, the -only information available is about the entire match. - -@defun match-string count &optional in-string -This function returns, as a string, the text matched in the last search -or match operation. It returns the entire text if @var{count} is zero, -or just the portion corresponding to the @var{count}th parenthetical -subexpression, if @var{count} is positive. If @var{count} is out of -range, or if that subexpression didn't match anything, the value is -@code{nil}. - -If the last such operation was done against a string with -@code{string-match}, then you should pass the same string as the -argument @var{in-string}. Otherwise, after a buffer search or match, -you should omit @var{in-string} or pass @code{nil} for it; but you -should make sure that the current buffer when you call -@code{match-string} is the one in which you did the searching or -matching. -@end defun - -@defun match-beginning count -This function returns the position of the start of text matched by the -last regular expression searched for, or a subexpression of it. - -If @var{count} is zero, then the value is the position of the start of -the entire match. Otherwise, @var{count} specifies a subexpression in -the regular expresion, and the value of the function is the starting -position of the match for that subexpression. - -The value is @code{nil} for a subexpression inside a @samp{\|} -alternative that wasn't used in the match. -@end defun - -@defun match-end count -This function is like @code{match-beginning} except that it returns the -position of the end of the match, rather than the position of the -beginning. -@end defun - - Here is an example of using the match data, with a comment showing the -positions within the text: - -@example -@group -(string-match "\\(qu\\)\\(ick\\)" - "The quick fox jumped quickly.") - ;0123456789 - @result{} 4 -@end group - -@group -(match-string 0 "The quick fox jumped quickly.") - @result{} "quick" -(match-string 1 "The quick fox jumped quickly.") - @result{} "qu" -(match-string 2 "The quick fox jumped quickly.") - @result{} "ick" -@end group - -@group -(match-beginning 1) ; @r{The beginning of the match} - @result{} 4 ; @r{with @samp{qu} is at index 4.} -@end group - -@group -(match-beginning 2) ; @r{The beginning of the match} - @result{} 6 ; @r{with @samp{ick} is at index 6.} -@end group - -@group -(match-end 1) ; @r{The end of the match} - @result{} 6 ; @r{with @samp{qu} is at index 6.} - -(match-end 2) ; @r{The end of the match} - @result{} 9 ; @r{with @samp{ick} is at index 9.} -@end group -@end example - - Here is another example. Point is initially located at the beginning -of the line. Searching moves point to between the space and the word -@samp{in}. The beginning of the entire match is at the 9th character of -the buffer (@samp{T}), and the beginning of the match for the first -subexpression is at the 13th character (@samp{c}). - -@example -@group -(list - (re-search-forward "The \\(cat \\)") - (match-beginning 0) - (match-beginning 1)) - @result{} (9 9 13) -@end group - -@group ----------- Buffer: foo ---------- -I read "The cat @point{}in the hat comes back" twice. - ^ ^ - 9 13 ----------- Buffer: foo ---------- -@end group -@end example - -@noindent -(In this case, the index returned is a buffer position; the first -character of the buffer counts as 1.) - -@node Replacing Match -@subsection Replacing the Text That Matched - - This function replaces the text matched by the last search with -@var{replacement}. - -@cindex case in replacements -@defun replace-match replacement &optional fixedcase literal string subexp -This function replaces the text in the buffer (or in @var{string}) that -was matched by the last search. It replaces that text with -@var{replacement}. - -If you did the last search in a buffer, you should specify @code{nil} -for @var{string}. Then @code{replace-match} does the replacement by -editing the buffer; it leaves point at the end of the replacement text, -and returns @code{t}. - -If you did the search in a string, pass the same string as @var{string}. -Then @code{replace-match} does the replacement by constructing and -returning a new string. - -If @var{fixedcase} is non-@code{nil}, then the case of the replacement -text is not changed; otherwise, the replacement text is converted to a -different case depending upon the capitalization of the text to be -replaced. If the original text is all upper case, the replacement text -is converted to upper case. If the first word of the original text is -capitalized, then the first word of the replacement text is capitalized. -If the original text contains just one word, and that word is a capital -letter, @code{replace-match} considers this a capitalized first word -rather than all upper case. - -If @code{case-replace} is @code{nil}, then case conversion is not done, -regardless of the value of @var{fixed-case}. @xref{Searching and Case}. - -If @var{literal} is non-@code{nil}, then @var{replacement} is inserted -exactly as it is, the only alterations being case changes as needed. -If it is @code{nil} (the default), then the character @samp{\} is treated -specially. If a @samp{\} appears in @var{replacement}, then it must be -part of one of the following sequences: - -@table @asis -@item @samp{\&} -@cindex @samp{&} in replacement -@samp{\&} stands for the entire text being replaced. - -@item @samp{\@var{n}} -@cindex @samp{\@var{n}} in replacement -@samp{\@var{n}}, where @var{n} is a digit, stands for the text that -matched the @var{n}th subexpression in the original regexp. -Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}. - -@item @samp{\\} -@cindex @samp{\} in replacement -@samp{\\} stands for a single @samp{\} in the replacement text. -@end table - -If @var{subexp} is non-@code{nil}, that says to replace just -subexpression number @var{subexp} of the regexp that was matched, not -the entire match. For example, after matching @samp{foo \(ba*r\)}, -calling @code{replace-match} with 1 as @var{subexp} means to replace -just the text that matched @samp{\(ba*r\)}. -@end defun - -@node Entire Match Data -@subsection Accessing the Entire Match Data - - The functions @code{match-data} and @code{set-match-data} read or -write the entire match data, all at once. - -@defun match-data -This function returns a newly constructed list containing all the -information on what text the last search matched. Element zero is the -position of the beginning of the match for the whole expression; element -one is the position of the end of the match for the expression. The -next two elements are the positions of the beginning and end of the -match for the first subexpression, and so on. In general, element -@ifinfo -number 2@var{n} -@end ifinfo -@tex -number {\mathsurround=0pt $2n$} -@end tex -corresponds to @code{(match-beginning @var{n})}; and -element -@ifinfo -number 2@var{n} + 1 -@end ifinfo -@tex -number {\mathsurround=0pt $2n+1$} -@end tex -corresponds to @code{(match-end @var{n})}. - -All the elements are markers or @code{nil} if matching was done on a -buffer, and all are integers or @code{nil} if matching was done on a -string with @code{string-match}. (In Emacs 18 and earlier versions, -markers were used even for matching on a string, except in the case -of the integer 0.) - -As always, there must be no possibility of intervening searches between -the call to a search function and the call to @code{match-data} that is -intended to access the match data for that search. - -@example -@group -(match-data) - @result{} (#<marker at 9 in foo> - #<marker at 17 in foo> - #<marker at 13 in foo> - #<marker at 17 in foo>) -@end group -@end example -@end defun - -@defun set-match-data match-list -This function sets the match data from the elements of @var{match-list}, -which should be a list that was the value of a previous call to -@code{match-data}. - -If @var{match-list} refers to a buffer that doesn't exist, you don't get -an error; that sets the match data in a meaningless but harmless way. - -@findex store-match-data -@code{store-match-data} is an alias for @code{set-match-data}. -@end defun - -@node Saving Match Data -@subsection Saving and Restoring the Match Data - - When you call a function that may do a search, you may need to save -and restore the match data around that call, if you want to preserve the -match data from an earlier search for later use. Here is an example -that shows the problem that arises if you fail to save the match data: - -@example -@group -(re-search-forward "The \\(cat \\)") - @result{} 48 -(foo) ; @r{Perhaps @code{foo} does} - ; @r{more searching.} -(match-end 0) - @result{} 61 ; @r{Unexpected result---not 48!} -@end group -@end example - - You can save and restore the match data with @code{save-match-data}: - -@defmac save-match-data body@dots{} -This special form executes @var{body}, saving and restoring the match -data around it. -@end defmac - - You can use @code{set-match-data} together with @code{match-data} to -imitate the effect of the special form @code{save-match-data}. This is -useful for writing code that can run in Emacs 18. Here is how: - -@example -@group -(let ((data (match-data))) - (unwind-protect - @dots{} ; @r{May change the original match data.} - (set-match-data data))) -@end group -@end example - - Emacs automatically saves and restores the match data when it runs -process filter functions (@pxref{Filter Functions}) and process -sentinels (@pxref{Sentinels}). - -@ignore - Here is a function which restores the match data provided the buffer -associated with it still exists. - -@smallexample -@group -(defun restore-match-data (data) -@c It is incorrect to split the first line of a doc string. -@c If there's a problem here, it should be solved in some other way. - "Restore the match data DATA unless the buffer is missing." - (catch 'foo - (let ((d data)) -@end group - (while d - (and (car d) - (null (marker-buffer (car d))) -@group - ;; @file{match-data} @r{buffer is deleted.} - (throw 'foo nil)) - (setq d (cdr d))) - (set-match-data data)))) -@end group -@end smallexample -@end ignore - -@node Searching and Case -@section Searching and Case -@cindex searching and case - - By default, searches in Emacs ignore the case of the text they are -searching through; if you specify searching for @samp{FOO}, then -@samp{Foo} or @samp{foo} is also considered a match. Regexps, and in -particular character sets, are included: thus, @samp{[aB]} would match -@samp{a} or @samp{A} or @samp{b} or @samp{B}. - - If you do not want this feature, set the variable -@code{case-fold-search} to @code{nil}. Then all letters must match -exactly, including case. This is a buffer-local variable; altering the -variable affects only the current buffer. (@xref{Intro to -Buffer-Local}.) Alternatively, you may change the value of -@code{default-case-fold-search}, which is the default value of -@code{case-fold-search} for buffers that do not override it. - - Note that the user-level incremental search feature handles case -distinctions differently. When given a lower case letter, it looks for -a match of either case, but when given an upper case letter, it looks -for an upper case letter only. But this has nothing to do with the -searching functions Lisp functions use. - -@defopt case-replace -This variable determines whether the replacement functions should -preserve case. If the variable is @code{nil}, that means to use the -replacement text verbatim. A non-@code{nil} value means to convert the -case of the replacement text according to the text being replaced. - -The function @code{replace-match} is where this variable actually has -its effect. @xref{Replacing Match}. -@end defopt - -@defopt case-fold-search -This buffer-local variable determines whether searches should ignore -case. If the variable is @code{nil} they do not ignore case; otherwise -they do ignore case. -@end defopt - -@defvar default-case-fold-search -The value of this variable is the default value for -@code{case-fold-search} in buffers that do not override it. This is the -same as @code{(default-value 'case-fold-search)}. -@end defvar - -@node Standard Regexps -@section Standard Regular Expressions Used in Editing -@cindex regexps used standardly in editing -@cindex standard regexps used in editing - - This section describes some variables that hold regular expressions -used for certain purposes in editing: - -@defvar page-delimiter -This is the regexp describing line-beginnings that separate pages. The -default value is @code{"^\014"} (i.e., @code{"^^L"} or @code{"^\C-l"}); -this matches a line that starts with a formfeed character. -@end defvar - - The following two regular expressions should @emph{not} assume the -match always starts at the beginning of a line; they should not use -@samp{^} to anchor the match. Most often, the paragraph commands do -check for a match only at the beginning of a line, which means that -@samp{^} would be superfluous. When there is a nonzero left margin, -they accept matches that start after the left margin. In that case, a -@samp{^} would be incorrect. However, a @samp{^} is harmless in modes -where a left margin is never used. - -@defvar paragraph-separate -This is the regular expression for recognizing the beginning of a line -that separates paragraphs. (If you change this, you may have to -change @code{paragraph-start} also.) The default value is -@w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of -spaces, tabs, and form feeds (after its left margin). -@end defvar - -@defvar paragraph-start -This is the regular expression for recognizing the beginning of a line -that starts @emph{or} separates paragraphs. The default value is -@w{@code{"[@ \t\n\f]"}}, which matches a line starting with a space, tab, -newline, or form feed (after its left margin). -@end defvar - -@defvar sentence-end -This is the regular expression describing the end of a sentence. (All -paragraph boundaries also end sentences, regardless.) The default value -is: - -@example -"[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*" -@end example - -This means a period, question mark or exclamation mark, followed -optionally by a closing parenthetical character, followed by tabs, -spaces or new lines. - -For a detailed explanation of this regular expression, see @ref{Regexp -Example}. -@end defvar diff --git a/lispref/sequences.texi b/lispref/sequences.texi deleted file mode 100644 index c6de3f1c94d..00000000000 --- a/lispref/sequences.texi +++ /dev/null @@ -1,493 +0,0 @@ -@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/sequences -@node Sequences Arrays Vectors, Symbols, Lists, Top -@chapter Sequences, Arrays, and Vectors -@cindex sequence - - Recall that the @dfn{sequence} type is the union of three other Lisp -types: lists, vectors, and strings. In other words, any list is a -sequence, any vector is a sequence, and any string is a sequence. The -common property that all sequences have is that each is an ordered -collection of elements. - - An @dfn{array} is a single primitive object that has a slot for each -elements. All the elements are accessible in constant time, but the -length of an existing array cannot be changed. Strings and vectors are -the two types of arrays. - - A list is a sequence of elements, but it is not a single primitive -object; it is made of cons cells, one cell per element. Finding the -@var{n}th element requires looking through @var{n} cons cells, so -elements farther from the beginning of the list take longer to access. -But it is possible to add elements to the list, or remove elements. - - The following diagram shows the relationship between these types: - -@example -@group - ___________________________________ - | | - | Sequence | - | ______ ______________________ | - | | | | | | - | | List | | Array | | - | | | | ________ _______ | | - | |______| | | | | | | | - | | | Vector | | String| | | - | | |________| |_______| | | - | |______________________| | - |___________________________________| -@end group -@end example - - The elements of vectors and lists may be any Lisp objects. The -elements of strings are all characters. - -@menu -* Sequence Functions:: Functions that accept any kind of sequence. -* Arrays:: Characteristics of arrays in Emacs Lisp. -* Array Functions:: Functions specifically for arrays. -* Vectors:: Special characteristics of Emacs Lisp vectors. -* Vector Functions:: Functions specifically for vectors. -@end menu - -@node Sequence Functions -@section Sequences - - In Emacs Lisp, a @dfn{sequence} is either a list, a vector or a -string. The common property that all sequences have is that each is an -ordered collection of elements. This section describes functions that -accept any kind of sequence. - -@defun sequencep object -Returns @code{t} if @var{object} is a list, vector, or -string, @code{nil} otherwise. -@end defun - -@defun copy-sequence sequence -@cindex copying sequences -Returns a copy of @var{sequence}. The copy is the same type of object -as the original sequence, and it has the same elements in the same order. - -Storing a new element into the copy does not affect the original -@var{sequence}, and vice versa. However, the elements of the new -sequence are not copies; they are identical (@code{eq}) to the elements -of the original. Therefore, changes made within these elements, as -found via the copied sequence, are also visible in the original -sequence. - -If the sequence is a string with text properties, the property list in -the copy is itself a copy, not shared with the original's property -list. However, the actual values of the properties are shared. -@xref{Text Properties}. - -See also @code{append} in @ref{Building Lists}, @code{concat} in -@ref{Creating Strings}, and @code{vconcat} in @ref{Vectors}, for others -ways to copy sequences. - -@example -@group -(setq bar '(1 2)) - @result{} (1 2) -@end group -@group -(setq x (vector 'foo bar)) - @result{} [foo (1 2)] -@end group -@group -(setq y (copy-sequence x)) - @result{} [foo (1 2)] -@end group - -@group -(eq x y) - @result{} nil -@end group -@group -(equal x y) - @result{} t -@end group -@group -(eq (elt x 1) (elt y 1)) - @result{} t -@end group - -@group -;; @r{Replacing an element of one sequence.} -(aset x 0 'quux) -x @result{} [quux (1 2)] -y @result{} [foo (1 2)] -@end group - -@group -;; @r{Modifying the inside of a shared element.} -(setcar (aref x 1) 69) -x @result{} [quux (69 2)] -y @result{} [foo (69 2)] -@end group -@end example -@end defun - -@defun length sequence -@cindex string length -@cindex list length -@cindex vector length -@cindex sequence length -Returns the number of elements in @var{sequence}. If @var{sequence} is -a cons cell that is not a list (because the final @sc{cdr} is not -@code{nil}), a @code{wrong-type-argument} error is signaled. - -@example -@group -(length '(1 2 3)) - @result{} 3 -@end group -@group -(length ()) - @result{} 0 -@end group -@group -(length "foobar") - @result{} 6 -@end group -@group -(length [1 2 3]) - @result{} 3 -@end group -@end example -@end defun - -@defun elt sequence index -@cindex elements of sequences -This function returns the element of @var{sequence} indexed by -@var{index}. Legitimate values of @var{index} are integers ranging from -0 up to one less than the length of @var{sequence}. If @var{sequence} -is a list, then out-of-range values of @var{index} return @code{nil}; -otherwise, they trigger an @code{args-out-of-range} error. - -@example -@group -(elt [1 2 3 4] 2) - @result{} 3 -@end group -@group -(elt '(1 2 3 4) 2) - @result{} 3 -@end group -@group -(char-to-string (elt "1234" 2)) - @result{} "3" -@end group -@group -(elt [1 2 3 4] 4) - @error{}Args out of range: [1 2 3 4], 4 -@end group -@group -(elt [1 2 3 4] -1) - @error{}Args out of range: [1 2 3 4], -1 -@end group -@end example - -This function generalizes @code{aref} (@pxref{Array Functions}) and -@code{nth} (@pxref{List Elements}). -@end defun - -@node Arrays -@section Arrays -@cindex array - - An @dfn{array} object has slots that hold a number of other Lisp -objects, called the elements of the array. Any element of an array may -be accessed in constant time. In contrast, an element of a list -requires access time that is proportional to the position of the element -in the list. - - When you create an array, you must specify how many elements it has. -The amount of space allocated depends on the number of elements. -Therefore, it is impossible to change the size of an array once it is -created; you cannot add or remove elements. However, you can replace an -element with a different value. - - Emacs defines two types of array, both of which are one-dimensional: -@dfn{strings} and @dfn{vectors}. A vector is a general array; its -elements can be any Lisp objects. A string is a specialized array; its -elements must be characters (i.e., integers between 0 and 255). Each -type of array has its own read syntax. @xref{String Type}, and -@ref{Vector Type}. - - Both kinds of array share these characteristics: - -@itemize @bullet -@item -The first element of an array has index zero, the second element has -index 1, and so on. This is called @dfn{zero-origin} indexing. For -example, an array of four elements has indices 0, 1, 2, @w{and 3}. - -@item -The elements of an array may be referenced or changed with the functions -@code{aref} and @code{aset}, respectively (@pxref{Array Functions}). -@end itemize - - In principle, if you wish to have an array of text characters, you -could use either a string or a vector. In practice, we always choose -strings for such applications, for four reasons: - -@itemize @bullet -@item -They occupy one-fourth the space of a vector of the same elements. - -@item -Strings are printed in a way that shows the contents more clearly -as characters. - -@item -Strings can hold text properties. @xref{Text Properties}. - -@item -Many of the specialized editing and I/O facilities of Emacs accept only -strings. For example, you cannot insert a vector of characters into a -buffer the way you can insert a string. @xref{Strings and Characters}. -@end itemize - - By contrast, for an array of keyboard input characters (such as a key -sequence), a vector may be necessary, because many keyboard input -characters are outside the range that will fit in a string. @xref{Key -Sequence Input}. - -@node Array Functions -@section Functions that Operate on Arrays - - In this section, we describe the functions that accept both strings -and vectors. - -@defun arrayp object -This function returns @code{t} if @var{object} is an array (i.e., either a -vector or a string). - -@example -@group -(arrayp [a]) -@result{} t -(arrayp "asdf") -@result{} t -@end group -@end example -@end defun - -@defun aref array index -@cindex array elements -This function returns the @var{index}th element of @var{array}. The -first element is at index zero. - -@example -@group -(setq primes [2 3 5 7 11 13]) - @result{} [2 3 5 7 11 13] -(aref primes 4) - @result{} 11 -(elt primes 4) - @result{} 11 -@end group - -@group -(aref "abcdefg" 1) - @result{} 98 ; @r{@samp{b} is @sc{ASCII} code 98.} -@end group -@end example - -See also the function @code{elt}, in @ref{Sequence Functions}. -@end defun - -@defun aset array index object -This function sets the @var{index}th element of @var{array} to be -@var{object}. It returns @var{object}. - -@example -@group -(setq w [foo bar baz]) - @result{} [foo bar baz] -(aset w 0 'fu) - @result{} fu -w - @result{} [fu bar baz] -@end group - -@group -(setq x "asdfasfd") - @result{} "asdfasfd" -(aset x 3 ?Z) - @result{} 90 -x - @result{} "asdZasfd" -@end group -@end example - -If @var{array} is a string and @var{object} is not a character, a -@code{wrong-type-argument} error results. -@end defun - -@defun fillarray array object -This function fills the array @var{array} with @var{object}, so that -each element of @var{array} is @var{object}. It returns @var{array}. - -@example -@group -(setq a [a b c d e f g]) - @result{} [a b c d e f g] -(fillarray a 0) - @result{} [0 0 0 0 0 0 0] -a - @result{} [0 0 0 0 0 0 0] -@end group -@group -(setq s "When in the course") - @result{} "When in the course" -(fillarray s ?-) - @result{} "------------------" -@end group -@end example - -If @var{array} is a string and @var{object} is not a character, a -@code{wrong-type-argument} error results. -@end defun - -The general sequence functions @code{copy-sequence} and @code{length} -are often useful for objects known to be arrays. @xref{Sequence Functions}. - -@node Vectors -@section Vectors -@cindex vector - - Arrays in Lisp, like arrays in most languages, are blocks of memory -whose elements can be accessed in constant time. A @dfn{vector} is a -general-purpose array; its elements can be any Lisp objects. (The other -kind of array in Emacs Lisp is the @dfn{string}, whose elements must be -characters.) Vectors in Emacs serve as syntax tables (vectors of -integers), as obarrays (vectors of symbols), and in keymaps (vectors of -commands). They are also used internally as part of the representation -of a byte-compiled function; if you print such a function, you will see -a vector in it. - - In Emacs Lisp, the indices of the elements of a vector start from zero -and count up from there. - - Vectors are printed with square brackets surrounding the elements. -Thus, a vector whose elements are the symbols @code{a}, @code{b} and -@code{a} is printed as @code{[a b a]}. You can write vectors in the -same way in Lisp input. - - A vector, like a string or a number, is considered a constant for -evaluation: the result of evaluating it is the same vector. This does -not evaluate or even examine the elements of the vector. -@xref{Self-Evaluating Forms}. - - Here are examples of these principles: - -@example -@group -(setq avector [1 two '(three) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] -(eval avector) - @result{} [1 two (quote (three)) "four" [five]] -(eq avector (eval avector)) - @result{} t -@end group -@end example - -@node Vector Functions -@section Functions That Operate on Vectors - - Here are some functions that relate to vectors: - -@defun vectorp object -This function returns @code{t} if @var{object} is a vector. - -@example -@group -(vectorp [a]) - @result{} t -(vectorp "asdf") - @result{} nil -@end group -@end example -@end defun - -@defun vector &rest objects -This function creates and returns a vector whose elements are the -arguments, @var{objects}. - -@example -@group -(vector 'foo 23 [bar baz] "rats") - @result{} [foo 23 [bar baz] "rats"] -(vector) - @result{} [] -@end group -@end example -@end defun - -@defun make-vector length object -This function returns a new vector consisting of @var{length} elements, -each initialized to @var{object}. - -@example -@group -(setq sleepy (make-vector 9 'Z)) - @result{} [Z Z Z Z Z Z Z Z Z] -@end group -@end example -@end defun - -@defun vconcat &rest sequences -@cindex copying vectors -This function returns a new vector containing all the elements of the -@var{sequences}. The arguments @var{sequences} may be lists, vectors, -or strings. If no @var{sequences} are given, an empty vector is -returned. - -The value is a newly constructed vector that is not @code{eq} to any -existing vector. - -@example -@group -(setq a (vconcat '(A B C) '(D E F))) - @result{} [A B C D E F] -(eq a (vconcat a)) - @result{} nil -@end group -@group -(vconcat) - @result{} [] -(vconcat [A B C] "aa" '(foo (6 7))) - @result{} [A B C 97 97 foo (6 7)] -@end group -@end example - -The @code{vconcat} function also allows integers as arguments. It -converts them to strings of digits, making up the decimal print -representation of the integer, and then uses the strings instead of the -original integers. @strong{Don't use this feature; we plan to eliminate -it. If you already use this feature, change your programs now!} The -proper way to convert an integer to a decimal number in this way is with -@code{format} (@pxref{Formatting Strings}) or @code{number-to-string} -(@pxref{String Conversion}). - -For other concatenation functions, see @code{mapconcat} in @ref{Mapping -Functions}, @code{concat} in @ref{Creating Strings}, and @code{append} -in @ref{Building Lists}. -@end defun - - The @code{append} function provides a way to convert a vector into a -list with the same elements (@pxref{Building Lists}): - -@example -@group -(setq avector [1 two (quote (three)) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] -(append avector nil) - @result{} (1 two (quote (three)) "four" [five]) -@end group -@end example diff --git a/lispref/streams.texi b/lispref/streams.texi deleted file mode 100644 index 4088c80ad7f..00000000000 --- a/lispref/streams.texi +++ /dev/null @@ -1,735 +0,0 @@ -@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/streams -@node Read and Print, Minibuffers, Debugging, Top -@comment node-name, next, previous, up -@chapter Reading and Printing Lisp Objects - - @dfn{Printing} and @dfn{reading} are the operations of converting Lisp -objects to textual form and vice versa. They use the printed -representations and read syntax described in @ref{Lisp Data Types}. - - This chapter describes the Lisp functions for reading and printing. -It also describes @dfn{streams}, which specify where to get the text (if -reading) or where to put it (if printing). - -@menu -* Streams Intro:: Overview of streams, reading and printing. -* Input Streams:: Various data types that can be used as input streams. -* Input Functions:: Functions to read Lisp objects from text. -* Output Streams:: Various data types that can be used as output streams. -* Output Functions:: Functions to print Lisp objects as text. -* Output Variables:: Variables that control what the printing functions do. -@end menu - -@node Streams Intro -@section Introduction to Reading and Printing -@cindex Lisp reader -@cindex printing -@cindex reading - - @dfn{Reading} a Lisp object means parsing a Lisp expression in textual -form and producing a corresponding Lisp object. This is how Lisp -programs get into Lisp from files of Lisp code. We call the text the -@dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)} -is the read syntax for a cons cell whose @sc{car} is @code{a} and whose -@sc{cdr} is the number 5. - - @dfn{Printing} a Lisp object means producing text that represents that -object---converting the object to its printed representation. Printing -the cons cell described above produces the text @samp{(a .@: 5)}. - - Reading and printing are more or less inverse operations: printing the -object that results from reading a given piece of text often produces -the same text, and reading the text that results from printing an object -usually produces a similar-looking object. For example, printing the -symbol @code{foo} produces the text @samp{foo}, and reading that text -returns the symbol @code{foo}. Printing a list whose elements are -@code{a} and @code{b} produces the text @samp{(a b)}, and reading that -text produces a list (but not the same list) with elements @code{a} -and @code{b}. - - However, these two operations are not precisely inverses. There are -three kinds of exceptions: - -@itemize @bullet -@item -Printing can produce text that cannot be read. For example, buffers, -windows, frames, subprocesses and markers print into text that starts -with @samp{#}; if you try to read this text, you get an error. There is -no way to read those data types. - -@item -One object can have multiple textual representations. For example, -@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and -@samp{(a .@: (b))} represent the same list. Reading will accept any of -the alternatives, but printing must choose one of them. - -@item -Comments can appear at certain points in the middle of an object's -read sequence without affecting the result of reading it. -@end itemize - -@node Input Streams -@section Input Streams -@cindex stream (for reading) -@cindex input stream - - Most of the Lisp functions for reading text take an @dfn{input stream} -as an argument. The input stream specifies where or how to get the -characters of the text to be read. Here are the possible types of input -stream: - -@table @asis -@item @var{buffer} -@cindex buffer input stream -The input characters are read from @var{buffer}, starting with the -character directly after point. Point advances as characters are read. - -@item @var{marker} -@cindex marker input stream -The input characters are read from the buffer that @var{marker} is in, -starting with the character directly after the marker. The marker -position advances as characters are read. The value of point in the -buffer has no effect when the stream is a marker. - -@item @var{string} -@cindex string input stream -The input characters are taken from @var{string}, starting at the first -character in the string and using as many characters as required. - -@item @var{function} -@cindex function input stream -The input characters are generated by @var{function}, one character per -call. Normally @var{function} is called with no arguments, and should -return a character. - -@cindex unreading -Occasionally @var{function} is called with one argument (always a -character). When that happens, @var{function} should save the argument -and arrange to return it on the next call. This is called -@dfn{unreading} the character; it happens when the Lisp reader reads one -character too many and wants to ``put it back where it came from''. - -@item @code{t} -@cindex @code{t} input stream -@code{t} used as a stream means that the input is read from the -minibuffer. In fact, the minibuffer is invoked once and the text -given by the user is made into a string that is then used as the -input stream. - -@item @code{nil} -@cindex @code{nil} input stream -@code{nil} supplied as an input stream means to use the value of -@code{standard-input} instead; that value is the @dfn{default input -stream}, and must be a non-@code{nil} input stream. - -@item @var{symbol} -A symbol as input stream is equivalent to the symbol's function -definition (if any). -@end table - - Here is an example of reading from a stream that is a buffer, showing -where point is located before and after: - -@example -@group ----------- Buffer: foo ---------- -This@point{} is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(read (get-buffer "foo")) - @result{} is -@end group -@group -(read (get-buffer "foo")) - @result{} the -@end group - -@group ----------- Buffer: foo ---------- -This is the@point{} contents of foo. ----------- Buffer: foo ---------- -@end group -@end example - -@noindent -Note that the first read skips a space. Reading skips any amount of -whitespace preceding the significant text. - - In Emacs 18, reading a symbol discarded the delimiter terminating the -symbol. Thus, point would end up at the beginning of @samp{contents} -rather than after @samp{the}. The Emacs 19 behavior is superior because -it correctly handles input such as @samp{bar(foo)}, where the -open-parenthesis that ends one object is needed as the beginning of -another object. - - Here is an example of reading from a stream that is a marker, -initially positioned at the beginning of the buffer shown. The value -read is the symbol @code{This}. - -@example -@group - ----------- Buffer: foo ---------- -This is the contents of foo. ----------- Buffer: foo ---------- -@end group - -@group -(setq m (set-marker (make-marker) 1 (get-buffer "foo"))) - @result{} #<marker at 1 in foo> -@end group -@group -(read m) - @result{} This -@end group -@group -m - @result{} #<marker at 5 in foo> ;; @r{Before the first space.} -@end group -@end example - - Here we read from the contents of a string: - -@example -@group -(read "(When in) the course") - @result{} (When in) -@end group -@end example - - The following example reads from the minibuffer. The -prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt -used when you read from the stream @code{t}.) The user's input is shown -following the prompt. - -@example -@group -(read t) - @result{} 23 ----------- Buffer: Minibuffer ---------- -Lisp expression: @kbd{23 @key{RET}} ----------- Buffer: Minibuffer ---------- -@end group -@end example - - Finally, here is an example of a stream that is a function, named -@code{useless-stream}. Before we use the stream, we initialize the -variable @code{useless-list} to a list of characters. Then each call to -the function @code{useless-stream} obtains the next character in the list -or unreads a character by adding it to the front of the list. - -@example -@group -(setq useless-list (append "XY()" nil)) - @result{} (88 89 40 41) -@end group - -@group -(defun useless-stream (&optional unread) - (if unread - (setq useless-list (cons unread useless-list)) - (prog1 (car useless-list) - (setq useless-list (cdr useless-list))))) - @result{} useless-stream -@end group -@end example - -@noindent -Now we read using the stream thus constructed: - -@example -@group -(read 'useless-stream) - @result{} XY -@end group - -@group -useless-list - @result{} (40 41) -@end group -@end example - -@noindent -Note that the open and close parentheses remains in the list. The Lisp -reader encountered the open parenthesis, decided that it ended the -input, and unread it. Another attempt to read from the stream at this -point would read @samp{()} and return @code{nil}. - -@defun get-file-char -This function is used internally as an input stream to read from the -input file opened by the function @code{load}. Don't use this function -yourself. -@end defun - -@node Input Functions -@section Input Functions - - This section describes the Lisp functions and variables that pertain -to reading. - - In the functions below, @var{stream} stands for an input stream (see -the previous section). If @var{stream} is @code{nil} or omitted, it -defaults to the value of @code{standard-input}. - -@kindex end-of-file - An @code{end-of-file} error is signaled if reading encounters an -unterminated list, vector, or string. - -@defun read &optional stream -This function reads one textual Lisp expression from @var{stream}, -returning it as a Lisp object. This is the basic Lisp input function. -@end defun - -@defun read-from-string string &optional start end -@cindex string to object -This function reads the first textual Lisp expression from the text in -@var{string}. It returns a cons cell whose @sc{car} is that expression, -and whose @sc{cdr} is an integer giving the position of the next -remaining character in the string (i.e., the first one not read). - -If @var{start} is supplied, then reading begins at index @var{start} in -the string (where the first character is at index 0). If @var{end} is -also supplied, then reading stops just before that index, as if the rest -of the string were not there. - -For example: - -@example -@group -(read-from-string "(setq x 55) (setq y 5)") - @result{} ((setq x 55) . 11) -@end group -@group -(read-from-string "\"A short string\"") - @result{} ("A short string" . 16) -@end group - -@group -;; @r{Read starting at the first character.} -(read-from-string "(list 112)" 0) - @result{} ((list 112) . 10) -@end group -@group -;; @r{Read starting at the second character.} -(read-from-string "(list 112)" 1) - @result{} (list . 5) -@end group -@group -;; @r{Read starting at the seventh character,} -;; @r{and stopping at the ninth.} -(read-from-string "(list 112)" 6 8) - @result{} (11 . 8) -@end group -@end example -@end defun - -@defvar standard-input -This variable holds the default input stream---the stream that -@code{read} uses when the @var{stream} argument is @code{nil}. -@end defvar - -@node Output Streams -@section Output Streams -@cindex stream (for printing) -@cindex output stream - - An output stream specifies what to do with the characters produced -by printing. Most print functions accept an output stream as an -optional argument. Here are the possible types of output stream: - -@table @asis -@item @var{buffer} -@cindex buffer output stream -The output characters are inserted into @var{buffer} at point. -Point advances as characters are inserted. - -@item @var{marker} -@cindex marker output stream -The output characters are inserted into the buffer that @var{marker} -points into, at the marker position. The marker position advances as -characters are inserted. The value of point in the buffer has no effect -on printing when the stream is a marker. - -@item @var{function} -@cindex function output stream -The output characters are passed to @var{function}, which is responsible -for storing them away. It is called with a single character as -argument, as many times as there are characters to be output, and is -free to do anything at all with the characters it receives. - -@item @code{t} -@cindex @code{t} output stream -The output characters are displayed in the echo area. - -@item @code{nil} -@cindex @code{nil} output stream -@code{nil} specified as an output stream means to the value of -@code{standard-output} instead; that value is the @dfn{default output -stream}, and must be a non-@code{nil} output stream. - -@item @var{symbol} -A symbol as output stream is equivalent to the symbol's function -definition (if any). -@end table - - Many of the valid output streams are also valid as input streams. The -difference between input and output streams is therefore mostly one of -how you use a Lisp object, not a distinction of types of object. - - Here is an example of a buffer used as an output stream. Point is -initially located as shown immediately before the @samp{h} in -@samp{the}. At the end, point is located directly before that same -@samp{h}. - -@cindex print example -@example -@group -(setq m (set-marker (make-marker) 10 (get-buffer "foo"))) - @result{} #<marker at 10 in foo> -@end group - -@group ----------- Buffer: foo ---------- -This is t@point{}he contents of foo. ----------- Buffer: foo ---------- -@end group - -(print "This is the output" (get-buffer "foo")) - @result{} "This is the output" - -@group -m - @result{} #<marker at 32 in foo> -@end group -@group ----------- Buffer: foo ---------- -This is t -"This is the output" -@point{}he contents of foo. ----------- Buffer: foo ---------- -@end group -@end example - - Now we show a use of a marker as an output stream. Initially, the -marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in -the word @samp{the}. At the end, the marker has advanced over the -inserted text so that it remains positioned before the same @samp{h}. -Note that the location of point, shown in the usual fashion, has no -effect. - -@example -@group ----------- Buffer: foo ---------- -"This is the @point{}output" ----------- Buffer: foo ---------- -@end group - -@group -m - @result{} #<marker at 11 in foo> -@end group - -@group -(print "More output for foo." m) - @result{} "More output for foo." -@end group - -@group ----------- Buffer: foo ---------- -"This is t -"More output for foo." -he @point{}output" ----------- Buffer: foo ---------- -@end group - -@group -m - @result{} #<marker at 35 in foo> -@end group -@end example - - The following example shows output to the echo area: - -@example -@group -(print "Echo Area output" t) - @result{} "Echo Area output" ----------- Echo Area ---------- -"Echo Area output" ----------- Echo Area ---------- -@end group -@end example - - Finally, we show the use of a function as an output stream. The -function @code{eat-output} takes each character that it is given and -conses it onto the front of the list @code{last-output} (@pxref{Building -Lists}). At the end, the list contains all the characters output, but -in reverse order. - -@example -@group -(setq last-output nil) - @result{} nil -@end group - -@group -(defun eat-output (c) - (setq last-output (cons c last-output))) - @result{} eat-output -@end group - -@group -(print "This is the output" 'eat-output) - @result{} "This is the output" -@end group - -@group -last-output - @result{} (10 34 116 117 112 116 117 111 32 101 104 - 116 32 115 105 32 115 105 104 84 34 10) -@end group -@end example - -@noindent -Now we can put the output in the proper order by reversing the list: - -@example -@group -(concat (nreverse last-output)) - @result{} " -\"This is the output\" -" -@end group -@end example - -@noindent -Calling @code{concat} converts the list to a string so you can see its -contents more clearly. - -@node Output Functions -@section Output Functions - - This section describes the Lisp functions for printing Lisp objects. - -@cindex @samp{"} in printing -@cindex @samp{\} in printing -@cindex quoting characters in printing -@cindex escape characters in printing - Some of the Emacs printing functions add quoting characters to the -output when necessary so that it can be read properly. The quoting -characters used are @samp{"} and @samp{\}; they distinguish strings from -symbols, and prevent punctuation characters in strings and symbols from -being taken as delimiters when reading. @xref{Printed Representation}, -for full details. You specify quoting or no quoting by the choice of -printing function. - - If the text is to be read back into Lisp, then it is best to print -with quoting characters to avoid ambiguity. Likewise, if the purpose is -to describe a Lisp object clearly for a Lisp programmer. However, if -the purpose of the output is to look nice for humans, then it is better -to print without quoting. - - Printing a self-referent Lisp object requires an infinite amount of -text. In certain cases, trying to produce this text leads to a stack -overflow. Emacs detects such recursion and prints @samp{#@var{level}} -instead of recursively printing an object already being printed. For -example, here @samp{#0} indicates a recursive reference to the object at -level 0 of the current print operation: - -@example -(setq foo (list nil)) - @result{} (nil) -(setcar foo foo) - @result{} (#0) -@end example - - In the functions below, @var{stream} stands for an output stream. -(See the previous section for a description of output streams.) If -@var{stream} is @code{nil} or omitted, it defaults to the value of -@code{standard-output}. - -@defun print object &optional stream -@cindex Lisp printer -The @code{print} function is a convenient way of printing. It outputs -the printed representation of @var{object} to @var{stream}, printing in -addition one newline before @var{object} and another after it. Quoting -characters are used. @code{print} returns @var{object}. For example: - -@example -@group -(progn (print 'The\ cat\ in) - (print "the hat") - (print " came back")) - @print{} - @print{} The\ cat\ in - @print{} - @print{} "the hat" - @print{} - @print{} " came back" - @print{} - @result{} " came back" -@end group -@end example -@end defun - -@defun prin1 object &optional stream -This function outputs the printed representation of @var{object} to -@var{stream}. It does not print newlines to separate output as -@code{print} does, but it does use quoting characters just like -@code{print}. It returns @var{object}. - -@example -@group -(progn (prin1 'The\ cat\ in) - (prin1 "the hat") - (prin1 " came back")) - @print{} The\ cat\ in"the hat"" came back" - @result{} " came back" -@end group -@end example -@end defun - -@defun princ object &optional stream -This function outputs the printed representation of @var{object} to -@var{stream}. It returns @var{object}. - -This function is intended to produce output that is readable by people, -not by @code{read}, so it doesn't insert quoting characters and doesn't -put double-quotes around the contents of strings. It does not add any -spacing between calls. - -@example -@group -(progn - (princ 'The\ cat) - (princ " in the \"hat\"")) - @print{} The cat in the "hat" - @result{} " in the \"hat\"" -@end group -@end example -@end defun - -@defun terpri &optional stream -@cindex newline in print -This function outputs a newline to @var{stream}. The name stands -for ``terminate print''. -@end defun - -@defun write-char character &optional stream -This function outputs @var{character} to @var{stream}. It returns -@var{character}. -@end defun - -@defun prin1-to-string object &optional noescape -@cindex object to string -This function returns a string containing the text that @code{prin1} -would have printed for the same argument. - -@example -@group -(prin1-to-string 'foo) - @result{} "foo" -@end group -@group -(prin1-to-string (mark-marker)) - @result{} "#<marker at 2773 in strings.texi>" -@end group -@end example - -If @var{noescape} is non-@code{nil}, that inhibits use of quoting -characters in the output. (This argument is supported in Emacs versions -19 and later.) - -@example -@group -(prin1-to-string "foo") - @result{} "\"foo\"" -@end group -@group -(prin1-to-string "foo" t) - @result{} "foo" -@end group -@end example - -See @code{format}, in @ref{String Conversion}, for other ways to obtain -the printed representation of a Lisp object as a string. -@end defun - -@node Output Variables -@section Variables Affecting Output - -@defvar standard-output -The value of this variable is the default output stream---the stream -that print functions use when the @var{stream} argument is @code{nil}. -@end defvar - -@defvar print-escape-newlines -@cindex @samp{\n} in print -@cindex escape characters -If this variable is non-@code{nil}, then newline characters in strings -are printed as @samp{\n} and formfeeds are printed as @samp{\f}. -Normally these characters are printed as actual newlines and formfeeds. - -This variable affects the print functions @code{prin1} and @code{print}, -as well as everything that uses them. It does not affect @code{princ}. -Here is an example using @code{prin1}: - -@example -@group -(prin1 "a\nb") - @print{} "a - @print{} b" - @result{} "a -b" -@end group - -@group -(let ((print-escape-newlines t)) - (prin1 "a\nb")) - @print{} "a\nb" - @result{} "a -b" -@end group -@end example - -@noindent -In the second expression, the local binding of -@code{print-escape-newlines} is in effect during the call to -@code{prin1}, but not during the printing of the result. -@end defvar - -@defvar print-length -@cindex printing limits -The value of this variable is the maximum number of elements of a list, -vector or bitvector that will be printed. If an object being printed has -more than this many elements, it is abbreviated with an ellipsis. - -If the value is @code{nil} (the default), then there is no limit. - -@example -@group -(setq print-length 2) - @result{} 2 -@end group -@group -(print '(1 2 3 4 5)) - @print{} (1 2 ...) - @result{} (1 2 ...) -@end group -@end example -@end defvar - -@defvar print-level -The value of this variable is the maximum depth of nesting of -parentheses and brackets when printed. Any list or vector at a depth -exceeding this limit is abbreviated with an ellipsis. A value of -@code{nil} (which is the default) means no limit. - -This variable exists in version 19 and later versions. -@end defvar diff --git a/lispref/strings.texi b/lispref/strings.texi deleted file mode 100644 index d5b9b4c7193..00000000000 --- a/lispref/strings.texi +++ /dev/null @@ -1,828 +0,0 @@ -@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/strings -@node Strings and Characters, Lists, Numbers, Top -@comment node-name, next, previous, up -@chapter Strings and Characters -@cindex strings -@cindex character arrays -@cindex characters -@cindex bytes - - A string in Emacs Lisp is an array that contains an ordered sequence -of characters. Strings are used as names of symbols, buffers, and -files, to send messages to users, to hold text being copied between -buffers, and for many other purposes. Because strings are so important, -Emacs Lisp has many functions expressly for manipulating them. Emacs -Lisp programs use strings more often than individual characters. - - @xref{Strings of Events}, for special considerations for strings of -keyboard character events. - -@menu -* Basics: String Basics. Basic properties of strings and characters. -* Predicates for Strings:: Testing whether an object is a string or char. -* Creating Strings:: Functions to allocate new strings. -* Text Comparison:: Comparing characters or strings. -* String Conversion:: Converting characters or strings and vice versa. -* Formatting Strings:: @code{format}: Emacs's analog of @code{printf}. -* Character Case:: Case conversion functions. -* Case Table:: Customizing case conversion. -@end menu - -@node String Basics -@section String and Character Basics - - Strings in Emacs Lisp are arrays that contain an ordered sequence of -characters. Characters are represented in Emacs Lisp as integers; -whether an integer was intended as a character or not is determined only -by how it is used. Thus, strings really contain integers. - - The length of a string (like any array) is fixed and independent of -the string contents, and cannot be altered. Strings in Lisp are -@emph{not} terminated by a distinguished character code. (By contrast, -strings in C are terminated by a character with @sc{ASCII} code 0.) -This means that any character, including the null character (@sc{ASCII} -code 0), is a valid element of a string.@refill - - Since strings are considered arrays, you can operate on them with the -general array functions. (@xref{Sequences Arrays Vectors}.) For -example, you can access or change individual characters in a string -using the functions @code{aref} and @code{aset} (@pxref{Array -Functions}). - - Each character in a string is stored in a single byte. Therefore, -numbers not in the range 0 to 255 are truncated when stored into a -string. This means that a string takes up much less memory than a -vector of the same length. - - Sometimes key sequences are represented as strings. When a string is -a key sequence, string elements in the range 128 to 255 represent meta -characters (which are extremely large integers) rather than keyboard -events in the range 128 to 255. - - Strings cannot hold characters that have the hyper, super or alt -modifiers; they can hold @sc{ASCII} control characters, but no other -control characters. They do not distinguish case in @sc{ASCII} control -characters. @xref{Character Type}, for more information about -representation of meta and other modifiers for keyboard input -characters. - - Strings are useful for holding regular expressions. You can also -match regular expressions against strings (@pxref{Regexp Search}). The -functions @code{match-string} (@pxref{Simple Match Data}) and -@code{replace-match} (@pxref{Replacing Match}) are useful for -decomposing and modifying strings based on regular expression matching. - - Like a buffer, a string can contain text properties for the characters -in it, as well as the characters themselves. @xref{Text Properties}. -All the Lisp primitives that copy text from strings to buffers or other -strings also copy the properties of the characters being copied. - - @xref{Text}, for information about functions that display strings or -copy them into buffers. @xref{Character Type}, and @ref{String Type}, -for information about the syntax of characters and strings. - -@node Predicates for Strings -@section The Predicates for Strings - -For more information about general sequence and array predicates, -see @ref{Sequences Arrays Vectors}, and @ref{Arrays}. - -@defun stringp object - This function returns @code{t} if @var{object} is a string, @code{nil} -otherwise. -@end defun - -@defun char-or-string-p object - This function returns @code{t} if @var{object} is a string or a -character (i.e., an integer), @code{nil} otherwise. -@end defun - -@node Creating Strings -@section Creating Strings - - The following functions create strings, either from scratch, or by -putting strings together, or by taking them apart. - -@defun make-string count character - This function returns a string made up of @var{count} repetitions of -@var{character}. If @var{count} is negative, an error is signaled. - -@example -(make-string 5 ?x) - @result{} "xxxxx" -(make-string 0 ?x) - @result{} "" -@end example - - Other functions to compare with this one include @code{char-to-string} -(@pxref{String Conversion}), @code{make-vector} (@pxref{Vectors}), and -@code{make-list} (@pxref{Building Lists}). -@end defun - -@defun substring string start &optional end -This function returns a new string which consists of those characters -from @var{string} in the range from (and including) the character at the -index @var{start} up to (but excluding) the character at the index -@var{end}. The first character is at index zero. - -@example -@group -(substring "abcdefg" 0 3) - @result{} "abc" -@end group -@end example - -@noindent -Here the index for @samp{a} is 0, the index for @samp{b} is 1, and the -index for @samp{c} is 2. Thus, three letters, @samp{abc}, are copied -from the string @code{"abcdefg"}. The index 3 marks the character -position up to which the substring is copied. The character whose index -is 3 is actually the fourth character in the string. - -A negative number counts from the end of the string, so that @minus{}1 -signifies the index of the last character of the string. For example: - -@example -@group -(substring "abcdefg" -3 -1) - @result{} "ef" -@end group -@end example - -@noindent -In this example, the index for @samp{e} is @minus{}3, the index for -@samp{f} is @minus{}2, and the index for @samp{g} is @minus{}1. -Therefore, @samp{e} and @samp{f} are included, and @samp{g} is excluded. - -When @code{nil} is used as an index, it stands for the length of the -string. Thus, - -@example -@group -(substring "abcdefg" -3 nil) - @result{} "efg" -@end group -@end example - -Omitting the argument @var{end} is equivalent to specifying @code{nil}. -It follows that @code{(substring @var{string} 0)} returns a copy of all -of @var{string}. - -@example -@group -(substring "abcdefg" 0) - @result{} "abcdefg" -@end group -@end example - -@noindent -But we recommend @code{copy-sequence} for this purpose (@pxref{Sequence -Functions}). - -If the characters copied from @var{string} have text properties, the -properties are copied into the new string also. @xref{Text Properties}. - -A @code{wrong-type-argument} error is signaled if either @var{start} or -@var{end} is not an integer or @code{nil}. An @code{args-out-of-range} -error is signaled if @var{start} indicates a character following -@var{end}, or if either integer is out of range for @var{string}. - -Contrast this function with @code{buffer-substring} (@pxref{Buffer -Contents}), which returns a string containing a portion of the text in -the current buffer. The beginning of a string is at index 0, but the -beginning of a buffer is at index 1. -@end defun - -@defun concat &rest sequences -@cindex copying strings -@cindex concatenating strings -This function returns a new string consisting of the characters in the -arguments passed to it (along with their text properties, if any). The -arguments may be strings, lists of numbers, or vectors of numbers; they -are not themselves changed. If @code{concat} receives no arguments, it -returns an empty string. - -@example -(concat "abc" "-def") - @result{} "abc-def" -(concat "abc" (list 120 (+ 256 121)) [122]) - @result{} "abcxyz" -;; @r{@code{nil} is an empty sequence.} -(concat "abc" nil "-def") - @result{} "abc-def" -(concat "The " "quick brown " "fox.") - @result{} "The quick brown fox." -(concat) - @result{} "" -@end example - -@noindent -The second example above shows how characters stored in strings are -taken modulo 256. In other words, each character in the string is -stored in one byte. - -The @code{concat} function always constructs a new string that is -not @code{eq} to any existing string. - -When an argument is an integer (not a sequence of integers), it is -converted to a string of digits making up the decimal printed -representation of the integer. @strong{Don't use this feature; we plan -to eliminate it. If you already use this feature, change your programs -now!} The proper way to convert an integer to a decimal number in this -way is with @code{format} (@pxref{Formatting Strings}) or -@code{number-to-string} (@pxref{String Conversion}). - -@example -@group -(concat 137) - @result{} "137" -(concat 54 321) - @result{} "54321" -@end group -@end example - -For information about other concatenation functions, see the -description of @code{mapconcat} in @ref{Mapping Functions}, -@code{vconcat} in @ref{Vectors}, and @code{append} in @ref{Building -Lists}. -@end defun - -@need 2000 -@node Text Comparison -@section Comparison of Characters and Strings -@cindex string equality - -@defun char-equal character1 character2 -This function returns @code{t} if the arguments represent the same -character, @code{nil} otherwise. This function ignores differences -in case if @code{case-fold-search} is non-@code{nil}. - -@example -(char-equal ?x ?x) - @result{} t -(char-to-string (+ 256 ?x)) - @result{} "x" -(char-equal ?x (+ 256 ?x)) - @result{} t -@end example -@end defun - -@defun string= string1 string2 -This function returns @code{t} if the characters of the two strings -match exactly; case is significant. - -@example -(string= "abc" "abc") - @result{} t -(string= "abc" "ABC") - @result{} nil -(string= "ab" "ABC") - @result{} nil -@end example - -The function @code{string=} ignores the text properties of the -two strings. To compare strings in a way that compares their text -properties also, use @code{equal} (@pxref{Equality Predicates}). -@end defun - -@defun string-equal string1 string2 -@code{string-equal} is another name for @code{string=}. -@end defun - -@cindex lexical comparison -@defun string< string1 string2 -@c (findex string< causes problems for permuted index!!) -This function compares two strings a character at a time. First it -scans both the strings at once to find the first pair of corresponding -characters that do not match. If the lesser character of those two is -the character from @var{string1}, then @var{string1} is less, and this -function returns @code{t}. If the lesser character is the one from -@var{string2}, then @var{string1} is greater, and this function returns -@code{nil}. If the two strings match entirely, the value is @code{nil}. - -Pairs of characters are compared by their @sc{ASCII} codes. Keep in -mind that lower case letters have higher numeric values in the -@sc{ASCII} character set than their upper case counterparts; numbers and -many punctuation characters have a lower numeric value than upper case -letters. - -@example -@group -(string< "abc" "abd") - @result{} t -(string< "abd" "abc") - @result{} nil -(string< "123" "abc") - @result{} t -@end group -@end example - -When the strings have different lengths, and they match up to the -length of @var{string1}, then the result is @code{t}. If they match up -to the length of @var{string2}, the result is @code{nil}. A string of -no characters is less than any other string. - -@example -@group -(string< "" "abc") - @result{} t -(string< "ab" "abc") - @result{} t -(string< "abc" "") - @result{} nil -(string< "abc" "ab") - @result{} nil -(string< "" "") - @result{} nil -@end group -@end example -@end defun - -@defun string-lessp string1 string2 -@code{string-lessp} is another name for @code{string<}. -@end defun - - See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for -a way to compare text in buffers. The function @code{string-match}, -which matches a regular expression against a string, can be used -for a kind of string comparison; see @ref{Regexp Search}. - -@node String Conversion -@comment node-name, next, previous, up -@section Conversion of Characters and Strings -@cindex conversion of strings - - This section describes functions for conversions between characters, -strings and integers. @code{format} and @code{prin1-to-string} -(@pxref{Output Functions}) can also convert Lisp objects into strings. -@code{read-from-string} (@pxref{Input Functions}) can ``convert'' a -string representation of a Lisp object into an object. - - @xref{Documentation}, for functions that produce textual descriptions -of text characters and general input events -(@code{single-key-description} and @code{text-char-description}). These -functions are used primarily for making help messages. - -@defun char-to-string character -@cindex character to string - This function returns a new string with a length of one character. -The value of @var{character}, modulo 256, is used to initialize the -element of the string. - -This function is similar to @code{make-string} with an integer argument -of 1. (@xref{Creating Strings}.) This conversion can also be done with -@code{format} using the @samp{%c} format specification. -(@xref{Formatting Strings}.) - -@example -(char-to-string ?x) - @result{} "x" -(char-to-string (+ 256 ?x)) - @result{} "x" -(make-string 1 ?x) - @result{} "x" -@end example -@end defun - -@defun string-to-char string -@cindex string to character - This function returns the first character in @var{string}. If the -string is empty, the function returns 0. The value is also 0 when the -first character of @var{string} is the null character, @sc{ASCII} code -0. - -@example -(string-to-char "ABC") - @result{} 65 -(string-to-char "xyz") - @result{} 120 -(string-to-char "") - @result{} 0 -(string-to-char "\000") - @result{} 0 -@end example - -This function may be eliminated in the future if it does not seem useful -enough to retain. -@end defun - -@defun number-to-string number -@cindex integer to string -@cindex integer to decimal -This function returns a string consisting of the printed -representation of @var{number}, which may be an integer or a floating -point number. The value starts with a sign if the argument is -negative. - -@example -(number-to-string 256) - @result{} "256" -(number-to-string -23) - @result{} "-23" -(number-to-string -23.5) - @result{} "-23.5" -@end example - -@cindex int-to-string -@code{int-to-string} is a semi-obsolete alias for this function. - -See also the function @code{format} in @ref{Formatting Strings}. -@end defun - -@defun string-to-number string -@cindex string to number -This function returns the numeric value of the characters in -@var{string}, read in base ten. It skips spaces and tabs at the -beginning of @var{string}, then reads as much of @var{string} as it can -interpret as a number. (On some systems it ignores other whitespace at -the beginning, not just spaces and tabs.) If the first character after -the ignored whitespace is not a digit or a minus sign, this function -returns 0. - -@example -(string-to-number "256") - @result{} 256 -(string-to-number "25 is a perfect square.") - @result{} 25 -(string-to-number "X256") - @result{} 0 -(string-to-number "-4.5") - @result{} -4.5 -@end example - -@findex string-to-int -@code{string-to-int} is an obsolete alias for this function. -@end defun - -@node Formatting Strings -@comment node-name, next, previous, up -@section Formatting Strings -@cindex formatting strings -@cindex strings, formatting them - - @dfn{Formatting} means constructing a string by substitution of -computed values at various places in a constant string. This string -controls how the other values are printed as well as where they appear; -it is called a @dfn{format string}. - - Formatting is often useful for computing messages to be displayed. In -fact, the functions @code{message} and @code{error} provide the same -formatting feature described here; they differ from @code{format} only -in how they use the result of formatting. - -@defun format string &rest objects - This function returns a new string that is made by copying -@var{string} and then replacing any format specification -in the copy with encodings of the corresponding @var{objects}. The -arguments @var{objects} are the computed values to be formatted. -@end defun - -@cindex @samp{%} in format -@cindex format specification - A format specification is a sequence of characters beginning with a -@samp{%}. Thus, if there is a @samp{%d} in @var{string}, the -@code{format} function replaces it with the printed representation of -one of the values to be formatted (one of the arguments @var{objects}). -For example: - -@example -@group -(format "The value of fill-column is %d." fill-column) - @result{} "The value of fill-column is 72." -@end group -@end example - - If @var{string} contains more than one format specification, the -format specifications correspond with successive values from -@var{objects}. Thus, the first format specification in @var{string} -uses the first such value, the second format specification uses the -second such value, and so on. Any extra format specifications (those -for which there are no corresponding values) cause unpredictable -behavior. Any extra values to be formatted are ignored. - - Certain format specifications require values of particular types. -However, no error is signaled if the value actually supplied fails to -have the expected type. Instead, the output is likely to be -meaningless. - - Here is a table of valid format specifications: - -@table @samp -@item %s -Replace the specification with the printed representation of the object, -made without quoting. Thus, strings are represented by their contents -alone, with no @samp{"} characters, and symbols appear without @samp{\} -characters. - -If there is no corresponding object, the empty string is used. - -@item %S -Replace the specification with the printed representation of the object, -made with quoting. Thus, strings are enclosed in @samp{"} characters, -and @samp{\} characters appear where necessary before special characters. - -If there is no corresponding object, the empty string is used. - -@item %o -@cindex integer to octal -Replace the specification with the base-eight representation of an -integer. - -@item %d -Replace the specification with the base-ten representation of an -integer. - -@item %x -@cindex integer to hexadecimal -Replace the specification with the base-sixteen representation of an -integer. - -@item %c -Replace the specification with the character which is the value given. - -@item %e -Replace the specification with the exponential notation for a floating -point number. - -@item %f -Replace the specification with the decimal-point notation for a floating -point number. - -@item %g -Replace the specification with notation for a floating point number, -using either exponential notation or decimal-point notation whichever -is shorter. - -@item %% -A single @samp{%} is placed in the string. This format specification is -unusual in that it does not use a value. For example, @code{(format "%% -%d" 30)} returns @code{"% 30"}. -@end table - - Any other format character results in an @samp{Invalid format -operation} error. - - Here are several examples: - -@example -@group -(format "The name of this buffer is %s." (buffer-name)) - @result{} "The name of this buffer is strings.texi." - -(format "The buffer object prints as %s." (current-buffer)) - @result{} "The buffer object prints as strings.texi." - -(format "The octal value of %d is %o, - and the hex value is %x." 18 18 18) - @result{} "The octal value of 18 is 22, - and the hex value is 12." -@end group -@end example - -@cindex numeric prefix -@cindex field width -@cindex padding - All the specification characters allow an optional numeric prefix -between the @samp{%} and the character. The optional numeric prefix -defines the minimum width for the object. If the printed representation -of the object contains fewer characters than this, then it is padded. -The padding is on the left if the prefix is positive (or starts with -zero) and on the right if the prefix is negative. The padding character -is normally a space, but if the numeric prefix starts with a zero, zeros -are used for padding. - -@example -(format "%06d is padded on the left with zeros" 123) - @result{} "000123 is padded on the left with zeros" - -(format "%-6d is padded on the right" 123) - @result{} "123 is padded on the right" -@end example - - @code{format} never truncates an object's printed representation, no -matter what width you specify. Thus, you can use a numeric prefix to -specify a minimum spacing between columns with no risk of losing -information. - - In the following three examples, @samp{%7s} specifies a minimum width -of 7. In the first case, the string inserted in place of @samp{%7s} has -only 3 letters, so 4 blank spaces are inserted for padding. In the -second case, the string @code{"specification"} is 13 letters wide but is -not truncated. In the third case, the padding is on the right. - -@smallexample -@group -(format "The word `%7s' actually has %d letters in it." - "foo" (length "foo")) - @result{} "The word ` foo' actually has 3 letters in it." -@end group - -@group -(format "The word `%7s' actually has %d letters in it." - "specification" (length "specification")) - @result{} "The word `specification' actually has 13 letters in it." -@end group - -@group -(format "The word `%-7s' actually has %d letters in it." - "foo" (length "foo")) - @result{} "The word `foo ' actually has 3 letters in it." -@end group -@end smallexample - -@node Character Case -@comment node-name, next, previous, up -@section Character Case -@cindex upper case -@cindex lower case -@cindex character case - - The character case functions change the case of single characters or -of the contents of strings. The functions convert only alphabetic -characters (the letters @samp{A} through @samp{Z} and @samp{a} through -@samp{z}); other characters are not altered. The functions do not -modify the strings that are passed to them as arguments. - - The examples below use the characters @samp{X} and @samp{x} which have -@sc{ASCII} codes 88 and 120 respectively. - -@defun downcase string-or-char -This function converts a character or a string to lower case. - -When the argument to @code{downcase} is a string, the function creates -and returns a new string in which each letter in the argument that is -upper case is converted to lower case. When the argument to -@code{downcase} is a character, @code{downcase} returns the -corresponding lower case character. This value is an integer. If the -original character is lower case, or is not a letter, then the value -equals the original character. - -@example -(downcase "The cat in the hat") - @result{} "the cat in the hat" - -(downcase ?X) - @result{} 120 -@end example -@end defun - -@defun upcase string-or-char -This function converts a character or a string to upper case. - -When the argument to @code{upcase} is a string, the function creates -and returns a new string in which each letter in the argument that is -lower case is converted to upper case. - -When the argument to @code{upcase} is a character, @code{upcase} -returns the corresponding upper case character. This value is an integer. -If the original character is upper case, or is not a letter, then the -value equals the original character. - -@example -(upcase "The cat in the hat") - @result{} "THE CAT IN THE HAT" - -(upcase ?x) - @result{} 88 -@end example -@end defun - -@defun capitalize string-or-char -@cindex capitalization -This function capitalizes strings or characters. If -@var{string-or-char} is a string, the function creates and returns a new -string, whose contents are a copy of @var{string-or-char} in which each -word has been capitalized. This means that the first character of each -word is converted to upper case, and the rest are converted to lower -case. - -The definition of a word is any sequence of consecutive characters that -are assigned to the word constituent syntax class in the current syntax -table (@xref{Syntax Class Table}). - -When the argument to @code{capitalize} is a character, @code{capitalize} -has the same result as @code{upcase}. - -@example -(capitalize "The cat in the hat") - @result{} "The Cat In The Hat" - -(capitalize "THE 77TH-HATTED CAT") - @result{} "The 77th-Hatted Cat" - -@group -(capitalize ?x) - @result{} 88 -@end group -@end example -@end defun - -@node Case Table -@section The Case Table - - You can customize case conversion by installing a special @dfn{case -table}. A case table specifies the mapping between upper case and lower -case letters. It affects both the string and character case conversion -functions (see the previous section) and those that apply to text in the -buffer (@pxref{Case Changes}). You need a case table if you are using a -language which has letters other than the standard @sc{ASCII} letters. - - A case table is a list of this form: - -@example -(@var{downcase} @var{upcase} @var{canonicalize} @var{equivalences}) -@end example - -@noindent -where each element is either @code{nil} or a string of length 256. The -element @var{downcase} says how to map each character to its lower-case -equivalent. The element @var{upcase} maps each character to its -upper-case equivalent. If lower and upper case characters are in -one-to-one correspondence, use @code{nil} for @var{upcase}; then Emacs -deduces the upcase table from @var{downcase}. - - For some languages, upper and lower case letters are not in one-to-one -correspondence. There may be two different lower case letters with the -same upper case equivalent. In these cases, you need to specify the -maps for both directions. - - The element @var{canonicalize} maps each character to a canonical -equivalent; any two characters that are related by case-conversion have -the same canonical equivalent character. - - The element @var{equivalences} is a map that cyclicly permutes each -equivalence class (of characters with the same canonical equivalent). -(For ordinary @sc{ASCII}, this would map @samp{a} into @samp{A} and -@samp{A} into @samp{a}, and likewise for each set of equivalent -characters.) - - When you construct a case table, you can provide @code{nil} for -@var{canonicalize}; then Emacs fills in this string from @var{upcase} -and @var{downcase}. You can also provide @code{nil} for -@var{equivalences}; then Emacs fills in this string from -@var{canonicalize}. In a case table that is actually in use, those -components are non-@code{nil}. Do not try to specify @var{equivalences} -without also specifying @var{canonicalize}. - - Each buffer has a case table. Emacs also has a @dfn{standard case -table} which is copied into each buffer when you create the buffer. -Changing the standard case table doesn't affect any existing buffers. - - Here are the functions for working with case tables: - -@defun case-table-p object -This predicate returns non-@code{nil} if @var{object} is a valid case -table. -@end defun - -@defun set-standard-case-table table -This function makes @var{table} the standard case table, so that it will -apply to any buffers created subsequently. -@end defun - -@defun standard-case-table -This returns the standard case table. -@end defun - -@defun current-case-table -This function returns the current buffer's case table. -@end defun - -@defun set-case-table table -This sets the current buffer's case table to @var{table}. -@end defun - - The following three functions are convenient subroutines for packages -that define non-@sc{ASCII} character sets. They modify a string -@var{downcase-table} provided as an argument; this should be a string to -be used as the @var{downcase} part of a case table. They also modify -the standard syntax table. @xref{Syntax Tables}. - -@defun set-case-syntax-pair uc lc downcase-table -This function specifies a pair of corresponding letters, one upper case -and one lower case. -@end defun - -@defun set-case-syntax-delims l r downcase-table -This function makes characters @var{l} and @var{r} a matching pair of -case-invariant delimiters. -@end defun - -@defun set-case-syntax char syntax downcase-table -This function makes @var{char} case-invariant, with syntax -@var{syntax}. -@end defun - -@deffn Command describe-buffer-case-table -This command displays a description of the contents of the current -buffer's case table. -@end deffn - -@cindex ISO Latin 1 -@pindex iso-syntax -You can load the library @file{iso-syntax} to set up the standard syntax -table and define a case table for the 8-bit ISO Latin 1 character set. diff --git a/lispref/symbols.texi b/lispref/symbols.texi deleted file mode 100644 index 9c20df9c4ae..00000000000 --- a/lispref/symbols.texi +++ /dev/null @@ -1,528 +0,0 @@ -@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/symbols -@node Symbols, Evaluation, Sequences Arrays Vectors, Top -@chapter Symbols -@cindex symbol - - A @dfn{symbol} is an object with a unique name. This chapter -describes symbols, their components, their property lists, and how they -are created and interned. Separate chapters describe the use of symbols -as variables and as function names; see @ref{Variables}, and -@ref{Functions}. For the precise read syntax for symbols, see -@ref{Symbol Type}. - - You can test whether an arbitrary Lisp object is a symbol -with @code{symbolp}: - -@defun symbolp object -This function returns @code{t} if @var{object} is a symbol, @code{nil} -otherwise. -@end defun - -@menu -* Symbol Components:: Symbols have names, values, function definitions - and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Property Lists:: Each symbol has a property list - for recording miscellaneous information. -@end menu - -@node Symbol Components, Definitions, Symbols, Symbols -@section Symbol Components -@cindex symbol components - - Each symbol has four components (or ``cells''), each of which -references another object: - -@table @asis -@item Print name -@cindex print name cell -The @dfn{print name cell} holds a string that names the symbol for -reading and printing. See @code{symbol-name} in @ref{Creating Symbols}. - -@item Value -@cindex value cell -The @dfn{value cell} holds the current value of the symbol as a -variable. When a symbol is used as a form, the value of the form is the -contents of the symbol's value cell. See @code{symbol-value} in -@ref{Accessing Variables}. - -@item Function -@cindex function cell -The @dfn{function cell} holds the function definition of the symbol. -When a symbol is used as a function, its function definition is used in -its place. This cell is also used to make a symbol stand for a keymap -or a keyboard macro, for editor command execution. Because each symbol -has separate value and function cells, variables and function names do -not conflict. See @code{symbol-function} in @ref{Function Cells}. - -@item Property list -@cindex property list cell -The @dfn{property list cell} holds the property list of the symbol. See -@code{symbol-plist} in @ref{Property Lists}. -@end table - - The print name cell always holds a string, and cannot be changed. The -other three cells can be set individually to any specified Lisp object. - - The print name cell holds the string that is the name of the symbol. -Since symbols are represented textually by their names, it is important -not to have two symbols with the same name. The Lisp reader ensures -this: every time it reads a symbol, it looks for an existing symbol with -the specified name before it creates a new one. (In GNU Emacs Lisp, -this lookup uses a hashing algorithm and an obarray; see @ref{Creating -Symbols}.) - - In normal usage, the function cell usually contains a function or -macro, as that is what the Lisp interpreter expects to see there -(@pxref{Evaluation}). Keyboard macros (@pxref{Keyboard Macros}), -keymaps (@pxref{Keymaps}) and autoload objects (@pxref{Autoloading}) are -also sometimes stored in the function cell of symbols. We often refer -to ``the function @code{foo}'' when we really mean the function stored -in the function cell of the symbol @code{foo}. We make the distinction -only when necessary. - - The property list cell normally should hold a correctly formatted -property list (@pxref{Property Lists}), as a number of functions expect -to see a property list there. - - The function cell or the value cell may be @dfn{void}, which means -that the cell does not reference any object. (This is not the same -thing as holding the symbol @code{void}, nor the same as holding the -symbol @code{nil}.) Examining a cell that is void results in an error, -such as @samp{Symbol's value as variable is void}. - - The four functions @code{symbol-name}, @code{symbol-value}, -@code{symbol-plist}, and @code{symbol-function} return the contents of -the four cells of a symbol. Here as an example we show the contents of -the four cells of the symbol @code{buffer-file-name}: - -@example -(symbol-name 'buffer-file-name) - @result{} "buffer-file-name" -(symbol-value 'buffer-file-name) - @result{} "/gnu/elisp/symbols.texi" -(symbol-plist 'buffer-file-name) - @result{} (variable-documentation 29529) -(symbol-function 'buffer-file-name) - @result{} #<subr buffer-file-name> -@end example - -@noindent -Because this symbol is the variable which holds the name of the file -being visited in the current buffer, the value cell contents we see are -the name of the source file of this chapter of the Emacs Lisp Manual. -The property list cell contains the list @code{(variable-documentation -29529)} which tells the documentation functions where to find the -documentation string for the variable @code{buffer-file-name} in the -@file{DOC} file. (29529 is the offset from the beginning of the -@file{DOC} file to where that documentation string begins.) The -function cell contains the function for returning the name of the file. -@code{buffer-file-name} names a primitive function, which has no read -syntax and prints in hash notation (@pxref{Primitive Function Type}). A -symbol naming a function written in Lisp would have a lambda expression -(or a byte-code object) in this cell. - -@node Definitions, Creating Symbols, Symbol Components, Symbols -@section Defining Symbols -@cindex definition of a symbol - - A @dfn{definition} in Lisp is a special form that announces your -intention to use a certain symbol in a particular way. In Emacs Lisp, -you can define a symbol as a variable, or define it as a function (or -macro), or both independently. - - A definition construct typically specifies a value or meaning for the -symbol for one kind of use, plus documentation for its meaning when used -in this way. Thus, when you define a symbol as a variable, you can -supply an initial value for the variable, plus documentation for the -variable. - - @code{defvar} and @code{defconst} are special forms that define a -symbol as a global variable. They are documented in detail in -@ref{Defining Variables}. - - @code{defun} defines a symbol as a function, creating a lambda -expression and storing it in the function cell of the symbol. This -lambda expression thus becomes the function definition of the symbol. -(The term ``function definition'', meaning the contents of the function -cell, is derived from the idea that @code{defun} gives the symbol its -definition as a function.) @code{defsubst} and @code{defalias} are two -other ways of defining a function. @xref{Functions}. - - @code{defmacro} defines a symbol as a macro. It creates a macro -object and stores it in the function cell of the symbol. Note that a -given symbol can be a macro or a function, but not both at once, because -both macro and function definitions are kept in the function cell, and -that cell can hold only one Lisp object at any given time. -@xref{Macros}. - - In Emacs Lisp, a definition is not required in order to use a symbol -as a variable or function. Thus, you can make a symbol a global -variable with @code{setq}, whether you define it first or not. The real -purpose of definitions is to guide programmers and programming tools. -They inform programmers who read the code that certain symbols are -@emph{intended} to be used as variables, or as functions. In addition, -utilities such as @file{etags} and @file{make-docfile} recognize -definitions, and add appropriate information to tag tables and the -@file{emacs/etc/DOC-@var{version}} file. @xref{Accessing Documentation}. - -@node Creating Symbols, Property Lists, Definitions, Symbols -@section Creating and Interning Symbols -@cindex reading symbols - - To understand how symbols are created in GNU Emacs Lisp, you must know -how Lisp reads them. Lisp must ensure that it finds the same symbol -every time it reads the same set of characters. Failure to do so would -cause complete confusion. - -@cindex symbol name hashing -@cindex hashing -@cindex obarray -@cindex bucket (in obarray) - When the Lisp reader encounters a symbol, it reads all the characters -of the name. Then it ``hashes'' those characters to find an index in a -table called an @dfn{obarray}. Hashing is an efficient method of -looking something up. For example, instead of searching a telephone -book cover to cover when looking up Jan Jones, you start with the J's -and go from there. That is a simple version of hashing. Each element -of the obarray is a @dfn{bucket} which holds all the symbols with a -given hash code; to look for a given name, it is sufficient to look -through all the symbols in the bucket for that name's hash code. - -@cindex interning - If a symbol with the desired name is found, the reader uses that -symbol. If the obarray does not contain a symbol with that name, the -reader makes a new symbol and adds it to the obarray. Finding or adding -a symbol with a certain name is called @dfn{interning} it, and the -symbol is then called an @dfn{interned symbol}. - - Interning ensures that each obarray has just one symbol with any -particular name. Other like-named symbols may exist, but not in the -same obarray. Thus, the reader gets the same symbols for the same -names, as long as you keep reading with the same obarray. - -@cindex symbol equality -@cindex uninterned symbol - No obarray contains all symbols; in fact, some symbols are not in any -obarray. They are called @dfn{uninterned symbols}. An uninterned -symbol has the same four cells as other symbols; however, the only way -to gain access to it is by finding it in some other object or as the -value of a variable. - - In Emacs Lisp, an obarray is actually a vector. Each element of the -vector is a bucket; its value is either an interned symbol whose name -hashes to that bucket, or 0 if the bucket is empty. Each interned -symbol has an internal link (invisible to the user) to the next symbol -in the bucket. Because these links are invisible, there is no way to -find all the symbols in an obarray except using @code{mapatoms} (below). -The order of symbols in a bucket is not significant. - - In an empty obarray, every element is 0, and you can create an obarray -with @code{(make-vector @var{length} 0)}. @strong{This is the only -valid way to create an obarray.} Prime numbers as lengths tend -to result in good hashing; lengths one less than a power of two are also -good. - - @strong{Do not try to put symbols in an obarray yourself.} This does -not work---only @code{intern} can enter a symbol in an obarray properly. -@strong{Do not try to intern one symbol in two obarrays.} This would -garble both obarrays, because a symbol has just one slot to hold the -following symbol in the obarray bucket. The results would be -unpredictable. - - It is possible for two different symbols to have the same name in -different obarrays; these symbols are not @code{eq} or @code{equal}. -However, this normally happens only as part of the abbrev mechanism -(@pxref{Abbrevs}). - -@cindex CL note---symbol in obarrays -@quotation -@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in -several obarrays. -@end quotation - - Most of the functions below take a name and sometimes an obarray as -arguments. A @code{wrong-type-argument} error is signaled if the name -is not a string, or if the obarray is not a vector. - -@defun symbol-name symbol -This function returns the string that is @var{symbol}'s name. For example: - -@example -@group -(symbol-name 'foo) - @result{} "foo" -@end group -@end example - -Changing the string by substituting characters, etc, does change the -name of the symbol, but fails to update the obarray, so don't do it! -@end defun - -@defun make-symbol name -This function returns a newly-allocated, uninterned symbol whose name is -@var{name} (which must be a string). Its value and function definition -are void, and its property list is @code{nil}. In the example below, -the value of @code{sym} is not @code{eq} to @code{foo} because it is a -distinct uninterned symbol whose name is also @samp{foo}. - -@example -(setq sym (make-symbol "foo")) - @result{} foo -(eq sym 'foo) - @result{} nil -@end example -@end defun - -@defun intern name &optional obarray -This function returns the interned symbol whose name is @var{name}. If -there is no such symbol in the obarray @var{obarray}, @code{intern} -creates a new one, adds it to the obarray, and returns it. If -@var{obarray} is omitted, the value of the global variable -@code{obarray} is used. - -@example -(setq sym (intern "foo")) - @result{} foo -(eq sym 'foo) - @result{} t - -(setq sym1 (intern "foo" other-obarray)) - @result{} foo -(eq sym 'foo) - @result{} nil -@end example -@end defun - -@defun intern-soft name &optional obarray -This function returns the symbol in @var{obarray} whose name is -@var{name}, or @code{nil} if @var{obarray} has no symbol with that name. -Therefore, you can use @code{intern-soft} to test whether a symbol with -a given name is already interned. If @var{obarray} is omitted, the -value of the global variable @code{obarray} is used. - -@smallexample -(intern-soft "frazzle") ; @r{No such symbol exists.} - @result{} nil -(make-symbol "frazzle") ; @r{Create an uninterned one.} - @result{} frazzle -@group -(intern-soft "frazzle") ; @r{That one cannot be found.} - @result{} nil -@end group -@group -(setq sym (intern "frazzle")) ; @r{Create an interned one.} - @result{} frazzle -@end group -@group -(intern-soft "frazzle") ; @r{That one can be found!} - @result{} frazzle -@end group -@group -(eq sym 'frazzle) ; @r{And it is the same one.} - @result{} t -@end group -@end smallexample -@end defun - -@defvar obarray -This variable is the standard obarray for use by @code{intern} and -@code{read}. -@end defvar - -@defun mapatoms function &optional obarray -This function calls @var{function} for each symbol in the obarray -@var{obarray}. It returns @code{nil}. If @var{obarray} is omitted, it -defaults to the value of @code{obarray}, the standard obarray for -ordinary symbols. - -@smallexample -(setq count 0) - @result{} 0 -(defun count-syms (s) - (setq count (1+ count))) - @result{} count-syms -(mapatoms 'count-syms) - @result{} nil -count - @result{} 1871 -@end smallexample - -See @code{documentation} in @ref{Accessing Documentation}, for another -example using @code{mapatoms}. -@end defun - -@defun unintern symbol &optional obarray -This function deletes @var{symbol} from the obarray @var{obarray}. If -@code{symbol} is not actually in the obarray, @code{unintern} does -nothing. If @var{obarray} is @code{nil}, the current obarray is used. - -If you provide a string instead of a symbol as @var{symbol}, it stands -for a symbol name. Then @code{unintern} deletes the symbol (if any) in -the obarray which has that name. If there is no such symbol, -@code{unintern} does nothing. - -If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise -it returns @code{nil}. -@end defun - -@node Property Lists,, Creating Symbols, Symbols -@section Property Lists -@cindex property list -@cindex plist - - A @dfn{property list} (@dfn{plist} for short) is a list of paired -elements stored in the property list cell of a symbol. Each of the -pairs associates a property name (usually a symbol) with a property or -value. Property lists are generally used to record information about a -symbol, such as its documentation as a variable, the name of the file -where it was defined, or perhaps even the grammatical class of the -symbol (representing a word) in a language-understanding system. - - Character positions in a string or buffer can also have property lists. -@xref{Text Properties}. - - The property names and values in a property list can be any Lisp -objects, but the names are usually symbols. They are compared using -@code{eq}. Here is an example of a property list, found on the symbol -@code{progn} when the compiler is loaded: - -@example -(lisp-indent-function 0 byte-compile byte-compile-progn) -@end example - -@noindent -Here @code{lisp-indent-function} and @code{byte-compile} are property -names, and the other two elements are the corresponding values. - -@menu -* Plists and Alists:: Comparison of the advantages of property - lists and association lists. -* Symbol Plists:: Functions to access symbols' property lists. -* Other Plists:: Accessing property lists stored elsewhere. -@end menu - -@node Plists and Alists -@subsection Property Lists and Association Lists - -@cindex property lists vs association lists - Association lists (@pxref{Association Lists}) are very similar to -property lists. In contrast to association lists, the order of the -pairs in the property list is not significant since the property names -must be distinct. - - Property lists are better than association lists for attaching -information to various Lisp function names or variables. If all the -associations are recorded in one association list, the program will need -to search that entire list each time a function or variable is to be -operated on. By contrast, if the information is recorded in the -property lists of the function names or variables themselves, each -search will scan only the length of one property list, which is usually -short. This is why the documentation for a variable is recorded in a -property named @code{variable-documentation}. The byte compiler -likewise uses properties to record those functions needing special -treatment. - - However, association lists have their own advantages. Depending on -your application, it may be faster to add an association to the front of -an association list than to update a property. All properties for a -symbol are stored in the same property list, so there is a possibility -of a conflict between different uses of a property name. (For this -reason, it is a good idea to choose property names that are probably -unique, such as by including the name of the library in the property -name.) An association list may be used like a stack where associations -are pushed on the front of the list and later discarded; this is not -possible with a property list. - -@node Symbol Plists -@subsection Property List Functions for Symbols - -@defun symbol-plist symbol -This function returns the property list of @var{symbol}. -@end defun - -@defun setplist symbol plist -This function sets @var{symbol}'s property list to @var{plist}. -Normally, @var{plist} should be a well-formed property list, but this is -not enforced. - -@smallexample -(setplist 'foo '(a 1 b (2 3) c nil)) - @result{} (a 1 b (2 3) c nil) -(symbol-plist 'foo) - @result{} (a 1 b (2 3) c nil) -@end smallexample - -For symbols in special obarrays, which are not used for ordinary -purposes, it may make sense to use the property list cell in a -nonstandard fashion; in fact, the abbrev mechanism does so -(@pxref{Abbrevs}). -@end defun - -@defun get symbol property -This function finds the value of the property named @var{property} in -@var{symbol}'s property list. If there is no such property, @code{nil} -is returned. Thus, there is no distinction between a value of -@code{nil} and the absence of the property. - -The name @var{property} is compared with the existing property names -using @code{eq}, so any object is a legitimate property. - -See @code{put} for an example. -@end defun - -@defun put symbol property value -This function puts @var{value} onto @var{symbol}'s property list under -the property name @var{property}, replacing any previous property value. -The @code{put} function returns @var{value}. - -@smallexample -(put 'fly 'verb 'transitive) - @result{}'transitive -(put 'fly 'noun '(a buzzing little bug)) - @result{} (a buzzing little bug) -(get 'fly 'verb) - @result{} transitive -(symbol-plist 'fly) - @result{} (verb transitive noun (a buzzing little bug)) -@end smallexample -@end defun - -@node Other Plists -@subsection Property Lists Outside Symbols - - These two functions are useful for manipulating property lists -that are stored in places other than symbols: - -@defun plist-get plist property -This returns the value of the @var{property} property -stored in the property list @var{plist}. For example, - -@example -(plist-get '(foo 4) 'foo) - @result{} 4 -@end example -@end defun - -@defun plist-put plist property value -This stores @var{value} as the value of the @var{property} property in -the property list @var{plist}. It may modify @var{plist} destructively, -or it may construct a new list structure without altering the old. The -function returns the modified property list, so you can store that back -in the place where you got @var{plist}. For example, - -@example -(setq my-plist '(bar t foo 4)) - @result{} (bar t foo 4) -(setq my-plist (plist-put my-plist 'foo 69)) - @result{} (bar t foo 69) -(setq my-plist (plist-put my-plist 'quux '(a))) - @result{} (quux (a) bar t foo 5) -@end example -@end defun - diff --git a/lispref/syntax.texi b/lispref/syntax.texi deleted file mode 100644 index 585df47580a..00000000000 --- a/lispref/syntax.texi +++ /dev/null @@ -1,723 +0,0 @@ -@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/syntax -@node Syntax Tables, Abbrevs, Searching and Matching, Top -@chapter Syntax Tables -@cindex parsing -@cindex syntax table -@cindex text parsing - - A @dfn{syntax table} specifies the syntactic textual function of each -character. This information is used by the parsing commands, the -complex movement commands, and others to determine where words, symbols, -and other syntactic constructs begin and end. The current syntax table -controls the meaning of the word motion functions (@pxref{Word Motion}) -and the list motion functions (@pxref{List Motion}) as well as the -functions in this chapter. - -@menu -* Basics: Syntax Basics. Basic concepts of syntax tables. -* Desc: Syntax Descriptors. How characters are classified. -* Syntax Table Functions:: How to create, examine and alter syntax tables. -* Motion and Syntax:: Moving over characters with certain syntaxes. -* Parsing Expressions:: Parsing balanced expressions - using the syntax table. -* Standard Syntax Tables:: Syntax tables used by various major modes. -* Syntax Table Internals:: How syntax table information is stored. -@end menu - -@node Syntax Basics -@section Syntax Table Concepts - -@ifinfo - A @dfn{syntax table} provides Emacs with the information that -determines the syntactic use of each character in a buffer. This -information is used by the parsing commands, the complex movement -commands, and others to determine where words, symbols, and other -syntactic constructs begin and end. The current syntax table controls -the meaning of the word motion functions (@pxref{Word Motion}) and the -list motion functions (@pxref{List Motion}) as well as the functions in -this chapter. -@end ifinfo - - A syntax table is a vector of 256 elements; it contains one entry for -each of the 256 possible characters in an 8-bit byte. Each element is -an integer that encodes the syntax of the character in question. - - Syntax tables are used only for moving across text, not for the Emacs -Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp -expressions, and these rules cannot be changed. - - Each buffer has its own major mode, and each major mode has its own -idea of the syntactic class of various characters. For example, in Lisp -mode, the character @samp{;} begins a comment, but in C mode, it -terminates a statement. To support these variations, Emacs makes the -choice of syntax table local to each buffer. Typically, each major -mode has its own syntax table and installs that table in each buffer -that uses that mode. Changing this table alters the syntax in all -those buffers as well as in any buffers subsequently put in that mode. -Occasionally several similar modes share one syntax table. -@xref{Example Major Modes}, for an example of how to set up a syntax -table. - -A syntax table can inherit the data for some characters from the -standard syntax table, while specifying other characters itself. The -``inherit'' syntax class means ``inherit this character's syntax from -the standard syntax table.'' Most major modes' syntax tables inherit -the syntax of character codes 0 through 31 and 128 through 255. This is -useful with character sets such as ISO Latin-1 that have additional -alphabetic characters in the range 128 to 255. Just changing the -standard syntax for these characters affects all major modes. - -@defun syntax-table-p object -This function returns @code{t} if @var{object} is a vector of length 256 -elements. This means that the vector may be a syntax table. However, -according to this test, any vector of length 256 is considered to be a -syntax table, no matter what its contents. -@end defun - -@node Syntax Descriptors -@section Syntax Descriptors -@cindex syntax classes - - This section describes the syntax classes and flags that denote the -syntax of a character, and how they are represented as a @dfn{syntax -descriptor}, which is a Lisp string that you pass to -@code{modify-syntax-entry} to specify the desired syntax. - - Emacs defines a number of @dfn{syntax classes}. Each syntax table -puts each character into one class. There is no necessary relationship -between the class of a character in one syntax table and its class in -any other table. - - Each class is designated by a mnemonic character, which serves as the -name of the class when you need to specify a class. Usually the -designator character is one that is frequently in that class; however, -its meaning as a designator is unvarying and independent of what syntax -that character currently has. - -@cindex syntax descriptor - A syntax descriptor is a Lisp string that specifies a syntax class, a -matching character (used only for the parenthesis classes) and flags. -The first character is the designator for a syntax class. The second -character is the character to match; if it is unused, put a space there. -Then come the characters for any desired flags. If no matching -character or flags are needed, one character is sufficient. - - For example, the descriptor for the character @samp{*} in C mode is -@samp{@w{. 23}} (i.e., punctuation, matching character slot unused, -second character of a comment-starter, first character of an -comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e., -punctuation, matching character slot unused, first character of a -comment-starter, second character of a comment-ender). - -@menu -* Syntax Class Table:: Table of syntax classes. -* Syntax Flags:: Additional flags each character can have. -@end menu - -@node Syntax Class Table -@subsection Table of Syntax Classes - - Here is a table of syntax classes, the characters that stand for them, -their meanings, and examples of their use. - -@deffn {Syntax class} @w{whitespace character} -@dfn{Whitespace characters} (designated with @w{@samp{@ }} or @samp{-}) -separate symbols and words from each other. Typically, whitespace -characters have no other syntactic significance, and multiple whitespace -characters are syntactically equivalent to a single one. Space, tab, -newline and formfeed are almost always classified as whitespace. -@end deffn - -@deffn {Syntax class} @w{word constituent} -@dfn{Word constituents} (designated with @samp{w}) are parts of normal -English words and are typically used in variable and command names in -programs. All upper- and lower-case letters, and the digits, are typically -word constituents. -@end deffn - -@deffn {Syntax class} @w{symbol constituent} -@dfn{Symbol constituents} (designated with @samp{_}) are the extra -characters that are used in variable and command names along with word -constituents. For example, the symbol constituents class is used in -Lisp mode to indicate that certain characters may be part of symbol -names even though they are not part of English words. These characters -are @samp{$&*+-_<>}. In standard C, the only non-word-constituent -character that is valid in symbols is underscore (@samp{_}). -@end deffn - -@deffn {Syntax class} @w{punctuation character} -@dfn{Punctuation characters} (@samp{.}) are those characters that are -used as punctuation in English, or are used in some way in a programming -language to separate symbols from one another. Most programming -language modes, including Emacs Lisp mode, have no characters in this -class since the few characters that are not symbol or word constituents -all have other uses. -@end deffn - -@deffn {Syntax class} @w{open parenthesis character} -@deffnx {Syntax class} @w{close parenthesis character} -@cindex parenthesis syntax -Open and close @dfn{parenthesis characters} are characters used in -dissimilar pairs to surround sentences or expressions. Such a grouping -is begun with an open parenthesis character and terminated with a close. -Each open parenthesis character matches a particular close parenthesis -character, and vice versa. Normally, Emacs indicates momentarily the -matching open parenthesis when you insert a close parenthesis. -@xref{Blinking}. - -The class of open parentheses is designated with @samp{(}, and that of -close parentheses with @samp{)}. - -In English text, and in C code, the parenthesis pairs are @samp{()}, -@samp{[]}, and @samp{@{@}}. In Emacs Lisp, the delimiters for lists and -vectors (@samp{()} and @samp{[]}) are classified as parenthesis -characters. -@end deffn - -@deffn {Syntax class} @w{string quote} -@dfn{String quote characters} (designated with @samp{"}) are used in -many languages, including Lisp and C, to delimit string constants. The -same string quote character appears at the beginning and the end of a -string. Such quoted strings do not nest. - -The parsing facilities of Emacs consider a string as a single token. -The usual syntactic meanings of the characters in the string are -suppressed. - -The Lisp modes have two string quote characters: double-quote (@samp{"}) -and vertical bar (@samp{|}). @samp{|} is not used in Emacs Lisp, but it -is used in Common Lisp. C also has two string quote characters: -double-quote for strings, and single-quote (@samp{'}) for character -constants. - -English text has no string quote characters because English is not a -programming language. Although quotation marks are used in English, -we do not want them to turn off the usual syntactic properties of -other characters in the quotation. -@end deffn - -@deffn {Syntax class} @w{escape} -An @dfn{escape character} (designated with @samp{\}) starts an escape -sequence such as is used in C string and character constants. The -character @samp{\} belongs to this class in both C and Lisp. (In C, it -is used thus only inside strings, but it turns out to cause no trouble -to treat it this way throughout C code.) - -Characters in this class count as part of words if -@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}. -@end deffn - -@deffn {Syntax class} @w{character quote} -A @dfn{character quote character} (designated with @samp{/}) quotes the -following character so that it loses its normal syntactic meaning. This -differs from an escape character in that only the character immediately -following is ever affected. - -Characters in this class count as part of words if -@code{words-include-escapes} is non-@code{nil}. @xref{Word Motion}. - -This class is used for backslash in @TeX{} mode. -@end deffn - -@deffn {Syntax class} @w{paired delimiter} -@dfn{Paired delimiter characters} (designated with @samp{$}) are like -string quote characters except that the syntactic properties of the -characters between the delimiters are not suppressed. Only @TeX{} mode -uses a paired delimiter presently---the @samp{$} that both enters and -leaves math mode. -@end deffn - -@deffn {Syntax class} @w{expression prefix} -An @dfn{expression prefix operator} (designated with @samp{'}) is used -for syntactic operators that are part of an expression if they appear -next to one. These characters in Lisp include the apostrophe, @samp{'} -(used for quoting), the comma, @samp{,} (used in macros), and @samp{#} -(used in the read syntax for certain data types). -@end deffn - -@deffn {Syntax class} @w{comment starter} -@deffnx {Syntax class} @w{comment ender} -@cindex comment syntax -The @dfn{comment starter} and @dfn{comment ender} characters are used in -various languages to delimit comments. These classes are designated -with @samp{<} and @samp{>}, respectively. - -English text has no comment characters. In Lisp, the semicolon -(@samp{;}) starts a comment and a newline or formfeed ends one. -@end deffn - -@deffn {Syntax class} @w{inherit} -This syntax class does not specify a syntax. It says to look in the -standard syntax table to find the syntax of this character. The -designator for this syntax code is @samp{@@}. -@end deffn - -@node Syntax Flags -@subsection Syntax Flags -@cindex syntax flags - - In addition to the classes, entries for characters in a syntax table -can include flags. There are six possible flags, represented by the -characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b} and -@samp{p}. - - All the flags except @samp{p} are used to describe multi-character -comment delimiters. The digit flags indicate that a character can -@emph{also} be part of a comment sequence, in addition to the syntactic -properties associated with its character class. The flags are -independent of the class and each other for the sake of characters such -as @samp{*} in C mode, which is a punctuation character, @emph{and} the -second character of a start-of-comment sequence (@samp{/*}), @emph{and} -the first character of an end-of-comment sequence (@samp{*/}). - -The flags for a character @var{c} are: - -@itemize @bullet -@item -@samp{1} means @var{c} is the start of a two-character comment-start -sequence. - -@item -@samp{2} means @var{c} is the second character of such a sequence. - -@item -@samp{3} means @var{c} is the start of a two-character comment-end -sequence. - -@item -@samp{4} means @var{c} is the second character of such a sequence. - -@item -@c Emacs 19 feature -@samp{b} means that @var{c} as a comment delimiter belongs to the -alternative ``b'' comment style. - -Emacs supports two comment styles simultaneously in any one syntax -table. This is for the sake of C++. Each style of comment syntax has -its own comment-start sequence and its own comment-end sequence. Each -comment must stick to one style or the other; thus, if it starts with -the comment-start sequence of style ``b'', it must also end with the -comment-end sequence of style ``b''. - -The two comment-start sequences must begin with the same character; only -the second character may differ. Mark the second character of the -``b''-style comment-start sequence with the @samp{b} flag. - -A comment-end sequence (one or two characters) applies to the ``b'' -style if its first character has the @samp{b} flag set; otherwise, it -applies to the ``a'' style. - -The appropriate comment syntax settings for C++ are as follows: - -@table @asis -@item @samp{/} -@samp{124b} -@item @samp{*} -@samp{23} -@item newline -@samp{>b} -@end table - -This defines four comment-delimiting sequences: - -@table @asis -@item @samp{/*} -This is a comment-start sequence for ``a'' style because the -second character, @samp{*}, does not have the @samp{b} flag. - -@item @samp{//} -This is a comment-start sequence for ``b'' style because the second -character, @samp{/}, does have the @samp{b} flag. - -@item @samp{*/} -This is a comment-end sequence for ``a'' style because the first -character, @samp{*}, does not have the @samp{b} flag - -@item newline -This is a comment-end sequence for ``b'' style, because the newline -character has the @samp{b} flag. -@end table - -@item -@c Emacs 19 feature -@samp{p} identifies an additional ``prefix character'' for Lisp syntax. -These characters are treated as whitespace when they appear between -expressions. When they appear within an expression, they are handled -according to their usual syntax codes. - -The function @code{backward-prefix-chars} moves back over these -characters, as well as over characters whose primary syntax class is -prefix (@samp{'}). @xref{Motion and Syntax}. -@end itemize - -@node Syntax Table Functions -@section Syntax Table Functions - - In this section we describe functions for creating, accessing and -altering syntax tables. - -@defun make-syntax-table -This function creates a new syntax table. Character codes 0 through -31 and 128 through 255 are set up to inherit from the standard syntax -table. The other character codes are set up by copying what the -standard syntax table says about them. - -Most major mode syntax tables are created in this way. -@end defun - -@defun copy-syntax-table &optional table -This function constructs a copy of @var{table} and returns it. If -@var{table} is not supplied (or is @code{nil}), it returns a copy of the -current syntax table. Otherwise, an error is signaled if @var{table} is -not a syntax table. -@end defun - -@deffn Command modify-syntax-entry char syntax-descriptor &optional table -This function sets the syntax entry for @var{char} according to -@var{syntax-descriptor}. The syntax is changed only for @var{table}, -which defaults to the current buffer's syntax table, and not in any -other syntax table. The argument @var{syntax-descriptor} specifies the -desired syntax; this is a string beginning with a class designator -character, and optionally containing a matching character and flags as -well. @xref{Syntax Descriptors}. - -This function always returns @code{nil}. The old syntax information in -the table for this character is discarded. - -An error is signaled if the first character of the syntax descriptor is not -one of the twelve syntax class designator characters. An error is also -signaled if @var{char} is not a character. - -@example -@group -@exdent @r{Examples:} - -;; @r{Put the space character in class whitespace.} -(modify-syntax-entry ?\ " ") - @result{} nil -@end group - -@group -;; @r{Make @samp{$} an open parenthesis character,} -;; @r{with @samp{^} as its matching close.} -(modify-syntax-entry ?$ "(^") - @result{} nil -@end group - -@group -;; @r{Make @samp{^} a close parenthesis character,} -;; @r{with @samp{$} as its matching open.} -(modify-syntax-entry ?^ ")$") - @result{} nil -@end group - -@group -;; @r{Make @samp{/} a punctuation character,} -;; @r{the first character of a start-comment sequence,} -;; @r{and the second character of an end-comment sequence.} -;; @r{This is used in C mode.} -(modify-syntax-entry ?/ ". 14") - @result{} nil -@end group -@end example -@end deffn - -@defun char-syntax character -This function returns the syntax class of @var{character}, represented -by its mnemonic designator character. This @emph{only} returns the -class, not any matching parenthesis or flags. - -An error is signaled if @var{char} is not a character. - -The following examples apply to C mode. The first example shows that -the syntax class of space is whitespace (represented by a space). The -second example shows that the syntax of @samp{/} is punctuation. This -does not show the fact that it is also part of comment-start and -end -sequences. The third example shows that open parenthesis is in the class -of open parentheses. This does not show the fact that it has a matching -character, @samp{)}. - -@example -@group -(char-to-string (char-syntax ?\ )) - @result{} " " -@end group - -@group -(char-to-string (char-syntax ?/)) - @result{} "." -@end group - -@group -(char-to-string (char-syntax ?\()) - @result{} "(" -@end group -@end example -@end defun - -@defun set-syntax-table table -This function makes @var{table} the syntax table for the current buffer. -It returns @var{table}. -@end defun - -@defun syntax-table -This function returns the current syntax table, which is the table for -the current buffer. -@end defun - -@node Motion and Syntax -@section Motion and Syntax - - This section describes functions for moving across characters in -certain syntax classes. None of these functions exists in Emacs -version 18 or earlier. - -@defun skip-syntax-forward syntaxes &optional limit -This function moves point forward across characters having syntax classes -mentioned in @var{syntaxes}. It stops when it encounters the end of -the buffer, or position @var{limit} (if specified), or a character it is -not supposed to skip. -@ignore @c may want to change this. -The return value is the distance traveled, which is a nonnegative -integer. -@end ignore -@end defun - -@defun skip-syntax-backward syntaxes &optional limit -This function moves point backward across characters whose syntax -classes are mentioned in @var{syntaxes}. It stops when it encounters -the beginning of the buffer, or position @var{limit} (if specified), or a -character it is not supposed to skip. -@ignore @c may want to change this. -The return value indicates the distance traveled. It is an integer that -is zero or less. -@end ignore -@end defun - -@defun backward-prefix-chars -This function moves point backward over any number of characters with -expression prefix syntax. This includes both characters in the -expression prefix syntax class, and characters with the @samp{p} flag. -@end defun - -@node Parsing Expressions -@section Parsing Balanced Expressions - - Here are several functions for parsing and scanning balanced -expressions, also known as @dfn{sexps}, in which parentheses match in -pairs. The syntax table controls the interpretation of characters, so -these functions can be used for Lisp expressions when in Lisp mode and -for C expressions when in C mode. @xref{List Motion}, for convenient -higher-level functions for moving over balanced expressions. - -@defun parse-partial-sexp start limit &optional target-depth stop-before state stop-comment -This function parses a sexp in the current buffer starting at -@var{start}, not scanning past @var{limit}. It stops at position -@var{limit} or when certain criteria described below are met, and sets -point to the location where parsing stops. It returns a value -describing the status of the parse at the point where it stops. - -If @var{state} is @code{nil}, @var{start} is assumed to be at the top -level of parenthesis structure, such as the beginning of a function -definition. Alternatively, you might wish to resume parsing in the -middle of the structure. To do this, you must provide a @var{state} -argument that describes the initial status of parsing. - -@cindex parenthesis depth -If the third argument @var{target-depth} is non-@code{nil}, parsing -stops if the depth in parentheses becomes equal to @var{target-depth}. -The depth starts at 0, or at whatever is given in @var{state}. - -If the fourth argument @var{stop-before} is non-@code{nil}, parsing -stops when it comes to any character that starts a sexp. If -@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the -start of a comment. - -@cindex parse state -The fifth argument @var{state} is an eight-element list of the same -form as the value of this function, described below. The return value -of one call may be used to initialize the state of the parse on another -call to @code{parse-partial-sexp}. - -The result is a list of eight elements describing the final state of -the parse: - -@enumerate 0 -@item -The depth in parentheses, counting from 0. - -@item -@cindex innermost containing parentheses -The character position of the start of the innermost parenthetical -grouping containing the stopping point; @code{nil} if none. - -@item -@cindex previous complete subexpression -The character position of the start of the last complete subexpression -terminated; @code{nil} if none. - -@item -@cindex inside string -Non-@code{nil} if inside a string. More precisely, this is the -character that will terminate the string. - -@item -@cindex inside comment -@code{t} if inside a comment (of either style). - -@item -@cindex quote character -@code{t} if point is just after a quote character. - -@item -The minimum parenthesis depth encountered during this scan. - -@item -@code{t} if inside a comment of style ``b''. -@end enumerate - -Elements 0, 3, 4, 5 and 7 are significant in the argument @var{state}. - -@cindex indenting with parentheses -This function is most often used to compute indentation for languages -that have nested parentheses. -@end defun - -@defun scan-lists from count depth -This function scans forward @var{count} balanced parenthetical groupings -from character number @var{from}. It returns the character position -where the scan stops. - -If @var{depth} is nonzero, parenthesis depth counting begins from that -value. The only candidates for stopping are places where the depth in -parentheses becomes zero; @code{scan-lists} counts @var{count} such -places and then stops. Thus, a positive value for @var{depth} means go -out @var{depth} levels of parenthesis. - -Scanning ignores comments if @code{parse-sexp-ignore-comments} is -non-@code{nil}. - -If the scan reaches the beginning or end of the buffer (or its -accessible portion), and the depth is not zero, an error is signaled. -If the depth is zero but the count is not used up, @code{nil} is -returned. -@end defun - -@defun scan-sexps from count -This function scans forward @var{count} sexps from character position -@var{from}. It returns the character position where the scan stops. - -Scanning ignores comments if @code{parse-sexp-ignore-comments} is -non-@code{nil}. - -If the scan reaches the beginning or end of (the accessible part of) the -buffer in the middle of a parenthetical grouping, an error is signaled. -If it reaches the beginning or end between groupings but before count is -used up, @code{nil} is returned. -@end defun - -@defvar parse-sexp-ignore-comments -@cindex skipping comments -If the value is non-@code{nil}, then comments are treated as -whitespace by the functions in this section and by @code{forward-sexp}. - -In older Emacs versions, this feature worked only when the comment -terminator is something like @samp{*/}, and appears only to end a -comment. In languages where newlines terminate comments, it was -necessary make this variable @code{nil}, since not every newline is the -end of a comment. This limitation no longer exists. -@end defvar - -You can use @code{forward-comment} to move forward or backward over -one comment or several comments. - -@defun forward-comment count -This function moves point forward across @var{count} comments (backward, -if @var{count} is negative). If it finds anything other than a comment -or whitespace, it stops, leaving point at the place where it stopped. -It also stops after satisfying @var{count}. -@end defun - -To move forward over all comments and whitespace following point, use -@code{(forward-comment (buffer-size))}. @code{(buffer-size)} is a good -argument to use, because the number of comments in the buffer cannot -exceed that many. - -@node Standard Syntax Tables -@section Some Standard Syntax Tables - - Most of the major modes in Emacs have their own syntax tables. Here -are several of them: - -@defun standard-syntax-table -This function returns the standard syntax table, which is the syntax -table used in Fundamental mode. -@end defun - -@defvar text-mode-syntax-table -The value of this variable is the syntax table used in Text mode. -@end defvar - -@defvar c-mode-syntax-table -The value of this variable is the syntax table for C-mode buffers. -@end defvar - -@defvar emacs-lisp-mode-syntax-table -The value of this variable is the syntax table used in Emacs Lisp mode -by editing commands. (It has no effect on the Lisp @code{read} -function.) -@end defvar - -@node Syntax Table Internals -@section Syntax Table Internals -@cindex syntax table internals - - Each element of a syntax table is an integer that encodes the syntax -of one character: the syntax class, possible matching character, and -flags. Lisp programs don't usually work with the elements directly; the -Lisp-level syntax table functions usually work with syntax descriptors -(@pxref{Syntax Descriptors}). - - The low 8 bits of each element of a syntax table indicate the -syntax class. - -@table @asis -@item @i{Integer} -@i{Class} -@item 0 -whitespace -@item 1 -punctuation -@item 2 -word -@item 3 -symbol -@item 4 -open parenthesis -@item 5 -close parenthesis -@item 6 -expression prefix -@item 7 -string quote -@item 8 -paired delimiter -@item 9 -escape -@item 10 -character quote -@item 11 -comment-start -@item 12 -comment-end -@item 13 -inherit -@end table - - The next 8 bits are the matching opposite parenthesis (if the -character has parenthesis syntax); otherwise, they are not meaningful. -The next 6 bits are the flags. diff --git a/lispref/text.texi b/lispref/text.texi deleted file mode 100644 index fb718fa41e1..00000000000 --- a/lispref/text.texi +++ /dev/null @@ -1,3016 +0,0 @@ -@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, together with their properties (when relevant). - -@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. -* Margins:: How to specify margins for filling commands. -* 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. -* Transposition:: Swapping two portions of a buffer. -* 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. - -If the text being copied has any text properties, these are copied into -the string along with the characters they belong to. @xref{Text -Properties}. However, overlays (@pxref{Overlays}) in the buffer and -their properties are ignored, not copied. - -@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-substring-no-properties start end -This is like @code{buffer-substring}, except that it does not copy text -properties, just the characters themselves. @xref{Text Properties}. -Here's an example of using this function to get a word to look up in an -alist: - -@example -(setq flammable - (assoc (buffer-substring start end) - '(("wood" . t) ("paper" . t) - ("steel" . nil) ("asbestos" . nil)))) -@end example - -If this were written using @code{buffer-substring} instead, it would not -work reliably; any text properties that happened to be in the word -copied from the buffer would make the comparisons fail. -@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}. It always ignores -text properties. - -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 -@end defun - -@node Insertion -@section Inserting Text -@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 former insertion @dfn{after -point} and the latter insertion @dfn{before point}. - - Insertion functions signal an error if the current buffer is -read-only. - - These functions copy text characters from strings and buffers along -with their properties. The inserted characters have exactly the same -properties as the characters they were copied from. By contrast, -characters specified as separate arguments, not part of a string or -buffer, inherit their text properties from the neighboring text. - -@defun insert &rest args -This function inserts the strings and/or characters @var{args} into the -current buffer, at point, moving point forward. In other words, it -inserts the text before point. 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 &optional inherit -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. - -If @var{inherit} is non-@code{nil}, then the inserted characters inherit -sticky text properties from the two characters before and after the -insertion point. @xref{Sticky Properties}. -@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@point{} ----------- Buffer: bar ---------- -@end group -@end example -@end defun - - @xref{Sticky Properties}, for other insertion functions that inherit -text properties from the nearby text in addition to inserting it. -Whitespace inserted by indentation functions also inherits text -properties. - -@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; it does so @var{count} -times, before point, 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 command calls @code{auto-fill-function} whenever that is -non-@code{nil} and the character inserted is a space or a newline -(@pxref{Auto Filling}). - -@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92 -This command 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 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 -This function calls @code{auto-fill-function} if the current column -number is greater than the value of @code{fill-column} and -@var{number-of-newlines} is @code{nil}. Typically what -@code{auto-fill-function} does is insert a newline; thus, the overall -result in this case is to insert 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}. - -This command indents to the left margin if that is not zero. -@xref{Margins}. - -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 Deleting 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 do save text in the kill ring in some special -cases. - - 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}. If -point was inside the deleted region, its value afterward is @var{start}. -Otherwise, point relocates with the surrounding text, as markers do. -@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 line each time. - -@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. @xref{Margins}. - -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 -@group ----------- Buffer: foo ---------- -When in the course of human -@point{} events, it becomes necessary ----------- Buffer: foo ---------- -@end group - -(delete-indentation) - @result{} nil - -@group ----------- Buffer: foo ---------- -When in the course of human@point{} events, it becomes necessary ----------- Buffer: foo ---------- -@end group -@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 delete 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 that holds a number of recent kills, not just the last text -kill. We call this a ``ring'' because yanking treats it as having -elements in 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, -that treat it as a ring. - - Some people think this use of the word ``kill'' is unfortunate, since -it refers to operations that 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 command 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, along with -its text properties. 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 (including text properties), 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. - -The command does not set @code{this-command} to @code{kill-region}, so a -subsequent kill command does not append to the same kill ring entry. - -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. The text properties are copied too. - -@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 which -designates the ``front'' of the kill ring by @var{n} places (from newer -kills to older ones), 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, counting 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 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. We say it -identifies the ``front'' of the ring. Moving -@code{kill-ring-yank-pointer} to a different link is called -@dfn{rotating the kill 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 to the value of @code{kill-ring}. The effect is to -rotate the ring so that the newly killed text is at the 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 the 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 that -don't have one are usually special-purpose buffers for which Emacs -assumes that undoing is not useful.) All the primitives that 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{text} . @var{position}) -This kind of element indicates how to reinsert text that was deleted. -The deleted text itself is the string @var{text}. The place to -reinsert it is @code{(abs @var{position})}. - -@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 (@var{marker} . @var{adjustment}) -This kind of element records the fact that the marker @var{marker} was -relocated due to deletion of surrounding text, and that it moved -@var{adjustment} character positions. Undoing this element moves -@var{marker} @minus{} @var{adjustment} characters. - -@item @var{position} -This element indicates where point was at an earlier time. Undoing this -element sets point to @var{position}. Deletion normally creates an -element of this kind as well as a reinsertion element. - -@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 before -each key sequence is executed. Thus, each undo normally undoes the -effects of one command. Self-inserting input characters are an -exception. The command loop makes a boundary for the first such -character; the next 19 consecutive self-inserting input characters do -not make boundaries, and then the 20th does, and so on as long as -self-inserting characters continue. - -All buffer modifications add a boundary whenever the previous undoable -change was made in some other buffer. This way, a command that modifies -several buffers makes a boundary in each buffer it changes. - -Calling this function explicitly is useful for splitting the effects of -a command into more than one unit. For example, @code{query-replace} -calls @code{undo-boundary} 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 this 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 -This is 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 older change groups). There is one exception: the very latest -change group is never discarded 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 -inserting spaces to make the left and/or right margins line up -precisely. 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 commands in this section return values that are not -meaningful. All the functions that do filling take note of the current -left margin, current right margin, and current justification style -(@pxref{Margins}). If the current justification style is -@code{none}, the filling functions don't actually do anything. - - Several of the filling functions have an argument @var{justify}. -If it is non-@code{nil}, that requests some kind of justification. It -can be @code{left}, @code{right}, @code{full}, or @code{center}, to -request a specific style of justification. If it is @code{t}, that -means to use the current justification style for this part of the text -(see @code{current-justification}, below). - - When you call the filling functions interactively, using a prefix -argument implies the value @code{full} for @var{justify}. - -@deffn Command fill-paragraph justify -@cindex filling a paragraph -This command fills the paragraph at or after point. If -@var{justify} 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 -This command fills each of the paragraphs in the region from @var{start} -to @var{end}. It justifies as well if @var{justify} 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 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} and @var{mail-flag}, are optional. If -@var{justify} 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 indented -paragraphs with additional 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 -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} is non-@code{nil}. - -In an interactive call, any prefix argument requests justification. - -In Adaptive Fill mode, which is enabled by default, calling the function -@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 how eop nosqueeze -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}. - -The argument @var{how}, if non-@code{nil} specifies explicitly the style -of justification. It can be @code{left}, @code{right}, @code{full}, -@code{center}, or @code{none}. If it is @code{t}, that means to do -follow specified justification style (see @code{current-justification}, -below). @code{nil} means to do full justification. - -If @var{eop} is non-@code{nil}, that means do left-justification if -@code{current-justification} specifies full justification. This is used -for the last line of a paragraph; even if the paragraph as a whole is -fully justified, the last line should not be. - -If @var{nosqueeze} is non-@code{nil}, that means do not change interior -whitespace. -@end deffn - -@defopt default-justification -This variable's value specifies the style of justification to use for -text that doesn't specify a style with a text property. The possible -values are @code{left}, @code{right}, @code{full}, @code{center}, or -@code{none}. The default value is @code{left}. -@end defopt - -@defun current-justification -This function returns the proper justification style to use for filling -the text around point. -@end defun - -@defvar fill-paragraph-function -This variable provides a way for major modes to override the filling of -paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls -this function to do the work. If the function returns a non-@code{nil} -value, @code{fill-paragraph} assumes the job is done, and immediately -returns that value. - -The usual use of this feature is to fill comments in programming -language modes. If the function needs to fill a paragraph in the usual -way, it can do so as follows: - -@example -(let ((fill-paragraph-function nil)) - (fill-paragraph arg)) -@end example -@end defvar - -@defvar use-hard-newlines -If this variable is non-@code{nil}, the filling functions do not delete -newlines that have the @code{hard} text property. These ``hard -newlines'' act as paragraph separators. -@end defvar - -@node Margins -@section Margins for Filling - -@defopt fill-prefix -This variable specifies a string of text that appears at the beginning -of normal text lines and should be disregarded when filling them. Any -line that fails to start with the fill prefix is considered the start of -a paragraph; so is any line that starts with the fill prefix followed by -additional whitespace. Lines that start with the fill prefix but no -additional whitespace are ordinary text lines that can be filled -together. The resulting filled lines also start with the fill prefix. - -The fill prefix follows the left margin whitespace, if any. -@end defopt - -@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 - -@deffn Command set-left-margin from to margin -This sets the @code{left-margin} property on the text from @var{from} to -@var{to} to the value @var{margin}. If Auto Fill mode is enabled, this -command also refills the region to fit the new margin. -@end deffn - -@deffn Command set-right-margin from to margin -This sets the @code{right-margin} property on the text from @var{from} -to @var{to} to the value @var{margin}. If Auto Fill mode is enabled, -this command also refills the region to fit the new margin. -@end deffn - -@defun current-left-margin -This function returns the proper left margin value to use for filling -the text around point. The value is the sum of the @code{left-margin} -property of the character at the start of the current line (or zero if -none), and the value of the variable @code{left-margin}. -@end defun - -@defun current-fill-column -This function returns the proper fill column value to use for filling -the text around point. The value is the value of the @code{fill-column} -variable, minus the value of the @code{right-margin} property of the -character after point. -@end defun - -@deffn Command move-to-left-margin &optional n force -This function moves point to the left margin of the current line. The -column moved to is determined by calling the function -@code{current-left-margin}. If the argument @var{n} is non-@code{nil}, -@code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first. - -If @var{force} is non-@code{nil}, that says to fix the line's -indentation if that doesn't match the left margin value. -@end deffn - -@defun delete-to-left-margin from to -This function removes left margin indentation from the text -between @var{from} and @var{to}. The amount of indentation -to delete is determined by calling @code{current-left-margin}. -In no case does this function delete non-whitespace. -@end defun - -@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 - -@defvar left-margin -This variable specifies the base left margin column. In Fundamental -mode, @key{LFD} indents to this column. This variable automatically -becomes buffer-local when set in any fashion. -@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 that fills lines automatically as text -is inserted. This section describes the hook used by Auto Fill mode. -For a description of functions that you can call explicitly to fill and -justify existing text, see @ref{Filling}. - - Auto Fill mode also enables the functions that change the margins and -justification style to refill portions of the text. @xref{Margins}. - -@defvar auto-fill-function -The value of this variable should be a function (of no arguments) to be -called after self-inserting a space or a newline. It may be @code{nil}, -in which case nothing special is done in that case. - -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 - -@defvar normal-auto-fill-function -This variable specifies the function to use for -@code{auto-fill-function}, if and when Auto Fill is turned on. Major -modes can set this locally to alter how Auto Fill works. -@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. -@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 add -whitespace 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}. Otherwise the function does nothing if point is already -beyond @var{column}. The value is the column at which the inserted -indentation ends. - -The inserted whitespace characters inherit text properties from the -surrounding text (usually, from the preceding text only). @xref{Sticky -Properties}. -@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 that inserts a tab character.) -@end deffn - -@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 that 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 definition: 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 @var{to-column} 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 that 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 that 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 the word before point -is ignored when moving forward. 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. -* Format Properties:: Properties for representing formatting of text. -* Sticky Properties:: How inserted text gets properties from - neighboring text. -* Saving Properties:: Saving text properties in files, and reading - them back. -* Lazy Properties:: Computing text properties in a lazy fashion - only when text is examined. -* 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 that 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 - -@defvar default-text-properties -This variable holds a property list giving default values for text -properties. Whenever a character does not specify a value for a -property, neither directly nor through a category symbol, the value -stored in this list is used instead. Here is an example: - -@example -(setq default-text-properties '(foo 69)) -;; @r{Make sure character 1 has no properties of its own.} -(set-text-properties 1 2 nil) -;; @r{What we get, when we ask, is the default value.} -(get-text-property 1 'foo) - @result{} 69 -@end example -@end defvar - -@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 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 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 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 - -See also the function @code{buffer-substring-no-properties} -(@pxref{Buffer Contents}) which copies text from the buffer -but does not copy its properties. - -@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. They use @code{eq} for -comparing property values. 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 scanning to the -end of the buffer, if the property you are interested in does not change. - -Remember that a position is always between two characters; the position -returned by these functions is between two characters with different -properties. - -@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}. -@end defun - -@defun previous-single-property-change pos prop &optional object limit -This is like @code{next-single-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 - - Here is a table of text property names that have special built-in -meanings. The following section lists a few more special property names -that are used to control filling. All other names have no standard -meaning, and you can use them as you like. - -@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. Its value is a face name or a list of face names. @xref{Faces}, -for more information. This feature may be 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, if non-@code{nil}, 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 can make a character invisible -on the screen. @xref{Invisible Text}, for details. - -@item intangible -@kindex intangible @r{(text property)} -If a group of consecutive characters have equal and non-@code{nil} -@code{intangible} properties, then you cannot place point between them. -If you try to move point forward into the group, point actually moves to -the end of the group. If you try to move point backward into the group, -point actually moves to the start of the group. - -When the variable @code{inhibit-point-motion-hooks} is non-@code{nil}, -the @code{intangible} property is ignored. - -@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)} -The operation of inserting text in a buffer also 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. The functions are called -@emph{after} the actual insertion takes place. - -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). In any case, all the -@code{point-left} functions are called first, followed by all 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, and the @code{intangible} -property has no effect. -@end defvar - -@node Format Properties -@subsection Formatted Text Properties - - These text properties affect the behavior of the fill commands. They -are used for representing formatted text. @xref{Filling}, and -@ref{Margins}. - -@table @code -@item hard -If a newline character has this property, it is a ``hard'' newline. -The fill commands do not alter hard newlines and do not move words -across them. However, this property takes effect only if the variable -@code{use-hard-newlines} is non-@code{nil}. - -@item right-margin -This property specifies an extra right margin for filling this part of the -text. - -@item left-margin -This property specifies an extra left margin for filling this part of the -text. - -@item justification -This property specifies the style of justification for filling this part -of the text. -@end table - -@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 primitives described in this -section. Self-inserting characters inherit properties because they work -using these primitives. - - 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 Properties 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-annotate-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. - -@xref{Format Conversion}, for a related feature. - -@c ??? In next edition, merge this info Format Conversion. - -@node Lazy Properties -@subsection Lazy Computation of Text Properties - - Instead of computing text properties for all the text in the buffer, -you can arrange to compute the text properties for parts of the text -when and if something depends on them. - - The primitive that extracts text from the buffer along with its -properties is @code{buffer-substring}. Before examining the properties, -this function runs the abnormal hook @code{buffer-access-fontify-functions}. - -@defvar buffer-access-fontify-functions -This variable holds a list of functions for computing text properties. -Before @code{buffer-substring} copies the text and text properties for a -portion of the buffer, it calls all the functions in this list. Each of -the functions receives two arguments that specify the range of the -buffer being accessed. (The buffer itself is always the current -buffer.) -@end defvar - - The function @code{buffer-substring-no-properties} does not call these -functions, since it ignores text properties anyway. - - In order to prevent the hook functions from being called more than -once for the same part of the buffer, you can use the variable -@code{buffer-access-fontified-property}. - -@defvar buffer-access-fontified-property -If this value's variable is non-@code{nil}, it is a symbol which is used -as a text property name. A non-@code{nil} value for that text property -means, ``the other text properties for this character have already been -computed.'' - -If all the characters in the range specified for @code{buffer-substring} -have a non-@code{nil} value for this property, @code{buffer-substring} -does not call the @code{buffer-access-fontify-functions} functions. It -assumes these characters already have the right text properties, and -just copies the properties they already have. - -The normal way to use this feature is that the -@code{buffer-access-fontify-functions} functions add this property, as -well as others, to the characters they operate on. That way, they avoid -being called over and over for the same text. -@end defvar - -@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 used for controlling selective display (@pxref{Selective -Display}). - -@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 that were actually changed by the translation. This does -not count characters that were mapped into themselves in the -translation table. -@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 that 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 Transposition -@section Transposition of Text - - This subroutine is used by the transposition commands. - -@defun transpose-regions start1 end1 start2 end2 &optional leave-markers -This function exchanges two nonoverlapping portions of the buffer. -Arguments @var{start1} and @var{end1} specify the bounds of one portion -and arguments @var{start2} and @var{end2} specify the bounds of the -other portion. - -Normally, @code{transpose-regions} relocates markers with the transposed -text; a marker previously positioned within one of the two transposed -portions moves along with that portion, thus remaining between the same -two characters in their new position. However, if @var{leave-markers} -is non-@code{nil}, @code{transpose-regions} does not do this---it leaves -all markers unrelocated. -@end defun - -@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-functions -This variable holds a list of a functions to call before any buffer -modification. Each function gets two arguments, 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-functions -This variable holds a list of a functions to call after any buffer -modification. Each function 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 - -@defvar before-change-function -This obsolete variable holds one function to call before any buffer -modification (or @code{nil} for no function). It is called just like -the functions in @code{before-change-functions}. -@end defvar - -@defvar after-change-function -This obsolete variable holds one function to call after any buffer modification -(or @code{nil} for no function). It is called just like the functions in -@code{after-change-functions}. -@end defvar - -The four variables above are temporarily bound to @code{nil} during the -time that any of these functions is running. This means that if one of -these functions changes the buffer, that change won't run these -functions. If you do want a hook function to make changes that run -these functions, make it bind these variables back to their usual -values. - -One inconvenient result of this protective feature is that you cannot -have a function in @code{after-change-functions} or -@code{before-change-functions} which changes the value of that variable. -But that's not a real limitation. If you want those functions to change -the list of functions to run, simply add one fixed function to the hook, -and code that function to look in another variable for other functions -to call. Here is an example: - -@example -(setq my-own-after-change-functions nil) -(defun indirect-after-change-function (beg end len) - (let ((list my-own-after-change-functions)) - (while list - (funcall (car list) beg end len) - (setq list (cdr list))))) -(add-hooks 'after-change-functions - 'indirect-after-change-function) -@end example - -@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 diff --git a/lispref/tips.texi b/lispref/tips.texi deleted file mode 100644 index 1d797fb3ef9..00000000000 --- a/lispref/tips.texi +++ /dev/null @@ -1,683 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. -@c See the file elisp.texi for copying conditions. -@setfilename ../info/tips -@node Tips, GNU Emacs Internals, Calendar, Top -@appendix Tips and Standards -@cindex tips -@cindex standards of coding style -@cindex coding standards - - This chapter describes no additional features of Emacs Lisp. -Instead it gives advice on making effective use of the features described -in the previous chapters. - -@menu -* Style Tips:: Writing clean and robust programs. -* Compilation Tips:: Making compiled code run fast. -* Documentation Tips:: Writing readable documentation strings. -* Comment Tips:: Conventions for writing comments. -* Library Headers:: Standard headers for library packages. -@end menu - -@node Style Tips -@section Writing Clean Lisp Programs - - Here are some tips for avoiding common errors in writing Lisp code -intended for widespread use: - -@itemize @bullet -@item -Since all global variables share the same name space, and all functions -share another name space, you should choose a short word to distinguish -your program from other Lisp programs. Then take care to begin the -names of all global variables, constants, and functions with the chosen -prefix. This helps avoid name conflicts. - -This recommendation applies even to names for traditional Lisp -primitives that are not primitives in Emacs Lisp---even to @code{cadr}. -Believe it or not, there is more than one plausible way to define -@code{cadr}. Play it safe; append your name prefix to produce a name -like @code{foo-cadr} or @code{mylib-cadr} instead. - -If you write a function that you think ought to be added to Emacs under -a certain name, such as @code{twiddle-files}, don't call it by that name -in your program. Call it @code{mylib-twiddle-files} in your program, -and send mail to @samp{bug-gnu-emacs@@prep.ai.mit.edu} suggesting we add -it to Emacs. If and when we do, we can change the name easily enough. - -If one prefix is insufficient, your package may use two or three -alternative common prefixes, so long as they make sense. - -Separate the prefix from the rest of the symbol name with a hyphen, -@samp{-}. This will be consistent with Emacs itself and with most Emacs -Lisp programs. - -@item -It is often useful to put a call to @code{provide} in each separate -library program, at least if there is more than one entry point to the -program. - -@item -If a file requires certain other library programs to be loaded -beforehand, then the comments at the beginning of the file should say -so. Also, use @code{require} to make sure they are loaded. - -@item -If one file @var{foo} uses a macro defined in another file @var{bar}, -@var{foo} should contain this expression before the first use of the -macro: - -@example -(eval-when-compile (require '@var{bar})) -@end example - -@noindent -(And @var{bar} should contain @code{(provide '@var{bar})}, to make the -@code{require} work.) This will cause @var{bar} to be loaded when you -byte-compile @var{foo}. Otherwise, you risk compiling @var{foo} without -the necessary macro loaded, and that would produce compiled code that -won't work right. @xref{Compiling Macros}. - -Using @code{eval-when-compile} avoids loading @var{bar} when -the compiled version of @var{foo} is @emph{used}. - -@item -If you define a major mode, make sure to run a hook variable using -@code{run-hooks}, just as the existing major modes do. @xref{Hooks}. - -@item -If the purpose of a function is to tell you whether a certain condition -is true or false, give the function a name that ends in @samp{p}. If -the name is one word, add just @samp{p}; if the name is multiple words, -add @samp{-p}. Examples are @code{framep} and @code{frame-live-p}. - -@item -If a user option variable records a true-or-false condition, give it a -name that ends in @samp{-flag}. - -@item -Please do not define @kbd{C-c @var{letter}} as a key in your major -modes. These sequences are reserved for users; they are the -@strong{only} sequences reserved for users, so we cannot do without -them. - -Instead, define sequences consisting of @kbd{C-c} followed by a control -character, a digit, or certain punctuation characters. These sequences -are reserved for major modes. - -Changing all the major modes in Emacs 18 so they would follow this -convention was a lot of work. Abandoning this convention would make -that work go to waste, and inconvenience users. - -@item -Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}}, -@kbd{<}, @kbd{>}, @kbd{:} or @kbd{;} are also reserved for major modes. - -@item -Sequences consisting of @kbd{C-c} followed by any other punctuation -character are allocated for minor modes. Using them in a major mode is -not absolutely prohibited, but if you do that, the major mode binding -may be shadowed from time to time by minor modes. - -@item -You should not bind @kbd{C-h} following any prefix character (including -@kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available -as a help character for listing the subcommands of the prefix character. - -@item -You should not bind a key sequence ending in @key{ESC} except following -another @key{ESC}. (That is, it is ok to bind a sequence ending in -@kbd{@key{ESC} @key{ESC}}.) - -The reason for this rule is that a non-prefix binding for @key{ESC} in -any context prevents recognition of escape sequences as function keys in -that context. - -@item -Applications should not bind mouse events based on button 1 with the -shift key held down. These events include @kbd{S-mouse-1}, -@kbd{M-S-mouse-1}, @kbd{C-S-mouse-1}, and so on. They are reserved for -users. - -@item -Modes should redefine @kbd{mouse-2} as a command to follow some sort of -reference in the text of a buffer, if users usually would not want to -alter the text in that buffer by hand. Modes such as Dired, Info, -Compilation, and Occur redefine it in this way. - -@item -When a package provides a modification of ordinary Emacs behavior, it is -good to include a command to enable and disable the feature, Provide a -command named @code{@var{whatever}-mode} which turns the feature on or -off, and make it autoload (@pxref{Autoload}). Design the package so -that simply loading it has no visible effect---that should not enable -the feature. Users will request the feature by invoking the command. - -@item -It is a bad idea to define aliases for the Emacs primitives. Use the -standard names instead. - -@item -Redefining an Emacs primitive is an even worse idea. -It may do the right thing for a particular program, but -there is no telling what other programs might break as a result. - -@item -If a file does replace any of the functions or library programs of -standard Emacs, prominent comments at the beginning of the file should -say which functions are replaced, and how the behavior of the -replacements differs from that of the originals. - -@item -Please keep the names of your Emacs Lisp source files to 13 characters -or less. This way, if the files are compiled, the compiled files' names -will be 14 characters or less, which is short enough to fit on all kinds -of Unix systems. - -@item -Don't use @code{next-line} or @code{previous-line} in programs; nearly -always, @code{forward-line} is more convenient as well as more -predictable and robust. @xref{Text Lines}. - -@item -Don't call functions that set the mark, unless setting the mark is one -of the intended features of your program. The mark is a user-level -feature, so it is incorrect to change the mark except to supply a value -for the user's benefit. @xref{The Mark}. - -In particular, don't use these functions: - -@itemize @bullet -@item -@code{beginning-of-buffer}, @code{end-of-buffer} -@item -@code{replace-string}, @code{replace-regexp} -@end itemize - -If you just want to move point, or replace a certain string, without any -of the other features intended for interactive users, you can replace -these functions with one or two lines of simple Lisp code. - -@item -Use lists rather than vectors, except when there is a particular reason -to use a vector. Lisp has more facilities for manipulating lists than -for vectors, and working with lists is usually more convenient. - -Vectors are advantageous for tables that are substantial in size and are -accessed in random order (not searched front to back), provided there is -no need to insert or delete elements (only lists allow that). - -@item -The recommended way to print a message in the echo area is with -the @code{message} function, not @code{princ}. @xref{The Echo Area}. - -@item -When you encounter an error condition, call the function @code{error} -(or @code{signal}). The function @code{error} does not return. -@xref{Signaling Errors}. - -Do not use @code{message}, @code{throw}, @code{sleep-for}, -or @code{beep} to report errors. - -@item -An error message should start with a capital letter but should not end -with a period. - -@item -Many commands that take a long time to execute display a message that -says @samp{Operating...} when they start, and change it to -@samp{Operating...done} when they finish. Please keep the style of -these messages uniform: @emph{no} space around the ellipsis, and -@emph{no} period at the end. - -@item -Try to avoid using recursive edits. Instead, do what the Rmail @kbd{e} -command does: use a new local keymap that contains one command defined -to switch back to the old local keymap. Or do what the -@code{edit-options} command does: switch to another buffer and let the -user switch back at will. @xref{Recursive Editing}. - -@item -In some other systems there is a convention of choosing variable names -that begin and end with @samp{*}. We don't use that convention in Emacs -Lisp, so please don't use it in your programs. (Emacs uses such names -only for program-generated buffers.) The users will find Emacs more -coherent if all libraries use the same conventions. - -@item -Try to avoid compiler warnings about undefined free variables, by adding -@code{defvar} definitions for these variables. - -If you bind a variable in one function, and use it or set it in another -function, the compiler warns about the latter function unless the -variable has a definition. But often these variables have short names, -and it is not clean for Lisp packages to define such variables names. -Therefore, you should rename the variable to start with the name prefix -used for the other functions and variables in your package. - -@item -Indent each function with @kbd{C-M-q} (@code{indent-sexp}) using the -default indentation parameters. - -@item -Don't make a habit of putting close-parentheses on lines by themselves; -Lisp programmers find this disconcerting. Once in a while, when there -is a sequence of many consecutive close-parentheses, it may make sense -to split them in one or two significant places. - -@item -Please put a copyright notice on the file if you give copies to anyone. -Use the same lines that appear at the top of the Lisp files in Emacs -itself. If you have not signed papers to assign the copyright to the -Foundation, then place your name in the copyright notice in place of the -Foundation's name. -@end itemize - -@node Compilation Tips -@section Tips for Making Compiled Code Fast -@cindex execution speed -@cindex speedups - - Here are ways of improving the execution speed of byte-compiled -Lisp programs. - -@itemize @bullet -@item -@cindex profiling -@cindex timing programs -@cindex @file{profile.el} -Use the @file{profile} library to profile your program. See the file -@file{profile.el} for instructions. - -@item -Use iteration rather than recursion whenever possible. -Function calls are slow in Emacs Lisp even when a compiled function -is calling another compiled function. - -@item -Using the primitive list-searching functions @code{memq}, @code{member}, -@code{assq}, or @code{assoc} is even faster than explicit iteration. It -may be worth rearranging a data structure so that one of these primitive -search functions can be used. - -@item -Certain built-in functions are handled specially in byte-compiled code, -avoiding the need for an ordinary function call. It is a good idea to -use these functions rather than alternatives. To see whether a function -is handled specially by the compiler, examine its @code{byte-compile} -property. If the property is non-@code{nil}, then the function is -handled specially. - -For example, the following input will show you that @code{aref} is -compiled specially (@pxref{Array Functions}) while @code{elt} is not -(@pxref{Sequence Functions}): - -@example -@group -(get 'aref 'byte-compile) - @result{} byte-compile-two-args -@end group - -@group -(get 'elt 'byte-compile) - @result{} nil -@end group -@end example - -@item -If calling a small function accounts for a substantial part of your -program's running time, make the function inline. This eliminates -the function call overhead. Since making a function inline reduces -the flexibility of changing the program, don't do it unless it gives -a noticeable speedup in something slow enough that users care about -the speed. @xref{Inline Functions}. -@end itemize - -@node Documentation Tips -@section Tips for Documentation Strings - - Here are some tips for the writing of documentation strings. - -@itemize @bullet -@item -Every command, function, or variable intended for users to know about -should have a documentation string. - -@item -An internal variable or subroutine of a Lisp program might as well have -a documentation string. In earlier Emacs versions, you could save space -by using a comment instead of a documentation string, but that is no -longer the case. - -@item -The first line of the documentation string should consist of one or two -complete sentences that stand on their own as a summary. @kbd{M-x -apropos} displays just the first line, and if it doesn't stand on its -own, the result looks bad. In particular, start the first line with a -capital letter and end with a period. - -The documentation string can have additional lines that expand on the -details of how to use the function or variable. The additional lines -should be made up of complete sentences also, but they may be filled if -that looks good. - -@item -For consistency, phrase the verb in the first sentence of a -documentation string as an infinitive with ``to'' omitted. For -instance, use ``Return the cons of A and B.'' in preference to ``Returns -the cons of A and B@.'' Usually it looks good to do likewise for the -rest of the first paragraph. Subsequent paragraphs usually look better -if they have proper subjects. - -@item -Write documentation strings in the active voice, not the passive, and in -the present tense, not the future. For instance, use ``Return a list -containing A and B.'' instead of ``A list containing A and B will be -returned.'' - -@item -Avoid using the word ``cause'' (or its equivalents) unnecessarily. -Instead of, ``Cause Emacs to display text in boldface,'' write just -``Display text in boldface.'' - -@item -Do not start or end a documentation string with whitespace. - -@item -Format the documentation string so that it fits in an Emacs window on an -80-column screen. It is a good idea for most lines to be no wider than -60 characters. The first line can be wider if necessary to fit the -information that ought to be there. - -However, rather than simply filling the entire documentation string, you -can make it much more readable by choosing line breaks with care. -Use blank lines between topics if the documentation string is long. - -@item -@strong{Do not} indent subsequent lines of a documentation string so -that the text is lined up in the source code with the text of the first -line. This looks nice in the source code, but looks bizarre when users -view the documentation. Remember that the indentation before the -starting double-quote is not part of the string! - -@item -When the user tries to use a disabled command, Emacs displays just the -first paragraph of its documentation string---everything through the -first blank line. If you wish, you can choose which information to -include before the first blank line so as to make this display useful. - -@item -A variable's documentation string should start with @samp{*} if the -variable is one that users would often want to set interactively. If -the value is a long list, or a function, or if the variable would be set -only in init files, then don't start the documentation string with -@samp{*}. @xref{Defining Variables}. - -@item -The documentation string for a variable that is a yes-or-no flag should -start with words such as ``Non-nil means@dots{}'', to make it clear that -all non-@code{nil} values are equivalent and indicate explicitly what -@code{nil} and non-@code{nil} mean. - -@item -When a function's documentation string mentions the value of an argument -of the function, use the argument name in capital letters as if it were -a name for that value. Thus, the documentation string of the function -@code{/} refers to its second argument as @samp{DIVISOR}, because the -actual argument name is @code{divisor}. - -Also use all caps for meta-syntactic variables, such as when you show -the decomposition of a list or vector into subunits, some of which may -vary. - -@item -@iftex -When a documentation string refers to a Lisp symbol, write it as it -would be printed (which usually means in lower case), with single-quotes -around it. For example: @samp{`lambda'}. There are two exceptions: -write @code{t} and @code{nil} without single-quotes. -@end iftex -@ifinfo -When a documentation string refers to a Lisp symbol, write it as it -would be printed (which usually means in lower case), with single-quotes -around it. For example: @samp{lambda}. There are two exceptions: write -t and nil without single-quotes. (In this manual, we normally do use -single-quotes for those symbols.) -@end ifinfo - -@item -Don't write key sequences directly in documentation strings. Instead, -use the @samp{\\[@dots{}]} construct to stand for them. For example, -instead of writing @samp{C-f}, write the construct -@samp{\\[forward-char]}. When Emacs displays the documentation string, -it substitutes whatever key is currently bound to @code{forward-char}. -(This is normally @samp{C-f}, but it may be some other character if the -user has moved key bindings.) @xref{Keys in Documentation}. - -@item -In documentation strings for a major mode, you will want to refer to the -key bindings of that mode's local map, rather than global ones. -Therefore, use the construct @samp{\\<@dots{}>} once in the -documentation string to specify which key map to use. Do this before -the first use of @samp{\\[@dots{}]}. The text inside the -@samp{\\<@dots{}>} should be the name of the variable containing the -local keymap for the major mode. - -It is not practical to use @samp{\\[@dots{}]} very many times, because -display of the documentation string will become slow. So use this to -describe the most important commands in your major mode, and then use -@samp{\\@{@dots{}@}} to display the rest of the mode's keymap. -@end itemize - -@node Comment Tips -@section Tips on Writing Comments - - We recommend these conventions for where to put comments and how to -indent them: - -@table @samp -@item ; -Comments that start with a single semicolon, @samp{;}, should all be -aligned to the same column on the right of the source code. Such -comments usually explain how the code on the same line does its job. In -Lisp mode and related modes, the @kbd{M-;} (@code{indent-for-comment}) -command automatically inserts such a @samp{;} in the right place, or -aligns such a comment if it is already present. - -This and following examples are taken from the Emacs sources. - -@smallexample -@group -(setq base-version-list ; there was a base - (assoc (substring fn 0 start-vn) ; version to which - file-version-assoc-list)) ; this looks like - ; a subversion -@end group -@end smallexample - -@item ;; -Comments that start with two semicolons, @samp{;;}, should be aligned to -the same level of indentation as the code. Such comments usually -describe the purpose of the following lines or the state of the program -at that point. For example: - -@smallexample -@group -(prog1 (setq auto-fill-function - @dots{} - @dots{} - ;; update mode line - (force-mode-line-update))) -@end group -@end smallexample - -Every function that has no documentation string (because it is use only -internally within the package it belongs to), should have instead a -two-semicolon comment right before the function, explaining what the -function does and how to call it properly. Explain precisely what each -argument means and how the function interprets its possible values. - -@item ;;; -Comments that start with three semicolons, @samp{;;;}, should start at -the left margin. Such comments are used outside function definitions to -make general statements explaining the design principles of the program. -For example: - -@smallexample -@group -;;; This Lisp code is run in Emacs -;;; when it is to operate as a server -;;; for other processes. -@end group -@end smallexample - -Another use for triple-semicolon comments is for commenting out lines -within a function. We use triple-semicolons for this precisely so that -they remain at the left margin. - -@smallexample -(defun foo (a) -;;; This is no longer necessary. -;;; (force-mode-line-update) - (message "Finished with %s" a)) -@end smallexample - -@item ;;;; -Comments that start with four semicolons, @samp{;;;;}, should be aligned -to the left margin and are used for headings of major sections of a -program. For example: - -@smallexample -;;;; The kill ring -@end smallexample -@end table - -@noindent -The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;} -(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}) -automatically indent comments according to these conventions, -depending on the number of semicolons. @xref{Comments,, -Manipulating Comments, emacs, The GNU Emacs Manual}. - -@node Library Headers -@section Conventional Headers for Emacs Libraries -@cindex header comments -@cindex library header comments - - Emacs 19 has conventions for using special comments in Lisp libraries -to divide them into sections and give information such as who wrote -them. This section explains these conventions. First, an example: - -@smallexample -@group -;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers - -;; Copyright (C) 1992 Free Software Foundation, Inc. -@end group - -;; Author: Eric S. Raymond <esr@@snark.thyrsus.com> -;; Maintainer: Eric S. Raymond <esr@@snark.thyrsus.com> -;; Created: 14 Jul 1992 -;; Version: 1.2 -@group -;; Keywords: docs - -;; This file is part of GNU Emacs. -@var{copying permissions}@dots{} -@end group -@end smallexample - - The very first line should have this format: - -@example -;;; @var{filename} --- @var{description} -@end example - -@noindent -The description should be complete in one line. - - After the copyright notice come several @dfn{header comment} lines, -each beginning with @samp{;; @var{header-name}:}. Here is a table of -the conventional possibilities for @var{header-name}: - -@table @samp -@item Author -This line states the name and net address of at least the principal -author of the library. - -If there are multiple authors, you can list them on continuation lines -led by @code{;;} and a tab character, like this: - -@smallexample -@group -;; Author: Ashwin Ram <Ram-Ashwin@@cs.yale.edu> -;; Dave Sill <de5@@ornl.gov> -;; Dave Brennan <brennan@@hal.com> -;; Eric Raymond <esr@@snark.thyrsus.com> -@end group -@end smallexample - -@item Maintainer -This line should contain a single name/address as in the Author line, or -an address only, or the string @samp{FSF}. If there is no maintainer -line, the person(s) in the Author field are presumed to be the -maintainers. The example above is mildly bogus because the maintainer -line is redundant. - -The idea behind the @samp{Author} and @samp{Maintainer} lines is to make -possible a Lisp function to ``send mail to the maintainer'' without -having to mine the name out by hand. - -Be sure to surround the network address with @samp{<@dots{}>} if -you include the person's full name as well as the network address. - -@item Created -This optional line gives the original creation date of the -file. For historical interest only. - -@item Version -If you wish to record version numbers for the individual Lisp program, put -them in this line. - -@item Adapted-By -In this header line, place the name of the person who adapted the -library for installation (to make it fit the style conventions, for -example). - -@item Keywords -This line lists keywords for the @code{finder-by-keyword} help command. -This field is important; it's how people will find your package when -they're looking for things by topic area. To separate the keywords, you -can use spaces, commas, or both. -@end table - - Just about every Lisp library ought to have the @samp{Author} and -@samp{Keywords} header comment lines. Use the others if they are -appropriate. You can also put in header lines with other header -names---they have no standard meanings, so they can't do any harm. - - We use additional stylized comments to subdivide the contents of the -library file. Here is a table of them: - -@table @samp -@item ;;; Commentary: -This begins introductory comments that explain how the library works. -It should come right after the copying permissions. - -@item ;;; Change log: -This begins change log information stored in the library file (if you -store the change history there). For most of the Lisp -files distributed with Emacs, the change history is kept in the file -@file{ChangeLog} and not in the source file at all; these files do -not have a @samp{;;; Change log:} line. - -@item ;;; Code: -This begins the actual code of the program. - -@item ;;; @var{filename} ends here -This is the @dfn{footer line}; it appears at the very end of the file. -Its purpose is to enable people to detect truncated versions of the file -from the lack of a footer line. -@end table diff --git a/lispref/variables.texi b/lispref/variables.texi deleted file mode 100644 index 22813ea5b63..00000000000 --- a/lispref/variables.texi +++ /dev/null @@ -1,1427 +0,0 @@ -@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/variables -@node Variables, Functions, Control Structures, Top -@chapter Variables -@cindex variable - - A @dfn{variable} is a name used in a program to stand for a value. -Nearly all programming languages have variables of some sort. In the -text of a Lisp program, variables are written using the syntax for -symbols. - - In Lisp, unlike most programming languages, programs are represented -primarily as Lisp objects and only secondarily as text. The Lisp -objects used for variables are symbols: the symbol name is the variable -name, and the variable's value is stored in the value cell of the -symbol. The use of a symbol as a variable is independent of its use as -a function name. @xref{Symbol Components}. - - The Lisp objects that constitute a Lisp program determine the textual -form of the program---it is simply the read syntax for those Lisp -objects. This is why, for example, a variable in a textual Lisp program -is written using the read syntax for the symbol that represents the -variable. - -@menu -* Global Variables:: Variable values that exist permanently, everywhere. -* Constant Variables:: Certain "variables" have values that never change. -* Local Variables:: Variable values that exist only temporarily. -* Void Variables:: Symbols that lack values. -* Defining Variables:: A definition says a symbol is used as a variable. -* Tips for Defining:: How to avoid bad results from quitting - within the code to initialize a variable. -* Accessing Variables:: Examining values of variables whose names - are known only at run time. -* Setting Variables:: Storing new values in variables. -* Variable Scoping:: How Lisp chooses among local and global values. -* Buffer-Local Variables:: Variable values in effect only in one buffer. -@end menu - -@node Global Variables -@section Global Variables -@cindex global variable - - The simplest way to use a variable is @dfn{globally}. This means that -the variable has just one value at a time, and this value is in effect -(at least for the moment) throughout the Lisp system. The value remains -in effect until you specify a new one. When a new value replaces the -old one, no trace of the old value remains in the variable. - - You specify a value for a symbol with @code{setq}. For example, - -@example -(setq x '(a b)) -@end example - -@noindent -gives the variable @code{x} the value @code{(a b)}. Note that -@code{setq} does not evaluate its first argument, the name of the -variable, but it does evaluate the second argument, the new value. - - Once the variable has a value, you can refer to it by using the symbol -by itself as an expression. Thus, - -@example -@group -x @result{} (a b) -@end group -@end example - -@noindent -assuming the @code{setq} form shown above has already been executed. - - If you do another @code{setq}, the new value replaces the old one: - -@example -@group -x - @result{} (a b) -@end group -@group -(setq x 4) - @result{} 4 -@end group -@group -x - @result{} 4 -@end group -@end example - -@node Constant Variables -@section Variables That Never Change -@vindex nil -@vindex t -@kindex setting-constant - - Emacs Lisp has two special symbols, @code{nil} and @code{t}, that -always evaluate to themselves. These symbols cannot be rebound, nor can -their value cells be changed. An attempt to change the value of -@code{nil} or @code{t} signals a @code{setting-constant} error. - -@example -@group -nil @equiv{} 'nil - @result{} nil -@end group -@group -(setq nil 500) -@error{} Attempt to set constant symbol: nil -@end group -@end example - -@node Local Variables -@section Local Variables -@cindex binding local variables -@cindex local variables -@cindex local binding -@cindex global binding - - Global variables have values that last until explicitly superseded -with new values. Sometimes it is useful to create variable values that -exist temporarily---only while within a certain part of the program. -These values are called @dfn{local}, and the variables so used are -called @dfn{local variables}. - - For example, when a function is called, its argument variables receive -new local values that last until the function exits. The @code{let} -special form explicitly establishes new local values for specified -variables; these last until exit from the @code{let} form. - -@cindex shadowing of variables - Establishing a local value saves away the previous value (or lack of -one) of the variable. When the life span of the local value is over, -the previous value is restored. In the mean time, we say that the -previous value is @dfn{shadowed} and @dfn{not visible}. Both global and -local values may be shadowed (@pxref{Scope}). - - If you set a variable (such as with @code{setq}) while it is local, -this replaces the local value; it does not alter the global value, or -previous local values that are shadowed. To model this behavior, we -speak of a @dfn{local binding} of the variable as well as a local value. - - The local binding is a conceptual place that holds a local value. -Entry to a function, or a special form such as @code{let}, creates the -local binding; exit from the function or from the @code{let} removes the -local binding. As long as the local binding lasts, the variable's value -is stored within it. Use of @code{setq} or @code{set} while there is a -local binding stores a different value into the local binding; it does -not create a new binding. - - We also speak of the @dfn{global binding}, which is where -(conceptually) the global value is kept. - -@cindex current binding - A variable can have more than one local binding at a time (for -example, if there are nested @code{let} forms that bind it). In such a -case, the most recently created local binding that still exists is the -@dfn{current binding} of the variable. (This is called @dfn{dynamic -scoping}; see @ref{Variable Scoping}.) If there are no local bindings, -the variable's global binding is its current binding. We also call the -current binding the @dfn{most-local existing binding}, for emphasis. -Ordinary evaluation of a symbol always returns the value of its current -binding. - - The special forms @code{let} and @code{let*} exist to create -local bindings. - -@defspec let (bindings@dots{}) forms@dots{} -This special form binds variables according to @var{bindings} and then -evaluates all of the @var{forms} in textual order. The @code{let}-form -returns the value of the last form in @var{forms}. - -Each of the @var{bindings} is either @w{(i) a} symbol, in which case -that symbol is bound to @code{nil}; or @w{(ii) a} list of the form -@code{(@var{symbol} @var{value-form})}, in which case @var{symbol} is -bound to the result of evaluating @var{value-form}. If @var{value-form} -is omitted, @code{nil} is used. - -All of the @var{value-form}s in @var{bindings} are evaluated in the -order they appear and @emph{before} any of the symbols are bound. Here -is an example of this: @code{Z} is bound to the old value of @code{Y}, -which is 2, not the new value, 1. - -@example -@group -(setq Y 2) - @result{} 2 -@end group -@group -(let ((Y 1) - (Z Y)) - (list Y Z)) - @result{} (1 2) -@end group -@end example -@end defspec - -@defspec let* (bindings@dots{}) forms@dots{} -This special form is like @code{let}, but it binds each variable right -after computing its local value, before computing the local value for -the next variable. Therefore, an expression in @var{bindings} can -reasonably refer to the preceding symbols bound in this @code{let*} -form. Compare the following example with the example above for -@code{let}. - -@example -@group -(setq Y 2) - @result{} 2 -@end group -@group -(let* ((Y 1) - (Z Y)) ; @r{Use the just-established value of @code{Y}.} - (list Y Z)) - @result{} (1 1) -@end group -@end example -@end defspec - - Here is a complete list of the other facilities that create local -bindings: - -@itemize @bullet -@item -Function calls (@pxref{Functions}). - -@item -Macro calls (@pxref{Macros}). - -@item -@code{condition-case} (@pxref{Errors}). -@end itemize - - Variables can also have buffer-local bindings (@pxref{Buffer-Local -Variables}); a few variables have terminal-local bindings -(@pxref{Multiple Displays}). These kinds of bindings work somewhat like -ordinary local bindings, but they are localized depending on ``where'' -you are in Emacs, rather than localized in time. - -@defvar max-specpdl-size -@cindex variable limit error -@cindex evaluation error -@cindex infinite recursion - This variable defines the limit on the total number of local variable -bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits}) -that are allowed before signaling an error (with data @code{"Variable -binding depth exceeds max-specpdl-size"}). - - This limit, with the associated error when it is exceeded, is one way -that Lisp avoids infinite recursion on an ill-defined function. - - The default value is 600. - - @code{max-lisp-eval-depth} provides another limit on depth of nesting. -@xref{Eval}. -@end defvar - -@node Void Variables -@section When a Variable is ``Void'' -@kindex void-variable -@cindex void variable - - If you have never given a symbol any value as a global variable, we -say that that symbol's global value is @dfn{void}. In other words, the -symbol's value cell does not have any Lisp object in it. If you try to -evaluate the symbol, you get a @code{void-variable} error rather than -a value. - - Note that a value of @code{nil} is not the same as void. The symbol -@code{nil} is a Lisp object and can be the value of a variable just as any -other object can be; but it is @emph{a value}. A void variable does not -have any value. - - After you have given a variable a value, you can make it void once more -using @code{makunbound}. - -@defun makunbound symbol -This function makes the current binding of @var{symbol} void. -Subsequent attempts to use this symbol's value as a variable will signal -the error @code{void-variable}, unless or until you set it again. - -@code{makunbound} returns @var{symbol}. - -@example -@group -(makunbound 'x) ; @r{Make the global value} - ; @r{of @code{x} void.} - @result{} x -@end group -@group -x -@error{} Symbol's value as variable is void: x -@end group -@end example - -If @var{symbol} is locally bound, @code{makunbound} affects the most -local existing binding. This is the only way a symbol can have a void -local binding, since all the constructs that create local bindings -create them with values. In this case, the voidness lasts at most as -long as the binding does; when the binding is removed due to exit from -the construct that made it, the previous or global binding is reexposed -as usual, and the variable is no longer void unless the newly reexposed -binding was void all along. - -@smallexample -@group -(setq x 1) ; @r{Put a value in the global binding.} - @result{} 1 -(let ((x 2)) ; @r{Locally bind it.} - (makunbound 'x) ; @r{Void the local binding.} - x) -@error{} Symbol's value as variable is void: x -@end group -@group -x ; @r{The global binding is unchanged.} - @result{} 1 - -(let ((x 2)) ; @r{Locally bind it.} - (let ((x 3)) ; @r{And again.} - (makunbound 'x) ; @r{Void the innermost-local binding.} - x)) ; @r{And refer: it's void.} -@error{} Symbol's value as variable is void: x -@end group - -@group -(let ((x 2)) - (let ((x 3)) - (makunbound 'x)) ; @r{Void inner binding, then remove it.} - x) ; @r{Now outer @code{let} binding is visible.} - @result{} 2 -@end group -@end smallexample -@end defun - - A variable that has been made void with @code{makunbound} is -indistinguishable from one that has never received a value and has -always been void. - - You can use the function @code{boundp} to test whether a variable is -currently void. - -@defun boundp variable -@code{boundp} returns @code{t} if @var{variable} (a symbol) is not void; -more precisely, if its current binding is not void. It returns -@code{nil} otherwise. - -@smallexample -@group -(boundp 'abracadabra) ; @r{Starts out void.} - @result{} nil -@end group -@group -(let ((abracadabra 5)) ; @r{Locally bind it.} - (boundp 'abracadabra)) - @result{} t -@end group -@group -(boundp 'abracadabra) ; @r{Still globally void.} - @result{} nil -@end group -@group -(setq abracadabra 5) ; @r{Make it globally nonvoid.} - @result{} 5 -@end group -@group -(boundp 'abracadabra) - @result{} t -@end group -@end smallexample -@end defun - -@node Defining Variables -@section Defining Global Variables -@cindex variable definition - - You may announce your intention to use a symbol as a global variable -with a @dfn{variable definition}: a special form, either @code{defconst} -or @code{defvar}. - - In Emacs Lisp, definitions serve three purposes. First, they inform -people who read the code that certain symbols are @emph{intended} to be -used a certain way (as variables). Second, they inform the Lisp system -of these things, supplying a value and documentation. Third, they -provide information to utilities such as @code{etags} and -@code{make-docfile}, which create data bases of the functions and -variables in a program. - - The difference between @code{defconst} and @code{defvar} is primarily -a matter of intent, serving to inform human readers of whether programs -will change the variable. Emacs Lisp does not restrict the ways in -which a variable can be used based on @code{defconst} or @code{defvar} -declarations. However, it does make a difference for initialization: -@code{defconst} unconditionally initializes the variable, while -@code{defvar} initializes it only if it is void. - - One would expect user option variables to be defined with -@code{defconst}, since programs do not change them. Unfortunately, this -has bad results if the definition is in a library that is not preloaded: -@code{defconst} would override any prior value when the library is -loaded. Users would like to be able to set user options in their init -files, and override the default values given in the definitions. For -this reason, user options must be defined with @code{defvar}. - -@defspec defvar symbol [value [doc-string]] -This special form defines @var{symbol} as a value and initializes it. -The definition informs a person reading your code that @var{symbol} is -used as a variable that programs are likely to set or change. It is -also used for all user option variables except in the preloaded parts of -Emacs. Note that @var{symbol} is not evaluated; the symbol to be -defined must appear explicitly in the @code{defvar}. - -If @var{symbol} already has a value (i.e., it is not void), @var{value} -is not even evaluated, and @var{symbol}'s value remains unchanged. If -@var{symbol} is void and @var{value} is specified, @code{defvar} -evaluates it and sets @var{symbol} to the result. (If @var{value} is -omitted, the value of @var{symbol} is not changed in any case.) - -When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in -Emacs Lisp mode (@code{eval-defun}), a special feature of -@code{eval-defun} evaluates it as a @code{defconst}. The purpose of -this is to make sure the variable's value is reinitialized, when you ask -for it specifically. - -If @var{symbol} has a buffer-local binding in the current buffer, -@code{defvar} sets the default value, not the local value. -@xref{Buffer-Local Variables}. - -If the @var{doc-string} argument appears, it specifies the documentation -for the variable. (This opportunity to specify documentation is one of -the main benefits of defining the variable.) The documentation is -stored in the symbol's @code{variable-documentation} property. The -Emacs help functions (@pxref{Documentation}) look for this property. - -If the first character of @var{doc-string} is @samp{*}, it means that -this variable is considered a user option. This lets users set the -variable conventiently using the commands @code{set-variable} and -@code{edit-options}. - -For example, this form defines @code{foo} but does not set its value: - -@example -@group -(defvar foo) - @result{} foo -@end group -@end example - -The following example sets the value of @code{bar} to @code{23}, and -gives it a documentation string: - -@example -@group -(defvar bar 23 - "The normal weight of a bar.") - @result{} bar -@end group -@end example - -The following form changes the documentation string for @code{bar}, -making it a user option, but does not change the value, since @code{bar} -already has a value. (The addition @code{(1+ 23)} is not even -performed.) - -@example -@group -(defvar bar (1+ 23) - "*The normal weight of a bar.") - @result{} bar -@end group -@group -bar - @result{} 23 -@end group -@end example - -Here is an equivalent expression for the @code{defvar} special form: - -@example -@group -(defvar @var{symbol} @var{value} @var{doc-string}) -@equiv{} -(progn - (if (not (boundp '@var{symbol})) - (setq @var{symbol} @var{value})) - (if '@var{doc-string} - (put '@var{symbol} 'variable-documentation '@var{doc-string})) - '@var{symbol}) -@end group -@end example - -The @code{defvar} form returns @var{symbol}, but it is normally used -at top level in a file where its value does not matter. -@end defspec - -@defspec defconst symbol [value [doc-string]] -This special form defines @var{symbol} as a value and initializes it. -It informs a person reading your code that @var{symbol} has a global -value, established here, that will not normally be changed or locally -bound by the execution of the program. The user, however, may be -welcome to change it. Note that @var{symbol} is not evaluated; the -symbol to be defined must appear explicitly in the @code{defconst}. - -@code{defconst} always evaluates @var{value} and sets the global value -of @var{symbol} to the result, provided @var{value} is given. If -@var{symbol} has a buffer-local binding in the current buffer, -@code{defconst} sets the default value, not the local value. - -@strong{Please note:} Don't use @code{defconst} for user option -variables in libraries that are not standardly preloaded. The user -should be able to specify a value for such a variable in the -@file{.emacs} file, so that it will be in effect if and when the library -is loaded later. - -Here, @code{pi} is a constant that presumably ought not to be changed -by anyone (attempts by the Indiana State Legislature notwithstanding). -As the second form illustrates, however, this is only advisory. - -@example -@group -(defconst pi 3.1415 "Pi to five places.") - @result{} pi -@end group -@group -(setq pi 3) - @result{} pi -@end group -@group -pi - @result{} 3 -@end group -@end example -@end defspec - -@defun user-variable-p variable -@cindex user option -This function returns @code{t} if @var{variable} is a user option---a -variable intended to be set by the user for customization---and -@code{nil} otherwise. (Variables other than user options exist for the -internal purposes of Lisp programs, and users need not know about them.) - -User option variables are distinguished from other variables by the -first character of the @code{variable-documentation} property. If the -property exists and is a string, and its first character is @samp{*}, -then the variable is a user option. -@end defun - -@kindex variable-interactive - If a user option variable has a @code{variable-interactive} property, -the @code{set-variable} command uses that value to control reading the -new value for the variable. The property's value is used as if it were -to @code{interactive} (@pxref{Using Interactive}). - - @strong{Warning:} If the @code{defconst} and @code{defvar} special -forms are used while the variable has a local binding, they set the -local binding's value; the global binding is not changed. This is not -what we really want. To prevent it, use these special forms at top -level in a file, where normally no local binding is in effect, and make -sure to load the file before making a local binding for the variable. - -@node Tips for Defining -@section Tips for Defining Variables Robustly - - When defining and initializing a variable that holds a complicated -value (such as a keymap with bindings in it), it's best to put the -entire computation of the value into the @code{defvar}, like this: - -@example -(defvar my-mode-map - (let ((map (make-sparse-keymap))) - (define-key my-mode-map "\C-c\C-a" 'my-command) - @dots{} - map) - @var{docstring}) -@end example - -@noindent -This method has several benefits. First, if the user quits while -loading the file, the variable is either still uninitialized or -initialized properly, never in-between. If it is uninitialized, -reloading the file will initialize it properly. Second, reloading the -file once the variable is initialized will not alter it; that is -important if the user has run hooks to alter part of the contents (such -as, to rebind keys). Third, evaluating the @code{defvar} form with -@kbd{C-M-x} @emph{will} reinitialize the map completely. - - Putting so much code in the @code{defvar} form has one disadvantage: -it puts the documentation string far away from the line which names the -variable. Here's a safe way to avoid that: - -@example -(defvar my-mode-map nil - @var{docstring}) -(if my-mode-map - nil - (let ((map (make-sparse-keymap))) - (define-key my-mode-map "\C-c\C-a" 'my-command) - @dots{} - (setq my-mode-map map))) -@end example - -@noindent -This has all the same advantages as putting the initialization inside -the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on -each form, if you do want to reinitialize the variable. - - But be careful not to write the code like this: - -@example -(defvar my-mode-map nil - @var{docstring}) -(if my-mode-map - nil - (setq my-mode-map (make-sparse-keymap)) - (define-key my-mode-map "\C-c\C-a" 'my-command) - @dots{}) -@end example - -@noindent -This code sets the variable, then alters it, but only if the variable -had been @code{ni}. If the user quits just after the @code{setq}, that -leaves the variable neither correctly initialized nor void nor -@code{nil}. Once that happens, reloading the file will not initialize -the variable; it will remain incomplete. - -@node Accessing Variables -@section Accessing Variable Values - - The usual way to reference a variable is to write the symbol which -names it (@pxref{Symbol Forms}). This requires you to specify the -variable name when you write the program. Usually that is exactly what -you want to do. Occasionally you need to choose at run time which -variable to reference; then you can use @code{symbol-value}. - -@defun symbol-value symbol -This function returns the value of @var{symbol}. This is the value in -the innermost local binding of the symbol, or its global value if it -has no local bindings. - -@example -@group -(setq abracadabra 5) - @result{} 5 -@end group -@group -(setq foo 9) - @result{} 9 -@end group - -@group -;; @r{Here the symbol @code{abracadabra}} -;; @r{is the symbol whose value is examined.} -(let ((abracadabra 'foo)) - (symbol-value 'abracadabra)) - @result{} foo -@end group - -@group -;; @r{Here the value of @code{abracadabra},} -;; @r{which is @code{foo},} -;; @r{is the symbol whose value is examined.} -(let ((abracadabra 'foo)) - (symbol-value abracadabra)) - @result{} 9 -@end group - -@group -(symbol-value 'abracadabra) - @result{} 5 -@end group -@end example - -A @code{void-variable} error is signaled if @var{symbol} has neither a -local binding nor a global value. -@end defun - -@node Setting Variables -@section How to Alter a Variable Value - - The usual way to change the value of a variable is with the special -form @code{setq}. When you need to compute the choice of variable at -run time, use the function @code{set}. - -@defspec setq [symbol form]@dots{} -This special form is the most common method of changing a variable's -value. Each @var{symbol} is given a new value, which is the result of -evaluating the corresponding @var{form}. The most-local existing -binding of the symbol is changed. - -@code{setq} does not evaluate @var{symbol}; it sets the symbol that you -write. We say that this argument is @dfn{automatically quoted}. The -@samp{q} in @code{setq} stands for ``quoted.'' - -The value of the @code{setq} form is the value of the last @var{form}. - -@example -@group -(setq x (1+ 2)) - @result{} 3 -@end group -x ; @r{@code{x} now has a global value.} - @result{} 3 -@group -(let ((x 5)) - (setq x 6) ; @r{The local binding of @code{x} is set.} - x) - @result{} 6 -@end group -x ; @r{The global value is unchanged.} - @result{} 3 -@end example - -Note that the first @var{form} is evaluated, then the first -@var{symbol} is set, then the second @var{form} is evaluated, then the -second @var{symbol} is set, and so on: - -@example -@group -(setq x 10 ; @r{Notice that @code{x} is set before} - y (1+ x)) ; @r{the value of @code{y} is computed.} - @result{} 11 -@end group -@end example -@end defspec - -@defun set symbol value -This function sets @var{symbol}'s value to @var{value}, then returns -@var{value}. Since @code{set} is a function, the expression written for -@var{symbol} is evaluated to obtain the symbol to set. - -The most-local existing binding of the variable is the binding that is -set; shadowed bindings are not affected. - -@example -@group -(set one 1) -@error{} Symbol's value as variable is void: one -@end group -@group -(set 'one 1) - @result{} 1 -@end group -@group -(set 'two 'one) - @result{} one -@end group -@group -(set two 2) ; @r{@code{two} evaluates to symbol @code{one}.} - @result{} 2 -@end group -@group -one ; @r{So it is @code{one} that was set.} - @result{} 2 -(let ((one 1)) ; @r{This binding of @code{one} is set,} - (set 'one 3) ; @r{not the global value.} - one) - @result{} 3 -@end group -@group -one - @result{} 2 -@end group -@end example - -If @var{symbol} is not actually a symbol, a @code{wrong-type-argument} -error is signaled. - -@example -(set '(x y) 'z) -@error{} Wrong type argument: symbolp, (x y) -@end example - -Logically speaking, @code{set} is a more fundamental primitive than -@code{setq}. Any use of @code{setq} can be trivially rewritten to use -@code{set}; @code{setq} could even be defined as a macro, given the -availability of @code{set}. However, @code{set} itself is rarely used; -beginners hardly need to know about it. It is useful only for choosing -at run time which variable to set. For example, the command -@code{set-variable}, which reads a variable name from the user and then -sets the variable, needs to use @code{set}. - -@cindex CL note---@code{set} local -@quotation -@b{Common Lisp note:} In Common Lisp, @code{set} always changes the -symbol's special value, ignoring any lexical bindings. In Emacs Lisp, -all variables and all bindings are (in effect) special, so @code{set} -always affects the most local existing binding. -@end quotation -@end defun - - One other function for setting a variable is designed to add -an element to a list if it is not already present in the list. - -@defun add-to-list symbol element -This function sets the variable @var{symbol} by consing @var{element} -onto the old value, if @var{element} is not already a member of that -value. It returns the resulting list, whether updated or not. The -value of @var{symbol} had better be a list already before the call. - -The argument @var{symbol} is not implicitly quoted; @code{add-to-list} -is an ordinary function, like @code{set} and unlike @code{setq}. Quote -the argument yourself if that is what you want. - -Here's a scenario showing how to use @code{add-to-list}: - -@example -(setq foo '(a b)) - @result{} (a b) - -(add-to-list 'foo 'c) ;; @r{Add @code{c}.} - @result{} (c a b) - -(add-to-list 'foo 'b) ;; @r{No effect.} - @result{} (c a b) - -foo ;; @r{@code{foo} was changed.} - @result{} (c a b) -@end example -@end defun - - An equivalent expression for @code{(add-to-list '@var{var} -@var{value})} is this: - -@example -(or (member @var{value} @var{var}) - (setq @var{var} (cons @var{value} @var{var}))) -@end example - -@node Variable Scoping -@section Scoping Rules for Variable Bindings - - A given symbol @code{foo} may have several local variable bindings, -established at different places in the Lisp program, as well as a global -binding. The most recently established binding takes precedence over -the others. - -@cindex scope -@cindex extent -@cindex dynamic scoping - Local bindings in Emacs Lisp have @dfn{indefinite scope} and -@dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in -the source code the binding can be accessed. Indefinite scope means -that any part of the program can potentially access the variable -binding. @dfn{Extent} refers to @emph{when}, as the program is -executing, the binding exists. Dynamic extent means that the binding -lasts as long as the activation of the construct that established it. - - The combination of dynamic extent and indefinite scope is called -@dfn{dynamic scoping}. By contrast, most programming languages use -@dfn{lexical scoping}, in which references to a local variable must be -located textually within the function or block that binds the variable. - -@cindex CL note---special variables -@quotation -@b{Common Lisp note:} Variables declared ``special'' in Common Lisp -are dynamically scoped, like variables in Emacs Lisp. -@end quotation - -@menu -* Scope:: Scope means where in the program a value is visible. - Comparison with other languages. -* Extent:: Extent means how long in time a value exists. -* Impl of Scope:: Two ways to implement dynamic scoping. -* Using Scoping:: How to use dynamic scoping carefully and avoid problems. -@end menu - -@node Scope -@subsection Scope - - Emacs Lisp uses @dfn{indefinite scope} for local variable bindings. -This means that any function anywhere in the program text might access a -given binding of a variable. Consider the following function -definitions: - -@example -@group -(defun binder (x) ; @r{@code{x} is bound in @code{binder}.} - (foo 5)) ; @r{@code{foo} is some other function.} -@end group - -@group -(defun user () ; @r{@code{x} is used in @code{user}.} - (list x)) -@end group -@end example - - In a lexically scoped language, the binding of @code{x} in -@code{binder} would never be accessible in @code{user}, because -@code{user} is not textually contained within the function -@code{binder}. However, in dynamically scoped Emacs Lisp, @code{user} -may or may not refer to the binding of @code{x} established in -@code{binder}, depending on circumstances: - -@itemize @bullet -@item -If we call @code{user} directly without calling @code{binder} at all, -then whatever binding of @code{x} is found, it cannot come from -@code{binder}. - -@item -If we define @code{foo} as follows and call @code{binder}, then the -binding made in @code{binder} will be seen in @code{user}: - -@example -@group -(defun foo (lose) - (user)) -@end group -@end example - -@item -If we define @code{foo} as follows and call @code{binder}, then the -binding made in @code{binder} @emph{will not} be seen in @code{user}: - -@example -(defun foo (x) - (user)) -@end example - -@noindent -Here, when @code{foo} is called by @code{binder}, it binds @code{x}. -(The binding in @code{foo} is said to @dfn{shadow} the one made in -@code{binder}.) Therefore, @code{user} will access the @code{x} bound -by @code{foo} instead of the one bound by @code{binder}. -@end itemize - -@node Extent -@subsection Extent - - @dfn{Extent} refers to the time during program execution that a -variable name is valid. In Emacs Lisp, a variable is valid only while -the form that bound it is executing. This is called @dfn{dynamic -extent}. ``Local'' or ``automatic'' variables in most languages, -including C and Pascal, have dynamic extent. - - One alternative to dynamic extent is @dfn{indefinite extent}. This -means that a variable binding can live on past the exit from the form -that made the binding. Common Lisp and Scheme, for example, support -this, but Emacs Lisp does not. - - To illustrate this, the function below, @code{make-add}, returns a -function that purports to add @var{n} to its own argument @var{m}. -This would work in Common Lisp, but it does not work as intended in -Emacs Lisp, because after the call to @code{make-add} exits, the -variable @code{n} is no longer bound to the actual argument 2. - -@example -(defun make-add (n) - (function (lambda (m) (+ n m)))) ; @r{Return a function.} - @result{} make-add -(fset 'add2 (make-add 2)) ; @r{Define function @code{add2}} - ; @r{with @code{(make-add 2)}.} - @result{} (lambda (m) (+ n m)) -(add2 4) ; @r{Try to add 2 to 4.} -@error{} Symbol's value as variable is void: n -@end example - -@cindex closures not available - Some Lisp dialects have ``closures'', objects that are like functions -but record additional variable bindings. Emacs Lisp does not have -closures. - -@node Impl of Scope -@subsection Implementation of Dynamic Scoping -@cindex deep binding - - A simple sample implementation (which is not how Emacs Lisp actually -works) may help you understand dynamic binding. This technique is -called @dfn{deep binding} and was used in early Lisp systems. - - Suppose there is a stack of bindings: variable-value pairs. At entry -to a function or to a @code{let} form, we can push bindings on the stack -for the arguments or local variables created there. We can pop those -bindings from the stack at exit from the binding construct. - - We can find the value of a variable by searching the stack from top to -bottom for a binding for that variable; the value from that binding is -the value of the variable. To set the variable, we search for the -current binding, then store the new value into that binding. - - As you can see, a function's bindings remain in effect as long as it -continues execution, even during its calls to other functions. That is -why we say the extent of the binding is dynamic. And any other function -can refer to the bindings, if it uses the same variables while the -bindings are in effect. That is why we say the scope is indefinite. - -@cindex shallow binding - The actual implementation of variable scoping in GNU Emacs Lisp uses a -technique called @dfn{shallow binding}. Each variable has a standard -place in which its current value is always found---the value cell of the -symbol. - - In shallow binding, setting the variable works by storing a value in -the value cell. Creating a new binding works by pushing the old value -(belonging to a previous binding) on a stack, and storing the local value -in the value cell. Eliminating a binding works by popping the old value -off the stack, into the value cell. - - We use shallow binding because it has the same results as deep -binding, but runs faster, since there is never a need to search for a -binding. - -@node Using Scoping -@subsection Proper Use of Dynamic Scoping - - Binding a variable in one function and using it in another is a -powerful technique, but if used without restraint, it can make programs -hard to understand. There are two clean ways to use this technique: - -@itemize @bullet -@item -Use or bind the variable only in a few related functions, written close -together in one file. Such a variable is used for communication within -one program. - -You should write comments to inform other programmers that they can see -all uses of the variable before them, and to advise them not to add uses -elsewhere. - -@item -Give the variable a well-defined, documented meaning, and make all -appropriate functions refer to it (but not bind it or set it) wherever -that meaning is relevant. For example, the variable -@code{case-fold-search} is defined as ``non-@code{nil} means ignore case -when searching''; various search and replace functions refer to it -directly or through their subroutines, but do not bind or set it. - -Then you can bind the variable in other programs, knowing reliably what -the effect will be. -@end itemize - - In either case, you should define the variable with @code{defvar}. -This helps other people understand your program by telling them to look -for inter-function usage. It also avoids a warning from the byte -compiler. Choose the variable's name to avoid name conflicts---don't -use short names like @code{x}. - -@node Buffer-Local Variables -@section Buffer-Local Variables -@cindex variables, buffer-local -@cindex buffer-local variables - - Global and local variable bindings are found in most programming -languages in one form or another. Emacs also supports another, unusual -kind of variable binding: @dfn{buffer-local} bindings, which apply only -to one buffer. Emacs Lisp is meant for programming editing commands, -and having different values for a variable in different buffers is an -important customization method. (A few variables have bindings that -are local to a given X terminal; see @ref{Multiple Displays}.) - -@menu -* Intro to Buffer-Local:: Introduction and concepts. -* Creating Buffer-Local:: Creating and destroying buffer-local bindings. -* Default Value:: The default value is seen in buffers - that don't have their own local values. -@end menu - -@node Intro to Buffer-Local -@subsection Introduction to Buffer-Local Variables - - A buffer-local variable has a buffer-local binding associated with a -particular buffer. The binding is in effect when that buffer is -current; otherwise, it is not in effect. If you set the variable while -a buffer-local binding is in effect, the new value goes in that binding, -so the global binding is unchanged; this means that the change is -visible in that buffer alone. - - A variable may have buffer-local bindings in some buffers but not in -others. The global binding is shared by all the buffers that don't have -their own bindings. Thus, if you set the variable in a buffer that does -not have a buffer-local binding for it, the new value is visible in all -buffers except those with buffer-local bindings. (Here we are assuming -that there are no @code{let}-style local bindings to complicate the issue.) - - The most common use of buffer-local bindings is for major modes to change -variables that control the behavior of commands. For example, C mode and -Lisp mode both set the variable @code{paragraph-start} to specify that only -blank lines separate paragraphs. They do this by making the variable -buffer-local in the buffer that is being put into C mode or Lisp mode, and -then setting it to the new value for that mode. - - The usual way to make a buffer-local binding is with -@code{make-local-variable}, which is what major mode commands use. This -affects just the current buffer; all other buffers (including those yet to -be created) continue to share the global value. - -@cindex automatically buffer-local - A more powerful operation is to mark the variable as -@dfn{automatically buffer-local} by calling -@code{make-variable-buffer-local}. You can think of this as making the -variable local in all buffers, even those yet to be created. More -precisely, the effect is that setting the variable automatically makes -the variable local to the current buffer if it is not already so. All -buffers start out by sharing the global value of the variable as usual, -but any @code{setq} creates a buffer-local binding for the current -buffer. The new value is stored in the buffer-local binding, leaving -the (default) global binding untouched. The global value can no longer -be changed with @code{setq}; you need to use @code{setq-default} to do -that. - - @strong{Warning:} When a variable has local values in one or more -buffers, you can get Emacs very confused by binding the variable with -@code{let}, changing to a different current buffer in which a different -binding is in effect, and then exiting the @code{let}. This can -scramble the values of the global and local bindings. - - To preserve your sanity, avoid that series of actions. If you use -@code{save-excursion} around each piece of code that changes to a -different current buffer, you will not have this problem. Here is an -example of what to avoid: - -@example -@group -(setq foo 'b) -(set-buffer "a") -(make-local-variable 'foo) -@end group -(setq foo 'a) -(let ((foo 'temp)) - (set-buffer "b") - @var{body}@dots{}) -@group -foo @result{} 'a ; @r{The old buffer-local value from buffer @samp{a}} - ; @r{is now the default value.} -@end group -@group -(set-buffer "a") -foo @result{} 'temp ; @r{The local value that should be gone} - ; @r{is now the buffer-local value in buffer @samp{a}.} -@end group -@end example - -@noindent -But @code{save-excursion} as shown here avoids the problem: - -@example -@group -(let ((foo 'temp)) - (save-excursion - (set-buffer "b") - @var{body}@dots{})) -@end group -@end example - - Note that references to @code{foo} in @var{body} access the -buffer-local binding of buffer @samp{b}. - - When a file specifies local variable values, these become buffer-local -values when you visit the file. @xref{Auto Major Mode}. - -@node Creating Buffer-Local -@subsection Creating and Deleting Buffer-Local Bindings - -@deffn Command make-local-variable variable -This function creates a buffer-local binding in the current buffer for -@var{variable} (a symbol). Other buffers are not affected. The value -returned is @var{variable}. - -@c Emacs 19 feature -The buffer-local value of @var{variable} starts out as the same value -@var{variable} previously had. If @var{variable} was void, it remains -void. - -@example -@group -;; @r{In buffer @samp{b1}:} -(setq foo 5) ; @r{Affects all buffers.} - @result{} 5 -@end group -@group -(make-local-variable 'foo) ; @r{Now it is local in @samp{b1}.} - @result{} foo -@end group -@group -foo ; @r{That did not change} - @result{} 5 ; @r{the value.} -@end group -@group -(setq foo 6) ; @r{Change the value} - @result{} 6 ; @r{in @samp{b1}.} -@end group -@group -foo - @result{} 6 -@end group - -@group -;; @r{In buffer @samp{b2}, the value hasn't changed.} -(save-excursion - (set-buffer "b2") - foo) - @result{} 5 -@end group -@end example - -Making a variable buffer-local within a @code{let}-binding for that -variable does not work. This is because @code{let} does not distinguish -between different kinds of bindings; it knows only which variable the -binding was made for. - -If the variable is terminal-local, this function signals an error. Such -variables cannot have buffer-local bindings as well. @xref{Multiple -Displays}. - -@strong{Note:} do not use @code{make-local-variable} for a hook -variable. Instead, use @code{make-local-hook}. @xref{Hooks}. -@end deffn - -@deffn Command make-variable-buffer-local variable -This function marks @var{variable} (a symbol) automatically -buffer-local, so that any subsequent attempt to set it will make it -local to the current buffer at the time. - -The value returned is @var{variable}. - -@strong{Note:} It is a mistake to use @code{make-variable-buffer-local} -for user-option variables, simply because users @emph{might} want to -customize them differently in different buffers. Users can make any -variable local, when they wish to. - -The main use of @code{make-variable-buffer-local} is when a variable is -used for internal purposes, and the Lisp program depends on having -separate values in separate buffers. -@end deffn - -@defun local-variable-p variable &optional buffer -This returns @code{t} if @var{variable} is buffer-local in buffer -@var{buffer} (which defaults to the current buffer); otherwise, -@code{nil}. -@end defun - -@defun buffer-local-variables &optional buffer -This function returns a list describing the buffer-local variables in -buffer @var{buffer}. It returns an association list (@pxref{Association -Lists}) in which each association contains one buffer-local variable and -its value. When a buffer-local variable is void in @var{buffer}, then -it appears directly in the resulting list. If @var{buffer} is omitted, -the current buffer is used. - -@example -@group -(make-local-variable 'foobar) -(makunbound 'foobar) -(make-local-variable 'bind-me) -(setq bind-me 69) -@end group -(setq lcl (buffer-local-variables)) - ;; @r{First, built-in variables local in all buffers:} -@result{} ((mark-active . nil) - (buffer-undo-list nil) - (mode-name . "Fundamental") - @dots{} -@group - ;; @r{Next, non-built-in local variables.} - ;; @r{This one is local and void:} - foobar - ;; @r{This one is local and nonvoid:} - (bind-me . 69)) -@end group -@end example - -Note that storing new values into the @sc{cdr}s of cons cells in this -list does @emph{not} change the local values of the variables. -@end defun - -@deffn Command kill-local-variable variable -This function deletes the buffer-local binding (if any) for -@var{variable} (a symbol) in the current buffer. As a result, the -global (default) binding of @var{variable} becomes visible in this -buffer. Usually this results in a change in the value of -@var{variable}, since the global value is usually different from the -buffer-local value just eliminated. - -If you kill the local binding of a variable that automatically becomes -local when set, this makes the global value visible in the current -buffer. However, if you set the variable again, that will once again -create a local binding for it. - -@code{kill-local-variable} returns @var{variable}. - -This function is a command because it is sometimes useful to kill one -buffer-local variable interactively, just as it is useful to create -buffer-local variables interactively. -@end deffn - -@defun kill-all-local-variables -This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as ``permanent''. As a -result, the buffer will see the default values of most variables. - -This function also resets certain other information pertaining to the -buffer: it sets the local keymap to @code{nil}, the syntax table to the -value of @code{standard-syntax-table}, and the abbrev table to the value -of @code{fundamental-mode-abbrev-table}. - -Every major mode command begins by calling this function, which has the -effect of switching to Fundamental mode and erasing most of the effects -of the previous major mode. To ensure that this does its job, the -variables that major modes set should not be marked permanent. - -@code{kill-all-local-variables} returns @code{nil}. -@end defun - -@c Emacs 19 feature -@cindex permanent local variable -A local variable is @dfn{permanent} if the variable name (a symbol) has a -@code{permanent-local} property that is non-@code{nil}. Permanent -locals are appropriate for data pertaining to where the file came from -or how to save it, rather than with how to edit the contents. - -@node Default Value -@subsection The Default Value of a Buffer-Local Variable -@cindex default value - - The global value of a variable with buffer-local bindings is also -called the @dfn{default} value, because it is the value that is in -effect except when specifically overridden. - - The functions @code{default-value} and @code{setq-default} access and -change a variable's default value regardless of whether the current -buffer has a buffer-local binding. For example, you could use -@code{setq-default} to change the default setting of -@code{paragraph-start} for most buffers; and this would work even when -you are in a C or Lisp mode buffer that has a buffer-local value for -this variable. - -@c Emacs 19 feature - The special forms @code{defvar} and @code{defconst} also set the -default value (if they set the variable at all), rather than any local -value. - -@defun default-value symbol -This function returns @var{symbol}'s default value. This is the value -that is seen in buffers that do not have their own values for this -variable. If @var{symbol} is not buffer-local, this is equivalent to -@code{symbol-value} (@pxref{Accessing Variables}). -@end defun - -@c Emacs 19 feature -@defun default-boundp symbol -The function @code{default-boundp} tells you whether @var{symbol}'s -default value is nonvoid. If @code{(default-boundp 'foo)} returns -@code{nil}, then @code{(default-value 'foo)} would get an error. - -@code{default-boundp} is to @code{default-value} as @code{boundp} is to -@code{symbol-value}. -@end defun - -@defspec setq-default symbol value -This sets the default value of @var{symbol} to @var{value}. It does not -evaluate @var{symbol}, but does evaluate @var{value}. The value of the -@code{setq-default} form is @var{value}. - -If a @var{symbol} is not buffer-local for the current buffer, and is not -marked automatically buffer-local, @code{setq-default} has the same -effect as @code{setq}. If @var{symbol} is buffer-local for the current -buffer, then this changes the value that other buffers will see (as long -as they don't have a buffer-local value), but not the value that the -current buffer sees. - -@example -@group -;; @r{In buffer @samp{foo}:} -(make-local-variable 'local) - @result{} local -@end group -@group -(setq local 'value-in-foo) - @result{} value-in-foo -@end group -@group -(setq-default local 'new-default) - @result{} new-default -@end group -@group -local - @result{} value-in-foo -@end group -@group -(default-value 'local) - @result{} new-default -@end group - -@group -;; @r{In (the new) buffer @samp{bar}:} -local - @result{} new-default -@end group -@group -(default-value 'local) - @result{} new-default -@end group -@group -(setq local 'another-default) - @result{} another-default -@end group -@group -(default-value 'local) - @result{} another-default -@end group - -@group -;; @r{Back in buffer @samp{foo}:} -local - @result{} value-in-foo -(default-value 'local) - @result{} another-default -@end group -@end example -@end defspec - -@defun set-default symbol value -This function is like @code{setq-default}, except that @var{symbol} is -evaluated. - -@example -@group -(set-default (car '(a b c)) 23) - @result{} 23 -@end group -@group -(default-value 'a) - @result{} 23 -@end group -@end example -@end defun diff --git a/lispref/windows.texi b/lispref/windows.texi deleted file mode 100644 index 36b422d21c7..00000000000 --- a/lispref/windows.texi +++ /dev/null @@ -1,1817 +0,0 @@ -@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/windows -@node Windows, Frames, Buffers, Top -@chapter Windows - - This chapter describes most of the functions and variables related to -Emacs windows. See @ref{Display}, for information on how text is -displayed in windows. - -@menu -* Basic Windows:: Basic information on using windows. -* Splitting Windows:: Splitting one window into two windows. -* Deleting Windows:: Deleting a window gives its space to other windows. -* Selecting Windows:: The selected window is the one that you edit in. -* Cyclic Window Ordering:: Moving around the existing windows. -* Buffers and Windows:: Each window displays the contents of a buffer. -* Displaying Buffers:: Higher-lever functions for displaying a buffer - and choosing a window for it. -* Choosing Window:: How to choose a window for displaying a buffer. -* Window Point:: Each window has its own location of point. -* Window Start:: The display-start position controls which text - is on-screen in the window. -* Vertical Scrolling:: Moving text up and down in the window. -* Scrolling Hooks:: Hooks that run when you scroll a window. -* Horizontal Scrolling:: Moving text sideways on the window. -* Size of Window:: Accessing the size of a window. -* Resizing Windows:: Changing the size of a window. -* Coordinates and Windows:: Converting coordinates to windows. -* Window Configurations:: Saving and restoring the state of the screen. -@end menu - -@node Basic Windows -@section Basic Concepts of Emacs Windows -@cindex window -@cindex selected window - - A @dfn{window} in Emacs is the physical area of the screen in which a -buffer is displayed. The term is also used to refer to a Lisp object that -represents that screen area in Emacs Lisp. It should be -clear from the context which is meant. - - Emacs groups windows into frames. A frame represents an area of -screen available for Emacs to use. Each frame always contains at least -one window, but you can subdivide it vertically or horizontally into -multiple nonoverlapping Emacs windows. - - In each frame, at any time, one and only one window is designated as -@dfn{selected within the frame}. The frame's cursor appears in that -window. At ant time, one frame is the selected frame; and the window -selected within that frame is @dfn{the selected window}. The selected -window's buffer is usually the current buffer (except when -@code{set-buffer} has been used). @xref{Current Buffer}. - - For practical purposes, a window exists only while it is displayed in -a frame. Once removed from the frame, the window is effectively deleted -and should not be used, @emph{even though there may still be references -to it} from other Lisp objects. Restoring a saved window configuration -is the only way for a window no longer on the screen to come back to -life. (@xref{Deleting Windows}.) - - Each window has the following attributes: - -@itemize @bullet -@item -containing frame - -@item -window height - -@item -window width - -@item -window edges with respect to the screen or frame - -@item -the buffer it displays - -@item -position within the buffer at the upper left of the window - -@item -amount of horizontal scrolling, in columns - -@item -point - -@item -the mark - -@item -how recently the window was selected -@end itemize - -@cindex multiple windows - Users create multiple windows so they can look at several buffers at -once. Lisp libraries use multiple windows for a variety of reasons, but -most often to display related information. In Rmail, for example, you -can move through a summary buffer in one window while the other window -shows messages one at a time as they are reached. - - The meaning of ``window'' in Emacs is similar to what it means in the -context of general-purpose window systems such as X, but not identical. -The X Window System places X windows on the screen; Emacs uses one or -more X windows as frames, and subdivides them into -Emacs windows. When you use Emacs on a character-only terminal, Emacs -treats the whole terminal screen as one frame. - -@cindex terminal screen -@cindex screen of terminal -@cindex tiled windows - Most window systems support arbitrarily located overlapping windows. -In contrast, Emacs windows are @dfn{tiled}; they never overlap, and -together they fill the whole screen or frame. Because of the way -in which Emacs creates new windows and resizes them, you can't create -every conceivable tiling of windows on an Emacs frame. @xref{Splitting -Windows}, and @ref{Size of Window}. - - @xref{Display}, for information on how the contents of the -window's buffer are displayed in the window. - -@defun windowp object - This function returns @code{t} if @var{object} is a window. -@end defun - -@node Splitting Windows -@section Splitting Windows -@cindex splitting windows -@cindex window splitting - - The functions described here are the primitives used to split a window -into two windows. Two higher level functions sometimes split a window, -but not always: @code{pop-to-buffer} and @code{display-buffer} -(@pxref{Displaying Buffers}). - - The functions described here do not accept a buffer as an argument. -The two ``halves'' of the split window initially display the same buffer -previously visible in the window that was split. - -@deffn Command split-window &optional window size horizontal -This function splits @var{window} into two windows. The original -window @var{window} remains the selected window, but occupies only -part of its former screen area. The rest is occupied by a newly created -window which is returned as the value of this function. - - If @var{horizontal} is non-@code{nil}, then @var{window} splits into -two side by side windows. The original window @var{window} keeps the -leftmost @var{size} columns, and gives the rest of the columns to the -new window. Otherwise, it splits into windows one above the other, and -@var{window} keeps the upper @var{size} lines and gives the rest of the -lines to the new window. The original window is therefore the -left-hand or upper of the two, and the new window is the right-hand or -lower. - - If @var{window} is omitted or @code{nil}, then the selected window is -split. If @var{size} is omitted or @code{nil}, then @var{window} is -divided evenly into two parts. (If there is an odd line, it is -allocated to the new window.) When @code{split-window} is called -interactively, all its arguments are @code{nil}. - - The following example starts with one window on a screen that is 50 -lines high by 80 columns wide; then the window is split. - -@smallexample -@group -(setq w (selected-window)) - @result{} #<window 8 on windows.texi> -(window-edges) ; @r{Edges in order:} - @result{} (0 0 80 50) ; @r{left--top--right--bottom} -@end group - -@group -;; @r{Returns window created} -(setq w2 (split-window w 15)) - @result{} #<window 28 on windows.texi> -@end group -@group -(window-edges w2) - @result{} (0 15 80 50) ; @r{Bottom window;} - ; @r{top is line 15} -@end group -@group -(window-edges w) - @result{} (0 0 80 15) ; @r{Top window} -@end group -@end smallexample - -The screen looks like this: - -@smallexample -@group - __________ - | | line 0 - | w | - |__________| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 -@end group -@end smallexample - -Next, the top window is split horizontally: - -@smallexample -@group -(setq w3 (split-window w 35 t)) - @result{} #<window 32 on windows.texi> -@end group -@group -(window-edges w3) - @result{} (35 0 80 15) ; @r{Left edge at column 35} -@end group -@group -(window-edges w) - @result{} (0 0 35 15) ; @r{Right edge at column 35} -@end group -@group -(window-edges w2) - @result{} (0 15 80 50) ; @r{Bottom window unchanged} -@end group -@end smallexample - -@need 3000 -Now, the screen looks like this: - -@smallexample -@group - column 35 - __________ - | | | line 0 - | w | w3 | - |___|______| - | | line 15 - | w2 | - |__________| - line 50 - column 0 column 80 -@end group -@end smallexample - -Normally, Emacs indicates the border between two side-by-side windows -with a scroll bar (@pxref{X Frame Parameters,Scroll Bars}) or @samp{|} -characters. The display table can specify alternative border -characters; see @ref{Display Tables}. -@end deffn - -@deffn Command split-window-vertically size -This function splits the selected window into two windows, one above -the other, leaving the selected window with @var{size} lines. - -This function is simply an interface to @code{split-windows}. -Here is the complete function definition for it: - -@smallexample -@group -(defun split-window-vertically (&optional arg) - "Split current window into two windows, @dots{}" - (interactive "P") - (split-window nil (and arg (prefix-numeric-value arg)))) -@end group -@end smallexample -@end deffn - -@deffn Command split-window-horizontally size -This function splits the selected window into two windows -side-by-side, leaving the selected window with @var{size} columns. - -This function is simply an interface to @code{split-windows}. Here is -the complete definition for @code{split-window-horizontally} (except for -part of the documentation string): - -@smallexample -@group -(defun split-window-horizontally (&optional arg) - "Split selected window into two windows, side by side..." - (interactive "P") - (split-window nil (and arg (prefix-numeric-value arg)) t)) -@end group -@end smallexample -@end deffn - -@defun one-window-p &optional no-mini all-frames -This function returns non-@code{nil} if there is only one window. The -argument @var{no-mini}, if non-@code{nil}, means don't count the -minibuffer even if it is active; otherwise, the minibuffer window is -included, if active, in the total number of windows, which is compared -against one. - -The argument @var{all-frames} specifies which frames to consider. Here -are the possible values and their meanings: - -@table @asis -@item @code{nil} -Count the windows in the selected frame, plus the minibuffer used -by that frame even if it lies in some other frame. - -@item @code{t} -Count all windows in all existing frames. - -@item @code{visible} -Count all windows in all visible frames. - -@item 0 -Count all windows in all visible or iconified frames. - -@item anything else -Count precisely the windows in the selected frame, and no others. -@end table -@end defun - -@node Deleting Windows -@section Deleting Windows -@cindex deleting windows - -A window remains visible on its frame unless you @dfn{delete} it by -calling certain functions that delete windows. A deleted window cannot -appear on the screen, but continues to exist as a Lisp object until -there are no references to it. There is no way to cancel the deletion -of a window aside from restoring a saved window configuration -(@pxref{Window Configurations}). Restoring a window configuration also -deletes any windows that aren't part of that configuration. - - When you delete a window, the space it took up is given to one -adjacent sibling. (In Emacs version 18, the space was divided evenly -among all the siblings.) - -@c Emacs 19 feature -@defun window-live-p window -This function returns @code{nil} if @var{window} is deleted, and -@code{t} otherwise. - -@strong{Warning:} Erroneous information or fatal errors may result from -using a deleted window as if it were live. -@end defun - -@deffn Command delete-window &optional window -This function removes @var{window} from the display. If @var{window} -is omitted, then the selected window is deleted. An error is signaled -if there is only one window when @code{delete-window} is called. - -This function returns @code{nil}. - -When @code{delete-window} is called interactively, @var{window} -defaults to the selected window. -@end deffn - -@deffn Command delete-other-windows &optional window -This function makes @var{window} the only window on its frame, by -deleting the other windows in that frame. If @var{window} is omitted or -@code{nil}, then the selected window is used by default. - -The result is @code{nil}. -@end deffn - -@deffn Command delete-windows-on buffer &optional frame -This function deletes all windows showing @var{buffer}. If there are -no windows showing @var{buffer}, it does nothing. - -@code{delete-windows-on} operates frame by frame. If a frame has -several windows showing different buffers, then those showing -@var{buffer} are removed, and the others expand to fill the space. If -all windows in some frame are showing @var{buffer} (including the case -where there is only one window), then the frame reverts to having a -single window showing another buffer chosen with @code{other-buffer}. -@xref{The Buffer List}. - -The argument @var{frame} controls which frames to operate on: - -@itemize @bullet -@item -If it is @code{nil}, operate on the selected frame. -@item -If it is @code{t}, operate on all frames. -@item -If it is @code{visible}, operate on all visible frames. -@item 0 -If it is 0, operate on all visible or iconified frames. -@item -If it is a frame, operate on that frame. -@end itemize - -This function always returns @code{nil}. -@end deffn - -@node Selecting Windows -@section Selecting Windows -@cindex selecting windows - - When a window is selected, the buffer in the window becomes the current -buffer, and the cursor will appear in it. - -@defun selected-window -This function returns the selected window. This is the window in -which the cursor appears and to which many commands apply. -@end defun - -@defun select-window window -This function makes @var{window} the selected window. The cursor then -appears in @var{window} (on redisplay). The buffer being displayed in -@var{window} is immediately designated the current buffer. - -The return value is @var{window}. - -@example -@group -(setq w (next-window)) -(select-window w) - @result{} #<window 65 on windows.texi> -@end group -@end example -@end defun - -@defmac save-selected-window forms@dots{} -This macro records the selected window, executes @var{forms} -in sequence, then restores the earlier selected window. - -This macro does not save or restore anything about the sizes, arrangement -or contents of windows; therefore, if the @var{forms} change them, -the change persists. - -Each frame, at any time, has a window selected within the frame. This -macro only saves @emph{the} selected window; it does not save anything -about other frames. If the @var{forms} select some other frame and -alter the window selected within it, the change persists. -@end defmac - -@cindex finding windows - The following functions choose one of the windows on the screen, -offering various criteria for the choice. - -@defun get-lru-window &optional frame -This function returns the window least recently ``used'' (that is, -selected). The selected window is always the most recently used window. - -The selected window can be the least recently used window if it is the -only window. A newly created window becomes the least recently used -window until it is selected. A minibuffer window is never a candidate. - -The argument @var{frame} controls which windows are considered. - -@itemize @bullet -@item -If it is @code{nil}, consider windows on the selected frame. -@item -If it is @code{t}, consider windows on all frames. -@item -If it is @code{visible}, consider windows on all visible frames. -@item -If it is 0, consider windows on all visible or iconified frames. -@item -If it is a frame, consider windows on that frame. -@end itemize -@end defun - -@defun get-largest-window &optional frame -This function returns the window with the largest area (height times -width). If there are no side-by-side windows, then this is the window -with the most lines. A minibuffer window is never a candidate. - -If there are two windows of the same size, then the function returns -the window that is first in the cyclic ordering of windows (see -following section), starting from the selected window. - -The argument @var{frame} controls which set of windows are -considered. See @code{get-lru-window}, above. -@end defun - -@node Cyclic Window Ordering -@comment node-name, next, previous, up -@section Cyclic Ordering of Windows -@cindex cyclic ordering of windows -@cindex ordering of windows, cyclic -@cindex window ordering, cyclic - - When you use the command @kbd{C-x o} (@code{other-window}) to select -the next window, it moves through all the windows on the screen in a -specific cyclic order. For any given configuration of windows, this -order never varies. It is called the @dfn{cyclic ordering of windows}. - - This ordering generally goes from top to bottom, and from left to -right. But it may go down first or go right first, depending on the -order in which the windows were split. - - If the first split was vertical (into windows one above each other), -and then the subwindows were split horizontally, then the ordering is -left to right in the top of the frame, and then left to right in the -next lower part of the frame, and so on. If the first split was -horizontal, the ordering is top to bottom in the left part, and so on. -In general, within each set of siblings at any level in the window tree, -the order is left to right, or top to bottom. - -@defun next-window &optional window minibuf all-frames -@cindex minibuffer window -This function returns the window following @var{window} in the cyclic -ordering of windows. This is the window that @kbd{C-x o} would select -if typed when @var{window} is selected. If @var{window} is the only -window visible, then this function returns @var{window}. If omitted, -@var{window} defaults to the selected window. - -The value of the argument @var{minibuf} determines whether the -minibuffer is included in the window order. Normally, when -@var{minibuf} is @code{nil}, the minibuffer is included if it is -currently active; this is the behavior of @kbd{C-x o}. (The minibuffer -window is active while the minibuffer is in use. @xref{Minibuffers}.) - -If @var{minibuf} is @code{t}, then the cyclic ordering includes the -minibuffer window even if it is not active. - -If @var{minibuf} is neither @code{t} nor @code{nil}, then the minibuffer -window is not included even if it is active. - -The argument @var{all-frames} specifies which frames to consider. Here -are the possible values and their meanings: - -@table @asis -@item @code{nil} -Consider all the windows in @var{window}'s frame, plus the minibuffer -used by that frame even if it lies in some other frame. - -@item @code{t} -Consider all windows in all existing frames. - -@item @code{visible} -Consider all windows in all visible frames. (To get useful results, you -must ensure @var{window} is in a visible frame.) - -@item 0 -Consider all windows in all visible or iconified frames. - -@item anything else -Consider precisely the windows in @var{window}'s frame, and no others. -@end table - -This example assumes there are two windows, both displaying the -buffer @samp{windows.texi}: - -@example -@group -(selected-window) - @result{} #<window 56 on windows.texi> -@end group -@group -(next-window (selected-window)) - @result{} #<window 52 on windows.texi> -@end group -@group -(next-window (next-window (selected-window))) - @result{} #<window 56 on windows.texi> -@end group -@end example -@end defun - -@defun previous-window &optional window minibuf all-frames -This function returns the window preceding @var{window} in the cyclic -ordering of windows. The other arguments specify which windows to -include in the cycle, as in @code{next-window}. -@end defun - -@deffn Command other-window count -This function selects the @var{count}th following window in the cyclic -order. If count is negative, then it selects the @minus{}@var{count}th -preceding window. It returns @code{nil}. - -In an interactive call, @var{count} is the numeric prefix argument. -@end deffn - -@c Emacs 19 feature -@defun walk-windows proc &optional minibuf all-frames -This function cycles through all windows, calling @code{proc} -once for each window with the window as its sole argument. - -The optional arguments @var{minibuf} and @var{all-frames} specify the -set of windows to include in the scan. See @code{next-window}, above, -for details. -@end defun - -@node Buffers and Windows -@section Buffers and Windows -@cindex examining windows -@cindex windows, controlling precisely -@cindex buffers, controlled in windows - - This section describes low-level functions to examine windows or to -display buffers in windows in a precisely controlled fashion. -@iftex -See the following section for -@end iftex -@ifinfo -@xref{Displaying Buffers}, for -@end ifinfo -related functions that find a window to use and specify a buffer for it. -The functions described there are easier to use than these, but they -employ heuristics in choosing or creating a window; use these functions -when you need complete control. - -@defun set-window-buffer window buffer-or-name -This function makes @var{window} display @var{buffer-or-name} as its -contents. It returns @code{nil}. - -@example -@group -(set-window-buffer (selected-window) "foo") - @result{} nil -@end group -@end example -@end defun - -@defun window-buffer &optional window -This function returns the buffer that @var{window} is displaying. If -@var{window} is omitted, this function returns the buffer for the -selected window. - -@example -@group -(window-buffer) - @result{} #<buffer windows.texi> -@end group -@end example -@end defun - -@defun get-buffer-window buffer-or-name &optional all-frames -This function returns a window currently displaying -@var{buffer-or-name}, or @code{nil} if there is none. If there are -several such windows, then the function returns the first one in the -cyclic ordering of windows, starting from the selected window. -@xref{Cyclic Window Ordering}. - -The argument @var{all-frames} controls which windows to consider. - -@itemize @bullet -@item -If it is @code{nil}, consider windows on the selected frame. -@item -If it is @code{t}, consider windows on all frames. -@item -If it is @code{visible}, consider windows on all visible frames. -@item -If it is 0, consider windows on all visible or iconified frames. -@item -If it is a frame, consider windows on that frame. -@end itemize -@end defun - -@defun get-buffer-window-list buffer-or-name &optional minibuf all-frames -This function returns a list of all the windows currently displaying -@var{buffer-or-name}. - -The two optional arguments work like the optional arguments of -@code{next-window} (@pxref{Cyclic Window Ordering}); they are @emph{not} -like the single optional argument of @code{get-buffer-window}. Perhaps -we should change @code{get-buffer-window} in the future to make it -compatible with the other functions. - -The argument @var{all-frames} controls which windows to consider. - -@itemize @bullet -@item -If it is @code{nil}, consider windows on the selected frame. -@item -If it is @code{t}, consider windows on all frames. -@item -If it is @code{visible}, consider windows on all visible frames. -@item -If it is 0, consider windows on all visible or iconified frames. -@item -If it is a frame, consider windows on that frame. -@end itemize -@end defun - -@node Displaying Buffers -@section Displaying Buffers in Windows -@cindex switching to a buffer -@cindex displaying a buffer - - In this section we describe convenient functions that choose a window -automatically and use it to display a specified buffer. These functions -can also split an existing window in certain circumstances. We also -describe variables that parameterize the heuristics used for choosing a -window. -@iftex -See the preceding section for -@end iftex -@ifinfo -@xref{Buffers and Windows}, for -@end ifinfo -low-level functions that give you more precise control. - - Do not use the functions in this section in order to make a buffer -current so that a Lisp program can access or modify it; they are too -drastic for that purpose, since they change the display of buffers in -windows, which is gratuitous and will surprise the user. Instead, use -@code{set-buffer} (@pxref{Current Buffer}) and @code{save-excursion} -(@pxref{Excursions}), which designate buffers as current for programmed -access without affecting the display of buffers in windows. - -@deffn Command switch-to-buffer buffer-or-name &optional norecord -This function makes @var{buffer-or-name} the current buffer, and also -displays the buffer in the selected window. This means that a human can -see the buffer and subsequent keyboard commands will apply to it. -Contrast this with @code{set-buffer}, which makes @var{buffer-or-name} -the current buffer but does not display it in the selected window. -@xref{Current Buffer}. - -If @var{buffer-or-name} does not identify an existing buffer, then a new -buffer by that name is created. The major mode for the new buffer is -set according to the variable @code{default-major-mode}. @xref{Auto -Major Mode}. - -Normally the specified buffer is put at the front of the buffer list. -This affects the operation of @code{other-buffer}. However, if -@var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer -List}. - -The @code{switch-to-buffer} function is often used interactively, as -the binding of @kbd{C-x b}. It is also used frequently in programs. It -always returns @code{nil}. -@end deffn - -@deffn Command switch-to-buffer-other-window buffer-or-name -This function makes @var{buffer-or-name} the current buffer and -displays it in a window not currently selected. It then selects that -window. The handling of the buffer is the same as in -@code{switch-to-buffer}. - -The currently selected window is absolutely never used to do the job. -If it is the only window, then it is split to make a distinct window for -this purpose. If the selected window is already displaying the buffer, -then it continues to do so, but another window is nonetheless found to -display it in as well. -@end deffn - -@defun pop-to-buffer buffer-or-name &optional other-window -This function makes @var{buffer-or-name} the current buffer and -switches to it in some window, preferably not the window previously -selected. The ``popped-to'' window becomes the selected window within -its frame. - -If the variable @code{pop-up-frames} is non-@code{nil}, -@code{pop-to-buffer} looks for a window in any visible frame already -displaying the buffer; if there is one, it returns that window and makes -it be selected within its frame. If there is none, it creates a new -frame and displays the buffer in it. - -If @code{pop-up-frames} is @code{nil}, then @code{pop-to-buffer} -operates entirely within the selected frame. (If the selected frame has -just a minibuffer, @code{pop-to-buffer} operates within the most -recently selected frame that was not just a minibuffer.) - -If the variable @code{pop-up-windows} is non-@code{nil}, windows may -be split to create a new window that is different from the original -window. For details, see @ref{Choosing Window}. - -If @var{other-window} is non-@code{nil}, @code{pop-to-buffer} finds or -creates another window even if @var{buffer-or-name} is already visible -in the selected window. Thus @var{buffer-or-name} could end up -displayed in two windows. On the other hand, if @var{buffer-or-name} is -already displayed in the selected window and @var{other-window} is -@code{nil}, then the selected window is considered sufficient display -for @var{buffer-or-name}, so that nothing needs to be done. - -All the variables that affect @code{display-buffer} affect -@code{pop-to-buffer} as well. @xref{Choosing Window}. - -If @var{buffer-or-name} is a string that does not name an existing -buffer, a buffer by that name is created. The major mode for the new -buffer is set according to the variable @code{default-major-mode}. -@xref{Auto Major Mode}. -@end defun - -@deffn Command replace-buffer-in-windows buffer -This function replaces @var{buffer} with some other buffer in all -windows displaying it. The other buffer used is chosen with -@code{other-buffer}. In the usual applications of this function, you -don't care which other buffer is used; you just want to make sure that -@var{buffer} is no longer displayed. - -This function returns @code{nil}. -@end deffn - -@node Choosing Window -@section Choosing a Window for Display - - This section describes the basic facility that chooses a window to -display a buffer in---@code{display-buffer}. All the higher-level -functions and commands use this subroutine. Here we describe how to use -@code{display-buffer} and how to customize it. - -@deffn Command display-buffer buffer-or-name &optional not-this-window -This command makes @var{buffer-or-name} appear in some window, like -@code{pop-to-buffer}, but it does not select that window and does not -make the buffer current. The identity of the selected window is -unaltered by this function. - -If @var{not-this-window} is non-@code{nil}, it means to display the -specified buffer in a window other than the selected one, even if it is -already on display in the selected window. This can cause the buffer to -appear in two windows at once. Otherwise, if @var{buffer-or-name} is -already being displayed in any window, that is good enough, so this -function does nothing. - -@code{display-buffer} returns the window chosen to display -@var{buffer-or-name}. - -Precisely how @code{display-buffer} finds or creates a window depends on -the variables described below. -@end deffn - -@defopt pop-up-windows -This variable controls whether @code{display-buffer} makes new windows. -If it is non-@code{nil} and there is only one window, then that window -is split. If it is @code{nil}, then @code{display-buffer} does not -split the single window, but uses it whole. -@end defopt - -@defopt split-height-threshold -This variable determines when @code{display-buffer} may split a window, -if there are multiple windows. @code{display-buffer} always splits the -largest window if it has at least this many lines. If the largest -window is not this tall, it is split only if it is the sole window and -@code{pop-up-windows} is non-@code{nil}. -@end defopt - -@c Emacs 19 feature -@defopt pop-up-frames -This variable controls whether @code{display-buffer} makes new frames. -If it is non-@code{nil}, @code{display-buffer} looks for an existing -window already displaying the desired buffer, on any visible frame. If -it finds one, it returns that window. Otherwise it makes a new frame. -The variables @code{pop-up-windows} and @code{split-height-threshold} do -not matter if @code{pop-up-frames} is non-@code{nil}. - -If @code{pop-up-frames} is @code{nil}, then @code{display-buffer} either -splits a window or reuses one. - -@xref{Frames}, for more information. -@end defopt - -@c Emacs 19 feature -@defvar pop-up-frame-function -This variable specifies how to make a new frame if @code{pop-up-frames} -is non-@code{nil}. - -Its value should be a function of no arguments. When -@code{display-buffer} makes a new frame, it does so by calling that -function, which should return a frame. The default value of the -variable is a function that creates a frame using parameters from -@code{pop-up-frame-alist}. -@end defvar - -@defvar pop-up-frame-alist -This variable holds an alist specifying frame parameters used when -@code{display-buffer} makes a new frame. @xref{Frame Parameters}, for -more information about frame parameters. -@end defvar - -@defvar special-display-buffer-names -A list of buffer names for buffers that should be displayed specially. -If the buffer's name is in this list, @code{display-buffer} handles the -buffer specially. - -By default, special display means to give the buffer a dedicated frame. - -If an element is a list, instead of a string, then the @sc{car} of the -list is the buffer name, and the rest of the list says how to create the -frame. There are two possibilities for the rest of the list. It can be -an alist, specifying frame parameters, or it can contain a function and -arguments to give to it. (The function's first argument is always the -buffer to be displayed; the arguments from the list come after that.) -@end defvar - -@defvar special-display-regexps -A list of regular expressions that specify buffers that should be -displayed specially. If the buffer's name matches any of the regular -expressions in this list, @code{display-buffer} handles the buffer -specially. - -By default, special display means to give the buffer a dedicated frame. - -If an element is a list, instead of a string, then the @sc{car} of the -list is the regular expression, and the rest of the list says how to -create the frame. See above, under @code{special-display-buffer-names}. -@end defvar - -@defvar special-display-function -This variable holds the function to call to display a buffer specially. -It receives the buffer as an argument, and should return the window in -which it is displayed. - -The default value of this variable is -@code{special-display-popup-frame}. -@end defvar - -@defun special-display-popup-frame buffer -This function makes @var{buffer} visible in a frame of its own. If -@var{buffer} is already displayed in a window in some frame, it makes -the frame visible and raises it, to use that window. Otherwise, it -creates a frame that will be dedicated to @var{buffer}. - -This function uses an existing window displaying @var{buffer} whether or -not it is in a frame of its own; but if you set up the above variables -in your init file, before @var{buffer} was created, then presumably the -window was previously made by this function. -@end defun - -@defopt special-display-frame-alist -This variable holds frame parameters for -@code{special-display-popup-frame} to use when it creates a frame. -@end defopt - -@defopt same-window-buffer-names -A list of buffer names for buffers that should be displayed in the -selected window. If the buffer's name is in this list, -@code{display-buffer} handles the buffer by switching to it in the -selected window. -@end defopt - -@defopt same-window-regexps -A list of regular expressions that specify buffers that should be -displayed in the selected window. If the buffer's name matches any of -the regular expressions in this list, @code{display-buffer} handles the -buffer by switching to it in the selected window. -@end defopt - -@c Emacs 19 feature -@defvar display-buffer-function -This variable is the most flexible way to customize the behavior of -@code{display-buffer}. If it is non-@code{nil}, it should be a function -that @code{display-buffer} calls to do the work. The function should -accept two arguments, the same two arguments that @code{display-buffer} -received. It should choose or create a window, display the specified -buffer, and then return the window. - -This hook takes precedence over all the other options and hooks -described above. -@end defvar - -@c Emacs 19 feature -@cindex dedicated window -A window can be marked as ``dedicated'' to its buffer. Then -@code{display-buffer} does not try to use that window. - -@defun window-dedicated-p window -This function returns @code{t} if @var{window} is marked as dedicated; -otherwise @code{nil}. -@end defun - -@defun set-window-dedicated-p window flag -This function marks @var{window} as dedicated if @var{flag} is -non-@code{nil}, and nondedicated otherwise. -@end defun - -@node Window Point -@section Windows and Point -@cindex window position -@cindex window point -@cindex position in window -@cindex point in window - - Each window has its own value of point, independent of the value of -point in other windows displaying the same buffer. This makes it useful -to have multiple windows showing one buffer. - -@itemize @bullet -@item -The window point is established when a window is first created; it is -initialized from the buffer's point, or from the window point of another -window opened on the buffer if such a window exists. - -@item -Selecting a window sets the value of point in its buffer to the window's -value of point. Conversely, deselecting a window sets the window's -value of point from that of the buffer. Thus, when you switch between -windows that display a given buffer, the point value for the selected -window is in effect in the buffer, while the point values for the other -windows are stored in those windows. - -@item -As long as the selected window displays the current buffer, the window's -point and the buffer's point always move together; they remain equal. - -@item -@xref{Positions}, for more details on buffer positions. -@end itemize - - As far as the user is concerned, point is where the cursor is, and -when the user switches to another buffer, the cursor jumps to the -position of point in that buffer. - -@defun window-point window -This function returns the current position of point in @var{window}. -For a nonselected window, this is the value point would have (in that -window's buffer) if that window were selected. - -When @var{window} is the selected window and its buffer is also the -current buffer, the value returned is the same as point in that buffer. - -Strictly speaking, it would be more correct to return the -``top-level'' value of point, outside of any @code{save-excursion} -forms. But that value is hard to find. -@end defun - -@defun set-window-point window position -This function positions point in @var{window} at position -@var{position} in @var{window}'s buffer. -@end defun - -@node Window Start -@section The Window Start Position - - Each window contains a marker used to keep track of a buffer position -that specifies where in the buffer display should start. This position -is called the @dfn{display-start} position of the window (or just the -@dfn{start}). The character after this position is the one that appears -at the upper left corner of the window. It is usually, but not -inevitably, at the beginning of a text line. - -@defun window-start &optional window -@cindex window top line -This function returns the display-start position of window -@var{window}. If @var{window} is @code{nil}, the selected window is -used. For example, - -@example -@group -(window-start) - @result{} 7058 -@end group -@end example - -When you create a window, or display a different buffer in it, the -display-start position is set to a display-start position recently used -for the same buffer, or 1 if the buffer doesn't have any. - -Redisplay updates the window-start position (if you have not specified -it explicitly since the previous redisplay) so that point appears on the -screen. Nothing except redisplay automatically changes the window-start -position; if you move point, do not expect the window-start position to -change in response until after the next redisplay. - -For a realistic example of using @code{window-start}, see the -description of @code{count-lines} in @ref{Text Lines}. -@end defun - -@defun window-end &optional window -This function returns the position of the end of the display in window -@var{window}. If @var{window} is @code{nil}, the selected window is -used. - -Simply changing the buffer text or moving point does not update the -value that @code{window-end} returns. The value is updated only when -Emacs redisplays and redisplay actually finishes. - -If the last redisplay of @var{window} was preempted, and did not finish, -Emacs does not know the position of the end of display in that window. -In that case, this function returns a value that is not correct. In a -future version, @code{window-end} will return @code{nil} in that case. -@ignore -in that case, this function returns @code{nil}. You can compute where -the end of the window @emph{would} have been, if redisplay had finished, -like this: - -@example -(save-excursion - (goto-char (window-start window)) - (vertical-motion (1- (window-height window)) - window) - (point)) -@end example -@end ignore -@end defun - -@defun set-window-start window position &optional noforce -This function sets the display-start position of @var{window} to -@var{position} in @var{window}'s buffer. It returns @var{position}. - -The display routines insist that the position of point be visible when a -buffer is displayed. Normally, they change the display-start position -(that is, scroll the window) whenever necessary to make point visible. -However, if you specify the start position with this function using -@code{nil} for @var{noforce}, it means you want display to start at -@var{position} even if that would put the location of point off the -screen. If this does place point off screen, the display routines move -point to the left margin on the middle line in the window. - -For example, if point @w{is 1} and you set the start of the window @w{to -2}, then point would be ``above'' the top of the window. The display -routines will automatically move point if it is still 1 when redisplay -occurs. Here is an example: - -@example -@group -;; @r{Here is what @samp{foo} looks like before executing} -;; @r{the @code{set-window-start} expression.} -@end group - -@group ----------- Buffer: foo ---------- -@point{}This is the contents of buffer foo. -2 -3 -4 -5 -6 ----------- Buffer: foo ---------- -@end group - -@group -(set-window-start - (selected-window) - (1+ (window-start))) -@result{} 2 -@end group - -@group -;; @r{Here is what @samp{foo} looks like after executing} -;; @r{the @code{set-window-start} expression.} ----------- Buffer: foo ---------- -his is the contents of buffer foo. -2 -3 -@point{}4 -5 -6 ----------- Buffer: foo ---------- -@end group -@end example - -If @var{noforce} is non-@code{nil}, and @var{position} would place point -off screen at the next redisplay, then redisplay computes a new window-start -position that works well with point, and thus @var{position} is not used. -@end defun - -@defun pos-visible-in-window-p &optional position window -This function returns @code{t} if @var{position} is within the range -of text currently visible on the screen in @var{window}. It returns -@code{nil} if @var{position} is scrolled vertically out of view. The -argument @var{position} defaults to the current position of point; -@var{window}, to the selected window. Here is an example: - -@example -@group -(or (pos-visible-in-window-p - (point) (selected-window)) - (recenter 0)) -@end group -@end example - -The @code{pos-visible-in-window-p} function considers only vertical -scrolling. If @var{position} is out of view only because @var{window} -has been scrolled horizontally, @code{pos-visible-in-window-p} returns -@code{t}. @xref{Horizontal Scrolling}. -@end defun - -@node Vertical Scrolling -@section Vertical Scrolling -@cindex vertical scrolling -@cindex scrolling vertically - - Vertical scrolling means moving the text up or down in a window. It -works by changing the value of the window's display-start location. It -may also change the value of @code{window-point} to keep it on the -screen. - - In the commands @code{scroll-up} and @code{scroll-down}, the directions -``up'' and ``down'' refer to the motion of the text in the buffer at which -you are looking through the window. Imagine that the text is -written on a long roll of paper and that the scrolling commands move the -paper up and down. Thus, if you are looking at text in the middle of a -buffer and repeatedly call @code{scroll-down}, you will eventually see -the beginning of the buffer. - - Some people have urged that the opposite convention be used: they -imagine that the window moves over text that remains in place. Then -``down'' commands would take you to the end of the buffer. This view is -more consistent with the actual relationship between windows and the -text in the buffer, but it is less like what the user sees. The -position of a window on the terminal does not move, and short scrolling -commands clearly move the text up or down on the screen. We have chosen -names that fit the user's point of view. - - The scrolling functions (aside from @code{scroll-other-window}) have -unpredictable results if the current buffer is different from the buffer -that is displayed in the selected window. @xref{Current Buffer}. - -@deffn Command scroll-up &optional count -This function scrolls the text in the selected window upward -@var{count} lines. If @var{count} is negative, scrolling is actually -downward. - -If @var{count} is @code{nil} (or omitted), then the length of scroll -is @code{next-screen-context-lines} lines less than the usable height of -the window (not counting its mode line). - -@code{scroll-up} returns @code{nil}. -@end deffn - -@deffn Command scroll-down &optional count -This function scrolls the text in the selected window downward -@var{count} lines. If @var{count} is negative, scrolling is actually -upward. - -If @var{count} is omitted or @code{nil}, then the length of the scroll -is @code{next-screen-context-lines} lines less than the usable height of -the window (not counting its mode line). - -@code{scroll-down} returns @code{nil}. -@end deffn - -@deffn Command scroll-other-window &optional count -This function scrolls the text in another window upward @var{count} -lines. Negative values of @var{count}, or @code{nil}, are handled -as in @code{scroll-up}. - -You can specify a buffer to scroll with the variable -@code{other-window-scroll-buffer}. When the selected window is the -minibuffer, the next window is normally the one at the top left corner. -You can specify a different window to scroll with the variable -@code{minibuffer-scroll-window}. This variable has no effect when any -other window is selected. @xref{Minibuffer Misc}. - -When the minibuffer is active, it is the next window if the selected -window is the one at the bottom right corner. In this case, -@code{scroll-other-window} attempts to scroll the minibuffer. If the -minibuffer contains just one line, it has nowhere to scroll to, so the -line reappears after the echo area momentarily displays the message -``Beginning of buffer''. -@end deffn - -@c Emacs 19 feature -@defvar other-window-scroll-buffer -If this variable is non-@code{nil}, it tells @code{scroll-other-window} -which buffer to scroll. -@end defvar - -@defopt scroll-step -This variable controls how scrolling is done automatically when point -moves off the screen. If the value is zero, then redisplay scrolls the -text to center point vertically in the window. If the value is a -positive integer @var{n}, then redisplay brings point back on screen by -scrolling @var{n} lines in either direction, if possible; otherwise, it -centers point. The default value is zero. -@end defopt - -@defopt next-screen-context-lines -The value of this variable is the number of lines of continuity to -retain when scrolling by full screens. For example, @code{scroll-up} -with an argument of @code{nil} scrolls so that this many lines at the -bottom of the window appear instead at the top. The default value is -@code{2}. -@end defopt - -@deffn Command recenter &optional count -@cindex centering point -This function scrolls the selected window to put the text where point -is located at a specified vertical position within the window. - -If @var{count} is a nonnegative number, it puts the line containing -point @var{count} lines down from the top of the window. If @var{count} -is a negative number, then it counts upward from the bottom of the -window, so that @minus{}1 stands for the last usable line in the window. -If @var{count} is a non-@code{nil} list, then it stands for the line in -the middle of the window. - -If @var{count} is @code{nil}, @code{recenter} puts the line containing -point in the middle of the window, then clears and redisplays the entire -selected frame. - -When @code{recenter} is called interactively, @var{count} is the raw -prefix argument. Thus, typing @kbd{C-u} as the prefix sets the -@var{count} to a non-@code{nil} list, while typing @kbd{C-u 4} sets -@var{count} to 4, which positions the current line four lines from the -top. - -With an argument of zero, @code{recenter} positions the current line at -the top of the window. This action is so handy that some people make a -separate key binding to do this. For example, - -@example -@group -(defun line-to-top-of-window () - "Scroll current line to top of window. -Replaces three keystroke sequence C-u 0 C-l." - (interactive) - (recenter 0)) - -(global-set-key [kp-multiply] 'line-to-top-of-window) -@end group -@end example -@end deffn - -@node Scrolling Hooks -@section Hooks for Vertical Scrolling - -This section describes how a Lisp program can take action whenever a -window displays a different part of its buffer or a different buffer. -There are three actions that can change this: scrolling the window, -switching buffers in the window, and changing the size of the window. -The first two actions run @code{window-scroll-functions}; the last runs -@code{window-size-change-functions}. The paradigmatic use of these -hooks is Lazy Lock mode; see @ref{Support Modes, Lazy Lock, Font Lock -Support Modes, emacs, The GNU Emacs Manual}. - -@defvar window-scroll-functions -This variable holds a list of functions that Emacs should call before -redisplaying a window with scrolling. It is not a normal hook, because -each function is called with two arguments: the window, and its new -display-start position. - -Displaying a different buffer in the window also runs these functions. - -These functions cannot expect @code{window-end} (@pxref{Window Start}) -to return a meaningful value, because that value is updated only by -redisplaying the buffer. So if one of these functions needs to know the -last character that will fit in the window with its current -display-start position, it has to find that character using -@code{vertical-motion} (@pxref{Screen Lines}). -@end defvar - -@defvar window-size-change-functions -This variable holds a list of functions to be called if the size of any -window changes for any reason. The functions are called just once per -redisplay, and just once for each frame on which size changes have -occurred. - -Each function receives the frame as its sole argument. There is no -direct way to find out which windows on that frame have changed size, or -precisely how. However, if a size-change function records, at each -call, the existing windows and their sizes, it can also compare the -present sizes and the previous sizes. - -Creating or deleting windows counts as a size change, and therefore -causes these functions to be called. Changing the frame size also -counts, because it changes the sizes of the existing windows. - -It is not a good idea to use @code{save-window-excursion} (@pxref{Window -Configurations}) in these functions, because that always counts as a -size change, and it would cause these functions to be called over and -over. In most cases, @code{save-selected-window} (@pxref{Selecting -Windows}) is what you need here. -@end defvar - -@node Horizontal Scrolling -@section Horizontal Scrolling -@cindex horizontal scrolling - - Because we read English first from top to bottom and second from left -to right, horizontal scrolling is not like vertical scrolling. Vertical -scrolling involves selection of a contiguous portion of text to display. -Horizontal scrolling causes part of each line to go off screen. The -amount of horizontal scrolling is therefore specified as a number of -columns rather than as a position in the buffer. It has nothing to do -with the display-start position returned by @code{window-start}. - - Usually, no horizontal scrolling is in effect; then the leftmost -column is at the left edge of the window. In this state, scrolling to -the right is meaningless, since there is no data to the left of the -screen to be revealed by it; so this is not allowed. Scrolling to the -left is allowed; it scrolls the first columns of text off the edge of -the window and can reveal additional columns on the right that were -truncated before. Once a window has a nonzero amount of leftward -horizontal scrolling, you can scroll it back to the right, but only so -far as to reduce the net horizontal scroll to zero. There is no limit -to how far left you can scroll, but eventually all the text will -disappear off the left edge. - -@deffn Command scroll-left count -This function scrolls the selected window @var{count} columns to the -left (or to the right if @var{count} is negative). The return value is -the total amount of leftward horizontal scrolling in effect after the -change---just like the value returned by @code{window-hscroll} (below). -@end deffn - -@deffn Command scroll-right count -This function scrolls the selected window @var{count} columns to the -right (or to the left if @var{count} is negative). The return value is -the total amount of leftward horizontal scrolling in effect after the -change---just like the value returned by @code{window-hscroll} (below). - -Once you scroll a window as far right as it can go, back to its normal -position where the total leftward scrolling is zero, attempts to scroll -any farther right have no effect. -@end deffn - -@defun window-hscroll &optional window -This function returns the total leftward horizontal scrolling of -@var{window}---the number of columns by which the text in @var{window} -is scrolled left past the left margin. - -The value is never negative. It is zero when no horizontal scrolling -has been done in @var{window} (which is usually the case). - -If @var{window} is @code{nil}, the selected window is used. - -@example -@group -(window-hscroll) - @result{} 0 -@end group -@group -(scroll-left 5) - @result{} 5 -@end group -@group -(window-hscroll) - @result{} 5 -@end group -@end example -@end defun - -@defun set-window-hscroll window columns -This function sets the number of columns from the left margin that -@var{window} is scrolled to the value of @var{columns}. The argument -@var{columns} should be zero or positive; if not, it is taken as zero. - -The value returned is @var{columns}. - -@example -@group -(set-window-hscroll (selected-window) 10) - @result{} 10 -@end group -@end example -@end defun - - Here is how you can determine whether a given position @var{position} -is off the screen due to horizontal scrolling: - -@example -@group -(defun hscroll-on-screen (window position) - (save-excursion - (goto-char position) - (and - (>= (- (current-column) (window-hscroll window)) 0) - (< (- (current-column) (window-hscroll window)) - (window-width window))))) -@end group -@end example - -@node Size of Window -@section The Size of a Window -@cindex window size -@cindex size of window - - An Emacs window is rectangular, and its size information consists of -the height (the number of lines) and the width (the number of character -positions in each line). The mode line is included in the height. But -the width does not count the scroll bar or the column of @samp{|} -characters that separates side-by-side windows. - - The following three functions return size information about a window: - -@defun window-height &optional window -This function returns the number of lines in @var{window}, including -its mode line. If @var{window} fills its entire frame, this is one less -than the value of @code{frame-height} on that frame (since the last line -is always reserved for the minibuffer). - -If @var{window} is @code{nil}, the function uses the selected window. - -@example -@group -(window-height) - @result{} 23 -@end group -@group -(split-window-vertically) - @result{} #<window 4 on windows.texi> -@end group -@group -(window-height) - @result{} 11 -@end group -@end example -@end defun - -@defun window-width &optional window -This function returns the number of columns in @var{window}. If -@var{window} fills its entire frame, this is the same as the value of -@code{frame-width} on that frame. The width does not include the -window's scroll bar or the column of @samp{|} characters that separates -side-by-side windows. - -If @var{window} is @code{nil}, the function uses the selected window. - -@example -@group -(window-width) - @result{} 80 -@end group -@end example -@end defun - -@defun window-edges &optional window -This function returns a list of the edge coordinates of @var{window}. -If @var{window} is @code{nil}, the selected window is used. - -The order of the list is @code{(@var{left} @var{top} @var{right} -@var{bottom})}, all elements relative to 0, 0 at the top left corner of -the frame. The element @var{right} of the value is one more than the -rightmost column used by @var{window}, and @var{bottom} is one more than -the bottommost row used by @var{window} and its mode-line. - -When you have side-by-side windows, the right edge value for a window -with a neighbor on the right includes the width of the separator between -the window and that neighbor. This separator may be a column of -@samp{|} characters or it may be a scroll bar. Since the width of the -window does not include this separator, the width does not equal the -difference between the right and left edges in this case. - -Here is the result obtained on a typical 24-line terminal with just one -window: - -@example -@group -(window-edges (selected-window)) - @result{} (0 0 80 23) -@end group -@end example - -@noindent -The bottom edge is at line 23 because the last line is the echo area. - -If @var{window} is at the upper left corner of its frame, then -@var{bottom} is the same as the value of @code{(window-height)}, -@var{right} is almost the same as the value of -@code{(window-width)}@footnote{They are not exactly equal because -@var{right} includes the vertical separator line or scroll bar, while -@code{(window-width)} does not.}, and @var{top} and @var{left} are zero. -For example, the edges of the following window are @w{@samp{0 0 5 8}}. -Assuming that the frame has more than 8 columns, the last column of the -window (column 7) holds a border rather than text. The last row (row 4) -holds the mode line, shown here with @samp{xxxxxxxxx}. - -@example -@group - 0 - _______ - 0 | | - | | - | | - | | - xxxxxxxxx 4 - - 7 -@end group -@end example - -When there are side-by-side windows, any window not at the right edge of -its frame has a separator in its last column or columns. The separator -counts as one or two columns in the width of the window. A window never -includes a separator on its left, since that belongs to the window to -the left. - -In the following example, let's suppose that the frame is 7 -columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}} -and the edges of the right window are @w{@samp{4 0 7 3}}. - -@example -@group - ___ ___ - | | | - | | | - xxxxxxxxx - - 0 34 7 -@end group -@end example -@end defun - -@node Resizing Windows -@section Changing the Size of a Window -@cindex window resizing -@cindex changing window size -@cindex window size, changing - - The window size functions fall into two classes: high-level commands -that change the size of windows and low-level functions that access -window size. Emacs does not permit overlapping windows or gaps between -windows, so resizing one window affects other windows. - -@deffn Command enlarge-window size &optional horizontal -This function makes the selected window @var{size} lines taller, -stealing lines from neighboring windows. It takes the lines from one -window at a time until that window is used up, then takes from another. -If a window from which lines are stolen shrinks below -@code{window-min-height} lines, that window disappears. - -If @var{horizontal} is non-@code{nil}, this function makes -@var{window} wider by @var{size} columns, stealing columns instead of -lines. If a window from which columns are stolen shrinks below -@code{window-min-width} columns, that window disappears. - -If the requested size would exceed that of the window's frame, then the -function makes the window occupy the entire height (or width) of the -frame. - -If @var{size} is negative, this function shrinks the window by -@minus{}@var{size} lines or columns. If that makes the window smaller -than the minimum size (@code{window-min-height} and -@code{window-min-width}), @code{enlarge-window} deletes the window. - -@code{enlarge-window} returns @code{nil}. -@end deffn - -@deffn Command enlarge-window-horizontally columns -This function makes the selected window @var{columns} wider. -It could be defined as follows: - -@example -@group -(defun enlarge-window-horizontally (columns) - (enlarge-window columns t)) -@end group -@end example -@end deffn - -@deffn Command shrink-window size &optional horizontal -This function is like @code{enlarge-window} but negates the argument -@var{size}, making the selected window smaller by giving lines (or -columns) to the other windows. If the window shrinks below -@code{window-min-height} or @code{window-min-width}, then it disappears. - -If @var{size} is negative, the window is enlarged by @minus{}@var{size} -lines or columns. -@end deffn - -@deffn Command shrink-window-horizontally columns -This function makes the selected window @var{columns} narrower. -It could be defined as follows: - -@example -@group -(defun shrink-window-horizontally (columns) - (shrink-window columns t)) -@end group -@end example -@end deffn - -@cindex minimum window size - The following two variables constrain the window-size-changing -functions to a minimum height and width. - -@defopt window-min-height -The value of this variable determines how short a window may become -before it is automatically deleted. Making a window smaller than -@code{window-min-height} automatically deletes it, and no window may be -created shorter than this. The absolute minimum height is two (allowing -one line for the mode line, and one line for the buffer display). -Actions that change window sizes reset this variable to two if it is -less than two. The default value is 4. -@end defopt - -@defopt window-min-width -The value of this variable determines how narrow a window may become -before it automatically deleted. Making a window smaller than -@code{window-min-width} automatically deletes it, and no window may be -created narrower than this. The absolute minimum width is one; any -value below that is ignored. The default value is 10. -@end defopt - -@node Coordinates and Windows -@section Coordinates and Windows - -This section describes how to relate screen coordinates to windows. - -@defun window-at x y &optional frame -This function returns the window containing the specified cursor -position in the frame @var{frame}. The coordinates @var{x} and @var{y} -are measured in characters and count from the top left corner of the -frame. If they are out of range, @code{window-at} returns @code{nil}. - -If you omit @var{frame}, the selected frame is used. -@end defun - -@defun coordinates-in-window-p coordinates window -This function checks whether a particular frame position falls within -the window @var{window}. - -@need 3000 -The argument @var{coordinates} is a cons cell of this form: - -@example -(@var{x} . @var{y}) -@end example - -@noindent -The coordinates @var{x} and @var{y} are measured in characters, and -count from the top left corner of the screen or frame. - -The value of @code{coordinates-in-window-p} is non-@code{nil} if the -coordinates are inside @var{window}. The value also indicates what part -of the window the position is in, as follows: - -@table @code -@item (@var{relx} . @var{rely}) -The coordinates are inside @var{window}. The numbers @var{relx} and -@var{rely} are the equivalent window-relative coordinates for the -specified position, counting from 0 at the top left corner of the -window. - -@item mode-line -The coordinates are in the mode line of @var{window}. - -@item vertical-split -The coordinates are in the vertical line between @var{window} and its -neighbor to the right. This value occurs only if the window doesn't -have a scroll bar; positions in a scroll bar are considered outside the -window. - -@item nil -The coordinates are not in any part of @var{window}. -@end table - -The function @code{coordinates-in-window-p} does not require a frame as -argument because it always uses the frame that @var{window} is on. -@end defun - -@node Window Configurations -@section Window Configurations -@cindex window configurations -@cindex saving window information - - A @dfn{window configuration} records the entire layout of a -frame---all windows, their sizes, which buffers they contain, what part -of each buffer is displayed, and the values of point and the mark. You -can bring back an entire previous layout by restoring a window -configuration previously saved. - - If you want to record all frames instead of just one, use a frame -configuration instead of a window configuration. @xref{Frame -Configurations}. - -@defun current-window-configuration -This function returns a new object representing Emacs's current window -configuration, namely the number of windows, their sizes and current -buffers, which window is the selected window, and for each window the -displayed buffer, the display-start position, and the positions of point -and the mark. An exception is made for point in the current buffer, -whose value is not saved. -@end defun - -@defun set-window-configuration configuration -This function restores the configuration of Emacs's windows and -buffers to the state specified by @var{configuration}. The argument -@var{configuration} must be a value that was previously returned by -@code{current-window-configuration}. - -This function always counts as a window size change and triggers -execution of the @code{window-size-change-functions}. (It doesn't know -how to tell whether the new configuration actually differs from the old -one.) - -Here is a way of using this function to get the same effect -as @code{save-window-excursion}: - -@example -@group -(let ((config (current-window-configuration))) - (unwind-protect - (progn (split-window-vertically nil) - @dots{}) - (set-window-configuration config))) -@end group -@end example -@end defun - -@defspec save-window-excursion forms@dots{} -This special form records the window configuration, executes @var{forms} -in sequence, then restores the earlier window configuration. The window -configuration includes the value of point and the portion of the buffer -that is visible. It also includes the choice of selected window. -However, it does not include the value of point in the current buffer; -use @code{save-excursion} if you wish to preserve that. - -Don't use this construct when @code{save-selected-window} is all you need. - -Exit from @code{save-window-excursion} always triggers execution of the -@code{window-size-change-functions}. (It doesn't know how to tell -whether the restored configuration actually differs from the one in -effect at the end of the @var{forms}.) - -The return value is the value of the final form in @var{forms}. -For example: - -@example -@group -(split-window) - @result{} #<window 25 on control.texi> -@end group -@group -(setq w (selected-window)) - @result{} #<window 19 on control.texi> -@end group -@group -(save-window-excursion - (delete-other-windows w) - (switch-to-buffer "foo") - 'do-something) - @result{} do-something - ;; @r{The screen is now split again.} -@end group -@end example -@end defspec - -@defun window-configuration-p object -This function returns @code{t} if @var{object} is a window configuration. -@end defun - - Primitives to look inside of window configurations would make sense, -but none are implemented. It is not clear they are useful enough to be -worth implementing. |