diff options
| -rw-r--r-- | lispref/buffers.texi | 307 | ||||
| -rw-r--r-- | lispref/calendar.texi | 10 | ||||
| -rw-r--r-- | lispref/commands.texi | 44 | ||||
| -rw-r--r-- | lispref/compile.texi | 129 | ||||
| -rw-r--r-- | lispref/debugging.texi | 4 | ||||
| -rw-r--r-- | lispref/display.texi | 201 | ||||
| -rw-r--r-- | lispref/elisp.texi | 27 | ||||
| -rw-r--r-- | lispref/eval.texi | 4 | ||||
| -rw-r--r-- | lispref/files.texi | 144 | ||||
| -rw-r--r-- | lispref/frames.texi | 335 | ||||
| -rw-r--r-- | lispref/keymaps.texi | 27 | ||||
| -rw-r--r-- | lispref/lists.texi | 46 | ||||
| -rw-r--r-- | lispref/loading.texi | 14 | ||||
| -rw-r--r-- | lispref/macros.texi | 66 | ||||
| -rw-r--r-- | lispref/minibuf.texi | 20 | ||||
| -rw-r--r-- | lispref/modes.texi | 74 | ||||
| -rw-r--r-- | lispref/numbers.texi | 23 | ||||
| -rw-r--r-- | lispref/objects.texi | 63 | ||||
| -rw-r--r-- | lispref/os.texi | 216 | ||||
| -rw-r--r-- | lispref/processes.texi | 88 | ||||
| -rw-r--r-- | lispref/searching.texi | 157 | ||||
| -rw-r--r-- | lispref/sequences.texi | 11 | ||||
| -rw-r--r-- | lispref/strings.texi | 12 | ||||
| -rw-r--r-- | lispref/symbols.texi | 63 | ||||
| -rw-r--r-- | lispref/text.texi | 222 | ||||
| -rw-r--r-- | lispref/variables.texi | 46 | ||||
| -rw-r--r-- | lispref/windows.texi | 27 |
27 files changed, 1914 insertions, 466 deletions
diff --git a/lispref/buffers.texi b/lispref/buffers.texi index 4ce4c4c2037..bfa8f020c62 100644 --- a/lispref/buffers.texi +++ b/lispref/buffers.texi @@ -17,6 +17,8 @@ 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. @@ -26,8 +28,7 @@ not be displayed in any windows. * 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. +* Indirect Buffers:: An indirect buffer shares text with some other buffer. @end menu @node Buffer Basics @@ -75,6 +76,130 @@ 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 @@ -533,6 +658,12 @@ If @var{buffer-or-name} 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 @@ -589,8 +720,9 @@ An error is signaled if @var{name} is not a string. @end group @end example -The major mode for the new buffer is set according to the variable -@code{default-major-mode}. @xref{Auto Major Mode}. +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 @@ -618,8 +750,9 @@ An error is signaled if @var{name} is not a string. @end group @end example -The major mode for the new buffer is set by the value of -@code{default-major-mode}. @xref{Auto Major Mode}. +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}. @@ -713,126 +846,48 @@ variable @code{buffer-offer-save} automatically becomes buffer-local when set for any reason. @xref{Buffer-Local Variables}. @end defvar -@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. +@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 equivalent, 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 -@example -@group -(current-buffer) - @result{} #<buffer buffers.texi> -@end group -@end example +@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 -@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 diff --git a/lispref/calendar.texi b/lispref/calendar.texi index 5f49a5128e2..8e42a530f25 100644 --- a/lispref/calendar.texi +++ b/lispref/calendar.texi @@ -66,7 +66,10 @@ asterisk (@samp{*}). 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. +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 @@ -104,7 +107,10 @@ changing its face or by adding an asterisk. Here's how to use it: @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. +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 diff --git a/lispref/commands.texi b/lispref/commands.texi index e95b5599ad3..aa7ad7d2852 100644 --- a/lispref/commands.texi +++ b/lispref/commands.texi @@ -370,6 +370,12 @@ 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. @@ -766,6 +772,7 @@ This function returns non-@code{nil} if @var{event} is an input event. * 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. @@ -1223,6 +1230,34 @@ 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{deiconify-frame} event +@item (deiconify-frame (@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 iconified, Emacs has no work to do. +@end table + @node Event Examples @subsection Event Examples @@ -1835,6 +1870,9 @@ 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 @@ -2339,6 +2377,9 @@ encounters an error or a failing search. @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 X terminal and cannot be +buffer-local. @xref{Multiple Displays}. @end defvar @defvar executing-macro @@ -2354,5 +2395,8 @@ 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 X terminal and cannot be +buffer-local. @xref{Multiple Displays}. @end defvar diff --git a/lispref/compile.texi b/lispref/compile.texi index 69b328fd905..413adc085a3 100644 --- a/lispref/compile.texi +++ b/lispref/compile.texi @@ -22,8 +22,8 @@ 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 18, you can run the -compiled code in Emacs 19, but not vice versa. +particular, if you compile a program with Emacs 19.29, the compiled +code does not run in earlier versions. @xref{Compilation Errors}, for how to investigate errors occurring in byte compilation. @@ -31,6 +31,8 @@ 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. @@ -109,7 +111,7 @@ 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, + 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 @@ -221,10 +223,129 @@ 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 make 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 build 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: + +@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 + These features permit you to write code to be evaluated during compilation of a program. @defspec eval-and-compile body diff --git a/lispref/debugging.texi b/lispref/debugging.texi index 1b765970278..3fa300d02f9 100644 --- a/lispref/debugging.texi +++ b/lispref/debugging.texi @@ -89,6 +89,10 @@ 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 To debug an error that happens during loading of the @file{.emacs} diff --git a/lispref/display.texi b/lispref/display.texi index 2fc7340e035..146dee69531 100644 --- a/lispref/display.texi +++ b/lispref/display.texi @@ -14,7 +14,8 @@ that Emacs presents to the user. * Screen Size:: How big is the Emacs screen. * Truncation:: Folding or wrapping long text lines. * The Echo Area:: Where messages are displayed. -* Selective Display:: Hiding part of the buffer text. +* 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. @@ -168,12 +169,27 @@ If it is non-@code{nil}, these lines are truncated; otherwise, 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. + +@defvar cache-long-line-scans +If this variable is non-@code{nil}, various indentation and motion +functions, and Emacs redisplay, cache the results of their scans for +newlines, and consult the cache to avoid rescanning regions of the +buffer unless they are modified. + +Turning on the newline cache slows down processing of short lines. + +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 +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 @@ -187,7 +203,7 @@ functions with @code{t} as the stream (@pxref{Output Functions}), or as follows: @defun message string &rest arguments -This function prints a one-line message in the echo area. The +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 @@ -217,6 +233,21 @@ Minibuffer depth is 0. @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 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 @@ -227,6 +258,62 @@ 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 things 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 + @node Selective Display @section Selective Display @cindex selective display @@ -237,9 +324,13 @@ lines do not appear. 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 uses this variant. In the second variant, the -choice of lines to hide is made automatically based on indentation. -This variant is designed as a user-level feature. +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 as 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 @@ -370,12 +461,17 @@ given time. @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. +Many of the help commands use this feature. Nowadays you can do the +same job by creating an overlay with a @code{before-string} property. +@xref{Overlay Properties}. @defspec with-output-to-temp-buffer buffer-name forms@dots{} This function executes @var{forms} while arranging to insert any @@ -527,11 +623,18 @@ what they should mean. 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 character. 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. @xref{Faces}, for -more information. This feature is temporary; in the future, we may -replace it with other ways of specifying how to display text. +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)} @@ -543,39 +646,67 @@ the range of the overlay. This feature may be temporary, like @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. Each function receives three arguments: the -overlay, and the beginning and end of the part of the buffer being +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 at the same place.) + @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 -if text is inserted right at the beginning of the overlay. +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 if text is -inserted right at the end of the overlay. +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)} -A non-@code{nil} @code{invisible} property means that the text in the -overlay does not appear on the screen. This works much like selective -display. Details of this feature are likely to change in future -versions, so check the @file{etc/NEWS} file in the version you are -using. +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. + +@item intangible +@kindex intangible @r{(overlay property)} +The @code{intangible} property on an overlay works just like the +@code{intangible} text propert. @xref{Special Properties}, for details. @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. This is not yet implemented, but will be. +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. This is not yet implemented, but will be. +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). @end table These are the functions for reading and writing the properties of an @@ -583,8 +714,10 @@ overlay. @defun overlay-get overlay prop This function returns the value of property @var{prop} recorded in -@var{overlay}. If @var{overlay} does not record any value for that -property, then the value is @code{nil}. +@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 @@ -654,6 +787,11 @@ 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 @@ -667,6 +805,12 @@ 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. @@ -1051,9 +1195,10 @@ This creates and returns a display table. The table initially has 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}). Note that the -display table has no effect on the tab and newline characters; they are -always displayed as whitespace in their usual special fashion. +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. diff --git a/lispref/elisp.texi b/lispref/elisp.texi index ce4b7d542c2..e1e21b9417c 100644 --- a/lispref/elisp.texi +++ b/lispref/elisp.texi @@ -6,8 +6,8 @@ @c %**end of header @ifinfo -This version is the edition 2.3 of the GNU Emacs Lisp -Reference Manual. It corresponds to Emacs Version 19.25. +This version is the 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 @@ -15,7 +15,7 @@ Published by the Free Software Foundation 675 Massachusetts Avenue Cambridge, MA 02139 USA -Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +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 @@ -68,21 +68,20 @@ instead of in the original English. @subtitle for Unix Users @c The edition number appears in several places in this file @c and also in the file intro.texi. -@subtitle Second Edition, June 1993 -@subtitle Revision 2.3, June 1994 +@subtitle Revision 2.4, June 1995 @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 Free Software Foundation, Inc. +Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. @sp 2 -Edition 2.3 @* -Revised for Emacs Version 19.25,@* -June, 1994.@* +Edition 2.4 @* +Revised for Emacs Version 19.29,@* +June, 1995.@* @sp 2 -ISBN 1-882114-40-X +ISBN 1-882114-71-X @sp 2 Published by the Free Software Foundation @* @@ -113,8 +112,8 @@ Cover art by Etienne Suvasa. @node Top, Copying, (dir), (dir) @ifinfo -This Info file contains edition 2.3 of the GNU Emacs Lisp -Reference Manual, corresponding to GNU Emacs version 19.25. +This Info file contains edition 2.4 of the GNU Emacs Lisp +Reference Manual, corresponding to GNU Emacs version 19.29. @end ifinfo @menu @@ -268,7 +267,7 @@ Numbers * 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. -* Transcendental Functions:: Trig, exponential and logarithmic functions. +* Math Functions:: Trig, exponential and logarithmic functions. * Random Numbers:: Obtaining random integers, predictable or not. Strings and Characters @@ -707,7 +706,7 @@ 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. +* Low-Level Kill Ring:: Functions and variables for kill ring access. * Internals of Kill Ring:: Variables that hold kill-ring data. Indentation diff --git a/lispref/eval.texi b/lispref/eval.texi index 999f3b4b1c4..1bbd672f5fc 100644 --- a/lispref/eval.texi +++ b/lispref/eval.texi @@ -165,6 +165,10 @@ 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 diff --git a/lispref/files.texi b/lispref/files.texi index 7c7f20c2884..cfcab286d7b 100644 --- a/lispref/files.texi +++ b/lispref/files.texi @@ -34,6 +34,7 @@ substitutions such as @samp{$HOME}. @xref{File Name Expansion}. * 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 @@ -426,6 +427,10 @@ 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. + +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}. @end defun If you want to pass a file name to another process so that another @@ -488,6 +493,10 @@ Normally, @code{write-region} displays a message @samp{Wrote file 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. + +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}. @end deffn @node File Locks @@ -684,6 +693,11 @@ 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 @@ -787,6 +801,12 @@ existing directory, @code{nil} otherwise. @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) @@ -1309,6 +1329,12 @@ backup version numbers, or trailing tildes. @end example @end defun +@defun file-name-sans-extension filename +This function returns @var{filename} sans its final ``extension'', if +any. The extension, in a file name, is the part that follows the last +@samp{.}. +@end defun + @node Directory Names @comment node-name, next, previous, up @subsection Directory Names @@ -1944,6 +1970,124 @@ 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 are textual representations used in files for the data (text, +text-properties, and possibly other information) in an Emacs buffer. +Emacs performs format conversion 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-fm} 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}); but 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 holds a list of the file formats 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}. + +@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. +@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 diff --git a/lispref/frames.texi b/lispref/frames.texi index edcff7ea6fa..97d8e3e940a 100644 --- a/lispref/frames.texi +++ b/lispref/frames.texi @@ -14,11 +14,13 @@ horizontally into smaller windows. @cindex terminal frame @cindex X window frame - When Emacs runs on a text-only terminal, it has just one frame, a -@dfn{terminal frame}. There is no way to create another terminal frame -after startup. If Emacs has an X display, it does not have a terminal -frame; instead, it starts with a single @dfn{X window frame}. You can -create more; see @ref{Creating Frames}. + When Emacs runs on a text-only terminal, it starts with one +@dfn{terminal frames}. If you create additional ones, Emacs displays +one and only one at any given time---on the terminal screen, of course. + + When Emacs uses X for display, 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 @@ -26,8 +28,10 @@ This predicate returns @code{t} if @var{object} is a frame, and @end defun @menu -* Creating Frames:: Creating additional X Window 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; @@ -57,8 +61,8 @@ This predicate returns @code{t} if @var{object} is a frame, and To create a new frame, call the function @code{make-frame}. @defun make-frame alist -This function creates a new frame, if the display mechanism permits -creation of frames. (An X server does; an ordinary terminal does not.) +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 @@ -67,8 +71,7 @@ either 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 -when creating an X window frame. +Parameters}, for documentation of individual parameters you can specify. @end defun @defvar before-make-frame-hook @@ -80,6 +83,62 @@ frame. 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}, @code{multiple-frames} 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 display names (strings). +@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 second argument @var{xrm-string} should be a string of +resources in xrdb format, or @code{nil}. The resources, if specified, +apply to all Emacs frames created on this display. +@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 @@ -95,7 +154,7 @@ and width. @menu * Parameter Access:: How to change a frame's parameters. * Initial Parameters:: Specifying frame parameters when you make a frame. -* X Frame Parameters:: Individual parameters documented. +* X Frame Parameters:: List of frame parameters. * Size and Position:: Changing the size and position of a frame. @end menu @@ -180,7 +239,9 @@ instead. @xref{Command Arguments,,, emacs, The GNU Emacs Manual}. @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: +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 @@ -193,15 +254,32 @@ 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. The value may be -@code{-} instead of a number; that represents @samp{-0} in a geometry -specification. +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, counting toward the +left. @item top -The screen position of the top edge, in pixels. The value may be -@code{-} instead of a number; that represents @samp{-0} in a geometry -specification. +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, counting toward the +top. @item icon-left The screen position of the left edge @emph{of the frame's icon}, in @@ -237,6 +315,14 @@ yes, @code{nil} means no, @code{only} means this frame is just a minibuffer, a minibuffer window (in some other frame) means 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. @@ -256,6 +342,9 @@ 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. @@ -279,11 +368,12 @@ The color for the cursor that shows point. The color for the border of the frame. @item cursor-type -The way to display the cursor. There are two legitimate values: -@code{bar} and @code{box}. The symbol @code{bar} specifies a vertical -bar between characters as the cursor. The symbol @code{box} specifies -an ordinary black box overlaying the character after point; that is the -default. +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. @@ -376,9 +466,37 @@ 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 (+ @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 (- @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: + @smallexample (x-parse-geometry "35x70+0-0") - @result{} ((width . 35) (height . 70) (left . 0) (top . -1)) + @result{} ((width . 35) (height . 70) (left . 0) (top - 0)) @end smallexample @end defun @@ -388,6 +506,42 @@ 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. + +The variable is always local to the current X terminal and cannot be +buffer-local. @xref{Multiple Displays}. +@end defvar + @node Deleting Frames @section Deleting Frames @cindex deletion of frames @@ -409,6 +563,12 @@ 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 than 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 @@ -421,7 +581,8 @@ doesn't have any effect on the internals of Emacs. @defun visible-frame-list This function returns a list of just the currently visible frames. -@xref{Visibility of 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 @@ -502,6 +663,12 @@ 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 X terminal and cannot be +buffer-local. @xref{Multiple Displays}. +@end defvar + @node Input Focus @section Input Focus @cindex input focus @@ -524,12 +691,20 @@ 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}. + @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. 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. +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 @@ -583,10 +758,14 @@ change it. @cindex iconified frame @cindex frame visibility -A 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. +An X windo 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}, @@ -613,6 +792,11 @@ This returns the visibility status of frame @var{frame}. The value is 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 @@ -634,13 +818,13 @@ screen. You can raise and lower Emacs's X windows with these functions: -@defun raise-frame frame +@deffn Command raise-frame frame This function raises frame @var{frame}. -@end defun +@end deffn -@defun lower-frame frame +@deffn Command lower-frame frame This function lowers frame @var{frame}. -@end defun +@end deffn @defopt minibuffer-auto-raise If this is non-@code{nil}, activation of the minibuffer raises the frame @@ -771,6 +955,9 @@ characters. These coordinates are not required to be within the frame. @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. @@ -873,8 +1060,8 @@ pop-up menu in the center of the frame. @cindex pointer shape @cindex mouse pointer shape - These variables specify which mouse pointer shape to use in various -situations: + These variables specify which shape to use for the mouse pointer in +various situations: @table @code @item x-pointer-shape @@ -1072,68 +1259,74 @@ If you specify them, the key is @section Data about the X Server This section describes functions and a variable that you can use to -get information about the capabilities and origin of the X server that -Emacs is displaying its frames on. - -@defun x-display-screens -This function returns the number of screens associated with the current -display. +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, 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 -This function returns the list of version numbers of the X server in -use. +@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 -This function returns the vendor supporting the X server in use. +@defun x-server-vendor &optional display +This function returns the vendor that provided the X server software. @end defun -@defun x-display-pixel-height -This function returns the height of this X screen in pixels. +@defun x-display-pixel-height &optional display +This function returns the height of the screen in pixels. @end defun -@defun x-display-mm-height -This function returns the height of this X screen in millimeters. +@defun x-display-mm-height &optional display +This function returns the height of the screen in millimeters. @end defun -@defun x-display-pixel-width -This function returns the width of this X screen in pixels. +@defun x-display-pixel-width &optional display +This function returns the width of the screen in pixels. @end defun -@defun x-display-mm-width -This function returns the width of this X screen in millimeters. +@defun x-display-mm-width &optional display +This function returns the width of the screen in millimeters. @end defun -@defun x-display-backing-store -This function returns the backing store capability of this screen. +@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 -This function returns non-@code{nil} if this X screen supports the +@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 -This function returns the number of planes this display supports. +@defun x-display-planes &optional display +This function returns the number of planes the display supports. @end defun -@defun x-display-visual-class -This function returns the visual class for this X screen. The value is -one of the symbols @code{static-gray}, @code{gray-scale}, +@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-color-p -This function returns @code{t} if the X screen in use is a color -screen. +@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 -This function returns the number of color cells this X screen supports. +@defun x-display-color-cells &optional display +This function returns the number of color cells the screen supports. @end defun @ignore diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi index 7cce7ea7a2b..8e09e3e4dfc 100644 --- a/lispref/keymaps.texi +++ b/lispref/keymaps.texi @@ -582,6 +582,21 @@ keymap, if any, overrides all other maps that would have been active, except for the current global map. @end defvar +@defvar overriding-local-map-menu-flag +If this variable is non-@code{nil}, the value of +@code{overriding-local-map} can affect the display of the menu bar. The +default value is @code{nil}, so @code{overriding-local-map} has no +effect on the menu bar. + +Note that @code{overriding-local-map} does affect the execution of key +sequences entered using the menu bar, even if it does not affect the +menu bar display. So if a menu bar key sequence comes in, you should +clear @code{overriding-local-map} before looking up and executing that +key sequence. Modes that use @code{overriding-local-map} would +typically do this anyway; normally they respond to events that they do +not handle by ``unreading'' them and and exiting. +@end defvar + @node Key Lookup @section Key Lookup @cindex key lookup @@ -913,6 +928,13 @@ 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}. + 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 @@ -1585,6 +1607,11 @@ 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 diff --git a/lispref/lists.texi b/lispref/lists.texi index dcb3b8af9d5..55ce93c9547 100644 --- a/lispref/lists.texi +++ b/lispref/lists.texi @@ -554,34 +554,14 @@ 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. -Integers are also allowed as arguments to @code{append}. They are -converted to strings of digits making up the decimal print -representation of the integer, and these strings are then appended. -Here's what happens: - -@example -@group -(setq trees '(pine oak)) - @result{} (pine oak) -@end group -@group -(char-to-string 54) - @result{} "6" -@end group -@group -(setq longer-list (append trees 6 '(spruce))) - @result{} (pine oak 54 spruce) -@end group -@group -(setq x-list (append trees 6 6)) - @result{} (pine oak 54 . 6) -@end group -@end example - -This special case exists for compatibility with Mocklisp, and we don't -recommend you take advantage of it. If you want to convert an integer -in this way, use @code{format} (@pxref{Formatting Strings}) or -@code{number-to-string} (@pxref{String Conversion}). +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 @@ -1303,6 +1283,16 @@ Here is another example, in which the keys and values are not symbols: @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 diff --git a/lispref/loading.texi b/lispref/loading.texi index 8254107e710..645ada83976 100644 --- a/lispref/loading.texi +++ b/lispref/loading.texi @@ -101,6 +101,10 @@ 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 @@ -193,6 +197,15 @@ file, and it is @code{nil} otherwise. This is how @code{defun} and effect can be undone if the load fails. @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 @@ -326,7 +339,6 @@ convention used only in the preloaded Lisp files such as documentation string in the @file{etc/DOC} file. @xref{Building Emacs}. @node Repeated Loading -@comment node-name, next, previous, up @section Repeated Loading @cindex repeated loading diff --git a/lispref/macros.texi b/lispref/macros.texi index 71dc82f9e54..c5cf625c8c7 100644 --- a/lispref/macros.texi +++ b/lispref/macros.texi @@ -203,6 +203,7 @@ called interactively. @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 @@ -215,11 +216,11 @@ two forms yield identical results: @example @group -(` (a list of (+ 2 3) elements)) +`(a list of (+ 2 3) elements) @result{} (a list of (+ 2 3) elements) @end group @group -(quote (a list of (+ 2 3) elements)) +'(a list of (+ 2 3) elements) @result{} (a list of (+ 2 3) elements) @end group @end example @@ -235,7 +236,7 @@ argument of @code{,} and puts the value in the list structure: @result{} (a list of 5 elements) @end group @group -(` (a list of (, (+ 2 3)) elements)) +`(a list of ,(+ 2 3) elements) @result{} (a list of 5 elements) @end group @end example @@ -258,7 +259,7 @@ Here are some examples: @result{} (1 2 3 4 2 3) @end group @group -(` (1 (,@@ some-list) 4 (,@@ some-list))) +`(1 ,@@some-list 4 ,@@some-list) @result{} (1 2 3 4 2 3) @end group @@ -273,57 +274,22 @@ Here are some examples: @result{} (use the words foo bar as elements) @end group @group -(` (use the words (,@@ (cdr list)) as elements)) +`(use the words ,@@(cdr list) as elements) @result{} (use the words foo bar as elements) @end group @end example -Emacs 18 had a bug that made the previous example fail. The bug -affected @code{,@@} followed only by constant elements. If you are -concerned with Emacs 18 compatibility, you can work around the bug like -this: - -@example -(` (use the words (,@@ (cdr list)) as elements @code{(,@@ nil)})) -@end example - -@noindent -@code{(,@@ nil)} avoids the problem by being a nonconstant element that -does not affect the result. - -@defmac ` list -This macro quotes @var{list} except for any sublists of the form -@code{(, @var{subexp})} or @code{(,@@ @var{listexp})}. Backquote -replaces these sublists with the value of @var{subexp} (as a single -element) or @var{listexp} (by splicing). Backquote copies the structure -of @var{list} down to the places where variable parts are substituted. - -@ignore @c these work now! -There are certain contexts in which @samp{,} would not be recognized and -should not be used: - -@smallexample -@group -;; @r{Use of a @samp{,} expression as the @sc{cdr} of a list.} -(` (a . (, 1))) ; @r{Not @code{(a . 1)}} - @result{} (a \, 1) -@end group - -@group -;; @r{Use of @samp{,} in a vector.} -(` [a (, 1) c]) ; @r{Not @code{[a 1 c]}} - @error{} Wrong type argument -@end group -@end smallexample -@end ignore -@end defmac - -@cindex CL note---@samp{,}, @samp{,@@} as functions @quotation -@b{Common Lisp note:} In Common Lisp, @samp{,} and @samp{,@@} are -implemented as reader macros, so they do not require parentheses. In -Emacs Lisp they use function call syntax because reader macros are not -supported (for simplicity's sake). +Before Emacs version 19.29, @code{`} used a different syntax which +required an extra level of parentheses around the entire backquote +construct. Likewise, each @code{,} or @code{,@@} substition required an +extra level of parentheses surrounding both the @code{,} or @code{,@@} +and the following expression. The old syntax required whitespace +between the @code{`}, @code{,} or @code{,@@} 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 diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi index fa78ec1f8bd..10dc146535e 100644 --- a/lispref/minibuf.texi +++ b/lispref/minibuf.texi @@ -554,7 +554,7 @@ too short). Both of those begin with the string @samp{foobar}. @end smallexample @end defun -@defun all-completions string collection &optional predicate +@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}. @@ -563,6 +563,9 @@ 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}: @@ -1369,12 +1372,17 @@ 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 window that is used for the minibuffer. In -Emacs 18, there is one and only one minibuffer window; this window -always exists and cannot be deleted. In Emacs 19, each frame can have -its own minibuffer, and this function returns the minibuffer window used -for frame @var{frame} (which defaults to the currently selected 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 diff --git a/lispref/modes.texi b/lispref/modes.texi index b0b8263200a..1927797080b 100644 --- a/lispref/modes.texi +++ b/lispref/modes.texi @@ -547,6 +547,16 @@ 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} should 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 @@ -929,7 +939,8 @@ Force redisplay of the current buffer's mode line. 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. +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 @@ -1177,20 +1188,39 @@ The current buffer name, obtained with the @code{buffer-name} function. 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 percent of the buffer above the @strong{top} of window, or +The percentage of the buffer text above the @strong{top} of window, or @samp{Top}, @samp{Bottom} or @samp{All}. @item %P @@ -1353,7 +1383,7 @@ For example, here's how @code{emacs-lisp-hooks} runs its mode hook: @end example @end defun -@defun add-hook hook function &optional append +@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, @@ -1376,27 +1406,29 @@ 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 +@defun remove-hook hook function &optional local This function removes @var{function} from the hook variable @var{hook}. -@end defun -@ignore @c Should no longer be necessary -If you make a hook variable buffer-local, copy its value before you use -@code{add-hook} or @code{remove-hook} to change it. For example, +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 -@example -(defun my-major-mode () - @dots{} - (make-local-variable 'foo-hook) - (if (boundp 'foo-hook) - (setq foo-hook (copy-sequence foo-hook))) - (add-hook 'foo-hook 'my-foo-function)" - @dots{} - ) -@end example +@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. -Otherwise you may accidentally alter the list structure that forms part -of the global value of the hook variable. -@end ignore +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 index b3226c0f1cd..0c331545e1d 100644 --- a/lispref/numbers.texi +++ b/lispref/numbers.texi @@ -372,8 +372,8 @@ commonly used. 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+ 8388607)} may evaluate to -@minus{}8388608, depending on your hardware. +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. @@ -642,11 +642,11 @@ number. 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 8,388,607 -produces @minus{}2 on a 24-bit machine: +and change the sign of the number. For example, left shifting +134,217,727 produces @minus{}2 on a 28-bit machine: @example -(lsh 8388607 1) ; @r{left shift} +(lsh 134217727 1) ; @r{left shift} @result{} -2 @end example @@ -1009,8 +1009,17 @@ This function returns a pseudo-random integer. Repeated calls return a series of pseudo-random integers. If @var{limit} is @code{nil}, then the value may in principle be any -integer. If @var{limit} is a positive integer, the value is chosen to -be nonnegative and less than @var{limit} (only in Emacs 19). +integer. However, on machines where integers have more than 32 bits, +the possible values may be limited to the interval +@tex +$[0,2^{32})$. +@end tex +@ifinfo +[0,2**32). +@end ifinfo + +If @var{limit} is a positive integer, the value is chosen to be +nonnegative and less than @var{limit} (only in Emacs 19). 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. diff --git a/lispref/objects.texi b/lispref/objects.texi index 5d9762ee268..fc06466112c 100644 --- a/lispref/objects.texi +++ b/lispref/objects.texi @@ -1229,11 +1229,34 @@ pass an argument to @code{+} that it cannot handle: @cindex type predicates @cindex testing types - Lisp provides functions, called @dfn{type predicates}, to test whether -an object is a member of a given type. (Following a convention of long -standing, the names of most Emacs Lisp predicates end in @samp{p}.) + 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. -Here is a table of predefined type predicates, in alphabetical order, + 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))) + (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 @@ -1334,6 +1357,33 @@ with references to further information. @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 @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{window-configuration}, or +@code{process}. + +@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 @@ -1460,7 +1510,10 @@ arguments to see if their elements are the same. So, if two objects are @end group @end example -Comparison of strings uses @code{string=}, and is case-sensitive. +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 diff --git a/lispref/os.texi b/lispref/os.texi index e7b7b076e08..e39c6ca752c 100644 --- a/lispref/os.texi +++ b/lispref/os.texi @@ -20,6 +20,8 @@ pertaining to the terminal and the screen. * 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. @@ -598,6 +600,23 @@ This function returns the name of the machine you are running on. @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}, @@ -631,6 +650,13 @@ function works by modifying @code{process-environment}; binding that variable with @code{let} is also reasonable practice. @end deffn +@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 process-environment This variable is a list of strings, each describing one environment variable. The functions @code{getenv} and @code{setenv} work by means @@ -708,12 +734,21 @@ indicating whether the privilege is currently enabled. @node User Identification @section User Identification -@defun user-login-name -This function returns the name under which the user is logged in. If -the environment variable @code{LOGNAME} is set, that value is used. -Otherwise, if the environment variable @code{USER} is set, that value is -used. Otherwise, the value is based on the effective @sc{uid}, not the -real @sc{uid}. +@defvar user-mail-address +This holds the nominal email address of the user who is using Emacs. +When Emacs starts up, it computes a default value that is usually right, +but users often set this themselves when the default value is not right. +@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 @@ -740,6 +775,28 @@ This function returns the full name of the user. @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}). + +@defvar user-real-login-name +This variable holds the same value that the function +@code{user-real-login-name} returns. The variable lets you alter the value; +also, you can use variables for constructing frame titles. +@end defvar + +@defvar user-full-name +This variable holds the same value that the function +@code{user-full-name} returns. The variable lets you alter the value; +also, you can use variables for constructing frame titles. +@end defvar + @defun user-real-uid This function returns the real @sc{uid} of the user. @@ -825,7 +882,149 @@ The argument @var{time-value}, if given, specifies a time to analyze instead of the current time. The argument should be a cons cell containing two integers, or a list whose first two elements are integers. Thus, you can use times obtained from @code{current-time} -(see below) and from @code{file-attributes} (@pxref{File Attributes}). +(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}). + +@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 C locale, 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 C locale, it is equivalent +to @samp{%D}. +@item %X +This has a locale-specific meaning. In the C locale, 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 form. 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 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 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 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. @end defun @node Timers @@ -1271,6 +1470,9 @@ 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 diff --git a/lispref/processes.texi b/lispref/processes.texi index e71d7efeaaf..a089ba0994d 100644 --- a/lispref/processes.texi +++ b/lispref/processes.texi @@ -148,23 +148,52 @@ user types another @kbd{C-g}, that kills the subprocess instantly with 18. In version 19, they return an indication of how the process terminated. -@defun call-process program &optional infile buffer-or-name display &rest args +@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 -process output gets inserted in buffer @var{buffer-or-name} before point, -if that argument names a buffer. If @var{buffer-or-name} is @code{t}, -output is sent to the current buffer; if @var{buffer-or-name} is -@code{nil}, output is discarded. - -If @var{buffer-or-name} is the integer 0, @code{call-process} returns -@code{nil} immediately and discards any output. In this case, the -process is not truly synchronous, since it can run in parallel with -Emacs; but you can think of it as synchronous in that Emacs is -essentially finished with the subprocess as soon as this function -returns. +@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 or create a 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 @@ -216,16 +245,16 @@ of @code{call-process}: @end smallexample @end defun -@defun call-process-region start end program &optional delete buffer-or-name display &rest args +@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{buffer-or-name} and @var{display} control what to do +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{buffer-or-name} is the integer 0, +@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. @@ -241,7 +270,7 @@ In the following example, we use @code{call-process-region} to run the @code{cat} utility, with standard input being the first five characters in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its standard input into its standard output. Since the argument -@var{buffer-or-name} is @code{t}, this output is inserted in the current +@var{destination} is @code{t}, this output is inserted in the current buffer. @smallexample @@ -390,6 +419,10 @@ with one subprocess by binding the variable around the call to (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 @@ -560,6 +593,13 @@ 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 @@ -846,6 +886,13 @@ 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 +programs 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 @@ -1057,6 +1104,13 @@ 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}. + 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}. + @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. diff --git a/lispref/searching.texi b/lispref/searching.texi index ec082152aad..7919804d35c 100644 --- a/lispref/searching.texi +++ b/lispref/searching.texi @@ -17,6 +17,7 @@ portions of it. * 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. @@ -226,12 +227,12 @@ 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, @samp{\(x+y*\)*a} could take hours 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. +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 @@ -715,6 +716,48 @@ comes back" twice. @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 @@ -909,34 +952,56 @@ match data around it, to prevent it from being overwritten. @node Simple Match Data @subsection Simple Match Data Access - This section explains how to use the match data to find the starting -point or ending point of the text that was matched by a particular -search, or by a particular parenthetical subexpression of a regular -expression. + 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, 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 text matched by the whole regexp. Otherwise, @var{count}, specifies -a subexpression in the regular expresion. The value of the function is -the starting position of the match for that subexpression. - -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. - -The value is @code{nil} for a subexpression inside a -@samp{\|} alternative that wasn't used in the match. +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 returns the position of the end of the text that matched -the last regular expression searched for, or a subexpression of it. -This function is otherwise similar to @code{match-beginning}. +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 @@ -951,6 +1016,15 @@ positions within the text: @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 @@ -1004,11 +1078,15 @@ character of the buffer counts as 1.) @var{replacement}. @cindex case in replacements -@defun replace-match replacement &optional fixedcase literal -This function replaces the buffer text matched by the last search, with -@var{replacement}. It applies only to buffers; you can't use -@code{replace-match} to replace a substring found with -@code{string-match}. +@defun replace-match replacement &optional fixedcase literal string +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 @var{string} is @code{nil}, @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 @var{string} is a string, it 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 @@ -1044,9 +1122,6 @@ Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}. @cindex @samp{\} in replacement @samp{\\} stands for a single @samp{\} in the replacement text. @end table - -@code{replace-match} leaves point at the end of the replacement text, -and returns @code{t}. @end defun @node Entire Match Data @@ -1239,19 +1314,27 @@ 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 left margin, they accept +matches that start after the left margin. In that case, a @samp{^} +would be incorrect. + @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. +@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. +@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 diff --git a/lispref/sequences.texi b/lispref/sequences.texi index c1e7f3dc2d0..0982b19c743 100644 --- a/lispref/sequences.texi +++ b/lispref/sequences.texi @@ -462,11 +462,12 @@ existing vector. @end group @end example -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. This special case exists for -compatibility with Mocklisp, and we don't recommend you take advantage -of it. If you want to convert an integer to digits in this way, use +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}). diff --git a/lispref/strings.texi b/lispref/strings.texi index 1ca59d81f69..a0321476dc0 100644 --- a/lispref/strings.texi +++ b/lispref/strings.texi @@ -218,10 +218,10 @@ 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. @string{Don't use this feature---it -exists for historical compatibility only, and we plan to change it by -and by.} If you wish to convert an integer to a decimal number in this -way, use @code{format} (@pxref{Formatting Strings}) or +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 @@ -270,6 +270,10 @@ match exactly; case is significant. (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 diff --git a/lispref/symbols.texi b/lispref/symbols.texi index f3d13ebdad7..caba9a9bd7e 100644 --- a/lispref/symbols.texi +++ b/lispref/symbols.texi @@ -350,6 +350,20 @@ 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 @@ -379,6 +393,16 @@ objects, but the names are usually symbols. They are compared using 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 @@ -408,12 +432,15 @@ 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}. +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. @@ -458,3 +485,37 @@ The @code{put} function returns @var{value}. @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 +stored in the property list @var{plist}. It may modify @var{plist} +destructively, or it may construct 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/text.texi b/lispref/text.texi index 6153bdb69f1..eefd2c30259 100644 --- a/lispref/text.texi +++ b/lispref/text.texi @@ -156,6 +156,11 @@ 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 ---------- @@ -176,6 +181,24 @@ This is the contents of buffer foo @end example @end defun +@defun buffer-substring-without-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 @@ -343,18 +366,17 @@ it except to install it on a keymap. In an interactive call, @var{count} is the numeric prefix argument. -This function calls @code{auto-fill-function} if the current column number -is greater than the value of @code{fill-column} and the character -inserted is a space (@pxref{Auto Filling}). +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 function performs abbrev expansion if Abbrev mode is enabled and +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 function is also responsible for calling -@code{blink-paren-function} when the inserted character has close -parenthesis syntax (@pxref{Blinking}). +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 @@ -710,6 +732,9 @@ the kill ring, but does not delete the text from the buffer. It returns @code{nil}. It also indicates the extent of the text copied by moving the cursor momentarily, or by displaying a message in the echo area. +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}. @@ -1073,8 +1098,11 @@ specified width. The width is controlled by the variable automatically as you insert it, but changes to existing text may leave it improperly filled. Then you must fill the text explicitly. - Most of the functions in this section return values that are not -meaningful. + 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. If +the current justification style is @code{none}, the filling functions +don't actually do anything. @deffn Command fill-paragraph justify-flag @cindex filling a paragraph @@ -1123,8 +1151,11 @@ described above. This command considers a region of text as a paragraph and fills it. If the region was made up of many paragraphs, the blank lines between paragraphs are removed. This function justifies as well as filling when -@var{justify-flag} is non-@code{nil}. In an interactive call, any -prefix argument requests justification. +@var{justify-flag} is non-@code{nil}. The precise value of +@var{justify-flag} specifies a style of justification, as in +@code{justify-current-line}, below. + +In an interactive call, any prefix argument requests justification. In Adaptive Fill mode, which is enabled by default, @code{fill-region-as-paragraph} on an indented paragraph when there is @@ -1132,12 +1163,38 @@ no fill prefix uses the indentation of the second line of the paragraph as the fill prefix. @end deffn -@deffn Command justify-current-line +@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 when +@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}. +@end defopt + +@defun current-justification +This function returns the proper justification style to use for filling +the text around point. +@end defun + @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 @@ -1168,6 +1225,67 @@ buffers that do not override it. This is the same as The default value for @code{default-fill-column} is 70. @end defvar +@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 + +@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{fill-colmn} property on the text from @var{from} to +@var{to} so as to yield a right margin of width @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), plus 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 specified, +@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 + @node Auto Filling @comment node-name, next, previous, up @section Auto Filling @@ -1180,10 +1298,9 @@ For a description of functions that you can call explicitly to fill and justify existing text, see @ref{Filling}. @defvar auto-fill-function -The value of this variable should be a function (of no arguments) to -be called after self-inserting a space at a column beyond -@code{fill-column}. It may be @code{nil}, in which case nothing -special is done. +The value of 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 @@ -1935,6 +2052,7 @@ along with the characters; this includes such diverse functions as * 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 @@ -1986,6 +2104,22 @@ This function returns the entire property list of the character at @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, 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 @@ -2068,6 +2202,10 @@ from the specified range of text. Here's an example: @end example @end defun +See also the function @code{buffer-substring-without-properties} +(@pxref{Buffer Contents}) which copies text from the buffer +but does not copy its properties. + @node Property Search @subsection Property Search Functions @@ -2188,9 +2326,9 @@ of the symbol serve as defaults for the properties of the character. @cindex face codes of text @kindex face @r{(text property)} You can use the property @code{face} to control the font and color of -text. @xref{Faces}, for more information. This feature is temporary; -in the future, we may replace it with other ways of specifying how to -display text. +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)} @@ -2225,16 +2363,19 @@ and then remove the property. @xref{Read Only Buffers}. @item invisible @kindex invisible @r{(text property)} -A non-@code{nil} @code{invisible} property means a character does not -appear on the screen. This works much like selective display. Details -of this feature are likely to change in future versions, so check the -@file{etc/NEWS} file in the version you are using. +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)} -A non-@code{nil} @code{intangible} property on a character prevents -putting point before that character. If you try, point actually goes -after the character (and after all succeeding intangible characters). +If a group of consecutive characters have equal and non-@code{nil} +@code{intangible} properties, then you cannot place point between them. +If you 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 @@ -2298,9 +2439,36 @@ value of point runs these hook functions. @defvar inhibit-point-motion-hooks When this variable is non-@code{nil}, @code{point-left} and -@code{point-entered} hooks are not run. +@code{point-entered} hooks are not run, and the @code{intangible} +property has no effect. @end defvar +@node Format Properties +@section Formatted Text Properties + + These text properties affect the behavior of the fill commands. They +are used for representing formatted text. @xref{Filling}. + +@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 the right margin for filling this part of the +text. + +@item left-margin +This property specifies the 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 diff --git a/lispref/variables.texi b/lispref/variables.texi index cc69742be50..fb08a390c6d 100644 --- a/lispref/variables.texi +++ b/lispref/variables.texi @@ -708,6 +708,39 @@ 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. The value of @var{symbol} had better be a list already. + +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 @@ -921,7 +954,8 @@ 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. +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. @@ -1072,6 +1106,9 @@ 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. + +@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 @@ -1116,6 +1153,12 @@ 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 +@defun local-variable-p variable +This returns @code{t} if @var{variable} is buffer-local in the current +buffer. It is much faster to get the answer this way than to examine +the value of @code{buffer-local-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 @@ -1277,4 +1320,3 @@ evaluated. @end group @end example @end defun - diff --git a/lispref/windows.texi b/lispref/windows.texi index 708862ab18b..b1dcd2d6e0e 100644 --- a/lispref/windows.texi +++ b/lispref/windows.texi @@ -659,8 +659,10 @@ 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. +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 @@ -715,7 +717,9 @@ already displayed in the selected window and @var{other-window} is for @var{buffer-or-name}, so that nothing needs to be done. If @var{buffer-or-name} is a string that does not name an existing -buffer, a buffer by that name is created. +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 @node Choosing Window @@ -1520,6 +1524,23 @@ created narrower than this. The absolute minimum width is one; any value below that is ignored. The default value is 10. @end defopt +@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 changed size, or precisely how; +however, if your size-change function keeps track, after each change, of +the windows that interest you, you can figure out what has changed by +comparing the old size data with the new. + +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. +@end defvar + @node Coordinates and Windows @section Coordinates and Windows |