diff options
Diffstat (limited to 'doc/lispref')
39 files changed, 4536 insertions, 1014 deletions
diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 1fe5a60b356..6a1d125701c 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -541,10 +541,12 @@ file formerly visited. @ref{Text}. @defun buffer-modified-p &optional buffer -This function returns @code{t} if the buffer @var{buffer} has been modified -since it was last read in from a file or saved, or @code{nil} -otherwise. If @var{buffer} is not supplied, the current buffer -is tested. +This function returns non-@code{nil} if @var{buffer} has +been modified since it was last read in from a file or saved, or +@code{nil} otherwise. If @var{buffer} has been auto-saved since the +time it was last modified, this function returns the symbol +@code{autosaved}. If @var{buffer} is @code{nil} or omitted, it +defaults to the current buffer. @end defun @defun set-buffer-modified-p flag @@ -563,8 +565,10 @@ function @code{force-mode-line-update} works by doing this: @end defun @defun restore-buffer-modified-p flag -Like @code{set-buffer-modified-p}, but does not force redisplay -of mode lines. +Like @code{set-buffer-modified-p}, but does not force redisplay of +mode lines. This function also allows @var{flag}'s value to be +the symbol @code{autosaved}, which marks the buffer as modified and +auto-saved after the last modification. @end defun @deffn Command not-modified &optional arg @@ -953,15 +957,67 @@ with a @code{nil} @var{norecord} argument since this may lead to infinite recursion. @end defvar +@defun buffer-match-p condition buffer-or-name &optional arg +This function checks if a buffer designated by @code{buffer-or-name} +satisfies a @code{condition}. Optional third argument @var{arg} is +passed to the predicate function in @var{condition}. A condition can +be one of the following: +@itemize @bullet{} +@item +A string, interpreted as a regular expression. The buffer +satisfies the condition if the regular expression matches the buffer +name. +@item +A predicate function, which should return non-@code{nil} if the buffer +matches. If the function expects one argument, it is called with +@var{buffer-or-name} as the argument; if it expects 2 arguments, the +first argument is @var{buffer-or-name} and the second is @var{arg} +(or @code{nil} if @var{arg} is omitted). +@item +A cons-cell @code{(@var{oper} . @var{expr})} where @var{oper} is one +of +@table @code +@item not +Satisfied if @var{expr} doesn't satisfy @code{buffer-match-p} with +the same buffer and @code{arg}. +@item or +Satisfied if @var{expr} is a list and @emph{any} condition in +@var{expr} satisfies @code{buffer-match-p}, with the same buffer and +@code{arg}. +@item and +Satisfied if @var{expr} is a list and @emph{all} conditions in +@var{expr} satisfy @code{buffer-match-p}, with the same buffer and +@code{arg}. +@item derived-mode +Satisfied if the buffer's major mode derives from @var{expr}. +@item major-mode +Satisfied if the buffer's major mode is equal to @var{expr}. Prefer +using @code{derived-mode} instead when both can work. +@end table +@item t +Satisfied by any buffer. A convenient alternative to @code{""} (empty +string), @code{(and)} (empty conjunction) or @code{always}. +@end itemize +@end defun + +@defun match-buffers condition &optional buffer-list arg +This function returns a list of all buffers that satisfy a +@code{condition}, as defined for @code{buffer-match-p}. By default +all buffers are considered, but this can be restricted via the second +optional @code{buffer-list} argument. Optional third argument +@var{arg} will be used by @var{condition} in the same way as +@code{buffer-match-p} does. +@end defun + @node Creating Buffers @section Creating Buffers @cindex creating buffers @cindex buffers, creating This section describes the two primitives for creating buffers. -@code{get-buffer-create} creates a buffer if it finds no existing buffer -with the specified name; @code{generate-new-buffer} always creates a new -buffer and gives it a unique name. +@code{get-buffer-create} creates a buffer if it finds no existing +buffer with the specified name; @code{generate-new-buffer} always +creates a new buffer and gives it a unique name. Both functions accept an optional argument @var{inhibit-buffer-hooks}. If it is non-@code{nil}, the buffer they create does not run the hooks diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index d948af6b4f1..ede1c4d7622 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -312,6 +312,25 @@ If @var{function} is an interactively callable function specifies how to compute its arguments. Otherwise, the value is @code{nil}. If @var{function} is a symbol, its function definition is used. +When called on an OClosure, the work is delegated to the generic +function @code{oclosure-interactive-form}. +@end defun + +@defun oclosure-interactive-form function +Just like @code{interactive-form}, this function takes a command and +returns its interactive form. The difference is that it is a generic +function and it is only called when @var{function} is an OClosure. +The purpose is to make it possible for some OClosure types to compute +their interactive forms dynamically instead of carrying it in one of +their slots. + +This is used for example for @code{kmacro} functions in order to +reduce their memory size, since they all share the same interactive +form. It is also used for @code{advice} functions, where the +interactive form is computed from the interactive forms of its +components, so as to make this computation more lazily and to +correctly adjust the interactive form when one of its component's +is redefined. @end defun @node Interactive Codes @@ -424,9 +443,9 @@ specification. If the key sequence that invoked the command has and @acronym{ASCII} characters, do not count where @samp{e} is concerned. @item f -A file name of an existing file (@pxref{File Names}). The default -directory is @code{default-directory}. Existing, Completion, Default, -Prompt. +A file name of an existing file (@pxref{File Names}). @xref{Reading +File Names}, for details about default values. Existing, Completion, +Default, Prompt. @item F A file name. The file need not exist. Completion, Default, Prompt. @@ -451,11 +470,11 @@ reads and discards the following up-event. You can get access to that up-event with the @samp{U} code character. This kind of input is used by commands such as @code{describe-key} and -@code{global-set-key}. +@code{keymap-global-set}. @item K A key sequence on a form that can be used as input to functions like -@code{define-key}. This works like @samp{k}, except that it +@code{keymap-set}. 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 (@pxref{Key Sequence Input}), so this @@ -682,11 +701,6 @@ different ways (e.g., @code{eww-open-in-new-buffer} and mode-specific, as they can be issued by the user from pretty much any context. -Note that specifying command modes is not supported in native-compiled -functions in Emacs 28.1 (but this is fixed in later Emacs versions). -This means that @code{read-extended-command-predicate} isn't supported -in native-compile builds, either. - @node Generic Commands @subsection Select among Command Alternatives @cindex generic commands @@ -883,6 +897,10 @@ keymaps. This command is the normal definition of @kbd{M-S-x} (that's ``meta shift x''). @end deffn +Both these commands prompt for a command name, but with different +completion rules. You can toggle between these two modes by using the +@kbd{M-S-x} command while being prompted. + @node Distinguish Interactive @section Distinguish Interactive Calls @cindex distinguish interactive calls @@ -1132,6 +1150,96 @@ frame, the value is the frame to which the event was redirected. If the last event came from a keyboard macro, the value is @code{macro}. @end defvar +@cindex input devices +@cindex device names +Input events must come from somewhere; sometimes, that is a keyboard +macro, a signal, or `unread-command-events', but it is usually a +physical input device connected to a computer that is controlled by +the user. Those devices are referred to as @dfn{input devices}, and +Emacs associates each input event with the input device from which it +originated. They are identified by a name that is unique to each +input device. + +The ability to determine the precise input device used depends on the +details of each system. When that information is unavailable, Emacs +reports keyboard events as originating from the @samp{"Virtual core +keyboard"}, and other events as originating from the @samp{"Virtual +core pointer"}. (These values are used on every platform because the +X server reports them when detailed device information is not known.) + +@defvar last-event-device +This variable records the name of the input device from which the last +input event read was generated. It is @code{nil} if no such device +exists, i.e., the last input event was read from +@code{unread-command-events}, or it came from a keyboard macro. + +When the X Input Extension is being used on X Windows, the device name +is a string that is unique to each physical keyboard, pointing device +and touchscreen attached to the X server. Otherwise, it is either the +string @samp{"Virtual core pointer"} or @samp{"Virtual core +keyboard"}, depending on whether the event was generated by a pointing +device (such as a mouse) or a keyboard. +@end defvar + +@defun device-class frame name +There are various different types of devices, which can be determined +from their names. This function can be used to determined the correct +type of the device @var{name} for an event originating from +@var{frame}. + +The return value is one of the following symbols (``device classes''): + +@table @code +@item core-keyboard +The core keyboard; this is means the device is a keyboard-like device, +but no other characteristics are unknown. + +@item core-pointer +The core pointer; this means the device is a pointing device, but no +other characteristics are known. + +@item mouse +A computer mouse. + +@item trackpoint +A trackpoint or joystick (or other similar control.) + +@item eraser +The other end of a stylus on a graphics tablet, or a standalone +eraser. + +@item pen +The pointed end of a pen on a graphics tablet, a stylus, or some other +similar device. + +@item puck +A device that looks like a computer mouse, but reports absolute +coordinates relative to some other surface. + +@item power-button +A power button or volume button (or other similar control.) + +@item keyboard +A computer keyboard. + +@item touchscreen +A computer touchpad. + +@item pad +A collection of sensitive buttons, rings, and strips commonly found +around a drawing tablet. + +@item touchpad +An indirect touch device such as a touchpad. + +@item piano +A musical instrument such as an electronic keyboard. + +@item test +A device used by the XTEST extension to report input. +@end table +@end defun + @node Adjusting Point @section Adjusting Point After Commands @cindex adjusting point @@ -1192,7 +1300,9 @@ intended by Lisp code to be used as an event. * Button-Down Events:: A button was pushed and not yet released. * Repeat Events:: Double and triple click (or drag, or down). * Motion Events:: Just moving the mouse, not pushing a button. +* Touchscreen Events:: Tapping and moving fingers on a touchscreen. * Focus Events:: Moving the mouse between frames. +* Xwidget Events:: Events generated by xwidgets. * Misc Events:: Other events the system can generate. * Event Examples:: Examples of the lists for mouse events. * Classifying Events:: Finding the modifier keys in an event symbol. @@ -1331,12 +1441,9 @@ actually treated as the meta key, not this.) It is best to avoid mentioning specific bit numbers in your program. To test the modifier bits of a character, use the function @code{event-modifiers} (@pxref{Classifying Events}). When making key -bindings, you can use the read syntax for characters with modifier bits -(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with -@code{define-key}, you can use lists such as @code{(control hyper ?x)} to -specify the characters (@pxref{Changing Key Bindings}). The function -@code{event-convert-list} converts such a list into an event type -(@pxref{Classifying Events}). +bindings with @code{keymap-set}, you specify these events using +strings like @samp{C-H-x} instead (for ``control hyper x'') +(@pxref{Changing Key Bindings}). @node Function Keys @subsection Function Keys @@ -1854,6 +1961,59 @@ small movements. Otherwise, motion events are not generated as long as the mouse cursor remains pointing to the same glyph in the text. @end defvar +@node Touchscreen Events +@subsection Touchscreen Events +@cindex touchscreen events +@cindex support for touchscreens + +Some window systems provide support for input devices that react to +the user's touching the screen and moving fingers while touching the +screen. These input devices are known as touchscreens, and Emacs +reports the events they generate as @dfn{touchscreen events}. + +Most individual events generated by a touchscreen only have meaning as +part of a larger sequence of other events: for instance, the simple +operation of tapping the touchscreen involves the user placing and +raising a finger on the touchscreen, and swiping the display to +scroll it involves placing a finger, moving it many times upwards or +downwards, and then raising the finger. + +@cindex touch point, in touchscreen events +While a simplistic model consisting of one finger is adequate for taps +and scrolling, more complicated gestures require support for keeping +track of multiple fingers, where the position of each finger is +represented by a @dfn{touch point}. For example, a ``pinch to zoom'' +gesture might consist of the user placing two fingers and moving them +individually in opposite directions, where the distance between the +positions of their individual points determine the amount by which to +zoom the display, and the center of an imaginary line between those +positions determines where to pan the display after zooming. + +The low-level touchscreen events described below can be used to +implement all the touch sequences described above. In those events, +each point is represented by a cons of an arbitrary number identifying +the point and a mouse position list (@pxref{Click Events}) specifying +the position of the finger when the event occurred. + +@table @code +@cindex @code{touchscreen-begin} event +@item (touchscreen-begin @var{point}) +This event is sent when @var{point} is created by the user pressing a +finger against the touchscreen. + +@cindex @code{touchscreen-update} event +@item (touchscreen-update @var{points}) +This event is sent when a point on the touchscreen has changed +position. @var{points} is a list of touch points containing the +up-to-date positions of each touch point currently on the touchscreen. + +@cindex @code{touchscreen-end} event +@item (touchscreen-end @var{point}) +This event is sent when @var{point} is no longer present on the +display, because another program took the grab, or because the user +raised the finger from the touchscreen. +@end table + @node Focus Events @subsection Focus Events @cindex focus event @@ -1890,6 +2050,100 @@ 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 Xwidget Events +@subsection Xwidget events + +Xwidgets (@pxref{Xwidgets}) can send events to update Lisp programs on +their status. These events are dubbed @code{xwidget-events}, and +contain various data describing the nature of the change. + +@table @code +@cindex @code{xwidget-event} event +@item (xwidget-event @var{kind} @var{xwidget} @var{arg}) +This event is sent whenever some kind of update occurs in +@var{xwidget}. There are several types of updates, identified by +their @var{kind}. + +@cindex xwidget callbacks +It is a special event (@pxref{Special Events}), which should be +handled by adding a callback to an xwidget that is called whenever an +xwidget event for @var{xwidget} is received. + +You can add a callback by setting the @code{callback} of an xwidget's +property list, which should be a function that accepts @var{xwidget} +and @var{kind} as arguments. + +@table @code +@cindex @code{load-changed} xwidget event +@item load-changed +This xwidget event indicates that the @var{xwidget} has reached a +particular point of the page-loading process. When these events are +sent, @var{arg} will contain a string that further describes the status +of the widget: + +@table @samp +@cindex @samp{load-started} in xwidgets +@item load-started +This means the widget has begun a page-loading operation. + +@cindex @samp{load-finished} in xwidgets +@item load-finished +This means the @var{xwidget} has finished processing whatever +page-loading operation that it was previously performing. + +@cindex @samp{load-redirected} in xwidgets +@item load-redirected +This means the @var{xwidget} has encountered and followed a redirect +during the page-loading operation. + +@cindex @samp{load-committed} in xwidgets +@item load-committed +This means the @var{xwidget} has committed to a given URL during the +page-loading operation, i.e.@: the URL is the final URL that will be +rendered by @var{xwidget} during the current page-loading operation. +@end table + +@cindex @code{download-callback} xwidget events +@item download-callback +This event indicates that a download of some kind has been completed. +@end table + +In the above events, there can be arguments after @var{arg}, which +itself indicates the URL from which the download file was retrieved: +the first argument after @var{arg} indicates the MIME type of the +download, as a string, while the second argument contains the full +file name of the downloaded file. + +@table @code +@cindex @code{download-started} xwidget events +@item download-started +This event indicates that a download has been started. In these +events, @var{arg} contains the URL of the file that is currently being +downloaded. + +@cindex @code{javascript-callback} xwidget events +@item javascript-callback +This event contains JavaScript callback data. These events are used +internally by @code{xwidget-webkit-execute-script}. +@end table + +@cindex @code{xwidget-display-event} event +@item (xwidget-display-event @var{xwidget} @var{source}) +This event is sent whenever an xwidget requests that another xwidget +be displayed. @var{xwidget} is the xwidget that should be displayed, +and @var{source} is the xwidget that asked to display @var{xwidget}. + +It is also a special event which should be handled through callbacks. +You can add such a callback by setting the @code{display-callback} of +@var{source}'s property list, which should be a function that accepts +@var{xwidget} and @var{source} as arguments. + +@var{xwidget}'s buffer will be set to a temporary buffer. When +displaying the widget, care should be taken to replace the buffer with +the buffer in which the xwidget will be displayed, using +@code{set-xwidget-buffer} (@pxref{Xwidgets}). +@end table + @node Misc Events @subsection Miscellaneous System Events @@ -1917,22 +2171,128 @@ This kind of event indicates that the user deiconified @var{frame} using the window manager. Its standard definition is @code{ignore}; since the frame has already been made visible, Emacs has no work to do. +@cindex @code{touch-end} event +@item (touch-end (@var{position})) +This kind of event indicates that the user's finger moved off the +mouse wheel or the touchpad. The @var{position} element is a mouse +position list (@pxref{Click Events}), specifying the position of the +mouse cursor when the finger moved off the mouse wheel. + @cindex @code{wheel-up} event @cindex @code{wheel-down} event -@item (wheel-up @var{position}) -@itemx (wheel-down @var{position}) +@item (wheel-up @var{position} @var{clicks} @var{lines} @var{pixel-delta}) +@itemx (wheel-down @var{position} @var{clicks} @var{lines} @var{pixel-delta}) These kinds of event are generated by moving a mouse wheel. The @var{position} element is a mouse position list (@pxref{Click Events}), specifying the position of the mouse cursor when the event occurred. +@var{clicks}, if present, is the number of times that the wheel was +moved in quick succession. @xref{Repeat Events}. @var{lines}, if +present and not @code{nil}, is the number of screen lines that should +be scrolled. @var{pixel-delta}, if present, is a cons cell of the +form @w{@code{(@var{x} . @var{y})}}, where @var{x} and @var{y} are the +numbers of pixels by which to scroll in each axis, a.k.a.@: +@dfn{pixelwise deltas}. + +@cindex pixel-resolution wheel events +You can use these @var{x} and @var{y} pixelwise deltas to determine +how much the mouse wheel has actually moved at pixel resolution. For +example, the pixelwise deltas could be used to scroll the display at +pixel resolution, exactly according to the user's turning the mouse +wheel. + @vindex mouse-wheel-up-event @vindex mouse-wheel-down-event -This kind of event is generated only on some kinds of systems. On some -systems, @code{mouse-4} and @code{mouse-5} are used instead. For -portable code, use the variables @code{mouse-wheel-up-event} and -@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine -what event types to expect for the mouse wheel. +This kind of event is generated only on some kinds of systems. On +some systems, @code{mouse-4} and @code{mouse-5} are used instead. For +portable code, use the variables @code{mouse-wheel-up-event}, +@code{mouse-wheel-up-alternate-event}, @code{mouse-wheel-down-event} +and @code{mouse-wheel-down-alternate-event} defined in +@file{mwheel.el} to determine what event types to expect for the mouse +wheel. + +@vindex mouse-wheel-left-event +@vindex mouse-wheel-right-event +Similarly, some mice can generate @code{mouse-wheel-left-event} and +@code{mouse-wheel-right-event} and can be used to scroll if +@code{mouse-wheel-tilt-scroll} is non-@code{nil}. However, some mice +also generate other events at the same time as they're generating +these scroll events which may get in the way. The way to fix this is +generally to unbind these events (for instance, @code{mouse-6} or +@code{mouse-7}, but this is very hardware and operating system +dependent). + +@cindex @code{pinch} event +@item (pinch @var{position} @var{dx} @var{dy} @var{scale} @var{angle}) +This kind of event is generated by the user performing a ``pinch'' +gesture by placing two fingers on a touchpad and moving them towards +or away from each other. @var{position} is a mouse position list +(@pxref{Click Events}) that provides the position of the mouse pointer +when the event occurred, @var{dx} is the change in the horizontal +distance between the fingers since the last event in the same sequence, +@var{dy} is the vertical movement of the fingers since the last event +in the same sequence, @var{scale} is the ratio of the current distance +between the fingers to that distance at the start of the sequence, and +@var{angle} is the angular difference in degrees between the direction +of the line connecting the fingers in this event and the direction of +that line in the last event of the same sequence. + +As pinch events are only sent at the beginning or during a pinch +sequence, they do not report gestures where the user moves two fingers +on a touchpad in a rotating fashion without pinching the fingers. + +All arguments after @var{position} are floating point numbers. + +This event is usually sent as part of a sequence, which begins with +the user placing two fingers on the touchpad, and ends with the user +removing those fingers. @var{dx}, @var{dy}, and @var{angle} will be +@code{0.0} in the first event of a sequence; subsequent events will +report non-zero values for these members of the event structure. + +@var{dx} and @var{dy} are reported in imaginary relative units, in +which @code{1.0} is the width and height of the touchpad +respectively. They are usually interpreted as being relative to the +size of the object beneath the gesture: image, window, etc. + +@cindex @code{preedit-text} event +@item (preedit-text @var{arg}) +This event is sent when a system input method tells Emacs to display +some text to indicate to the user what will be inserted. The contents +of @var{arg} are dependent on the window system being used. + +On X, @var{arg} is a string describing some text to place behind the +cursor. It can be @code{nil}, which means to remove any text +previously displayed. + +On PGTK frames (@pxref{Frames}), @var{arg} is a list of strings with +information about their color and underline attributes. It has the +following form: + +@example +@group + ((@var{string1} + (ul . @var{underline-color}) + (bg . @var{background-color}) + (fg . @var{foreground-color})) + (@var{string2} + (ul . @var{underline-color}) + (bg . @var{background-color}) + (fg . @var{foreground-color})) + @dots{} + ) +@end group +@end example + +Color information can be omitted, leaving just the text of the +strings. @var{underline-color} can be @code{t}, meaning underlined +text with default underline color, or it can be a string, the name of +the color to draw the underline. + +This is a special event (@pxref{Special Events}), which normally +should not be bound by the user to any command. Emacs will typically +display the text contained in the event in an overlay behind point +when it is received. @cindex @code{drag-n-drop} event @item (drag-n-drop @var{position} @var{files}) @@ -1985,7 +2345,7 @@ example: (interactive) (message "Caught signal %S" last-input-event)) -(define-key special-event-map [sigusr1] 'sigusr-handler) +(keymap-set special-event-map "<sigusr1>" 'sigusr-handler) @end smallexample To test the signal handler, you can make Emacs send a signal to itself: @@ -2086,7 +2446,7 @@ bind it to the @code{signal usr1} event sequence: (defun usr1-handler () (interactive) (message "Got USR1 signal")) -(global-set-key [signal usr1] 'usr1-handler) +(keymap-global-set "<signal> <usr1>" 'usr1-handler) @end smallexample @node Classifying Events @@ -2191,21 +2551,6 @@ This function returns non-@code{nil} if @var{object} is a mouse movement event. @xref{Motion Events}. @end defun -@defun event-convert-list list -This function converts a list of modifier names and a basic event type -to an event type which specifies all of them. The basic event type -must be the last element of the list. For example, - -@example -(event-convert-list '(control ?a)) - @result{} 1 -(event-convert-list '(control meta ?a)) - @result{} -134217727 -(event-convert-list '(control super f1)) - @result{} C-s-f1 -@end example -@end defun - @node Accessing Mouse @subsection Accessing Mouse Events @cindex mouse events, data in @@ -2285,7 +2630,7 @@ POSITION is assumed to lie in a window text area." @end example @end defun -@defun posn-col-row position +@defun posn-col-row position &optional use-window This function returns a cons cell @w{@code{(@var{col} . @var{row})}}, containing the estimated column and row corresponding to buffer position described by @var{position}. The return value is given in @@ -2293,7 +2638,11 @@ units of the frame's default character width and default line height (including spacing), as computed from the @var{x} and @var{y} values corresponding to @var{position}. (So, if the actual characters have non-default sizes, the actual row and column may differ from these -computed values.) +computed values.) If the optional @var{window} argument is +non-@code{nil}, use the default character width in the window +indicated by @var{position} instead of the frame. (This makes a +difference if that window is showing a buffer with a non-default +zooming level, for instance.) Note that @var{row} is counted from the top of the text area. If the window given by @var{position} possesses a header line (@pxref{Header @@ -2352,7 +2701,10 @@ the character at that position. @cindex timestamp of a mouse event @defun posn-timestamp position Return the timestamp in @var{position}. This is the time at which the -event occurred, in milliseconds. +event occurred, in milliseconds. Such a timestamp is reported +relative to an arbitrary starting time that varies according to the +window system in use. On the X Window System, for example, it is the +number of milliseconds since the X server was started. @end defun These functions compute a position list given particular buffer @@ -2425,25 +2777,14 @@ characters in a string is a complex matter, for reasons of historical compatibility, and it is not always possible. We recommend that new programs avoid dealing with these complexities -by not storing keyboard events in strings. Here is how to do that: - -@itemize @bullet -@item -Use vectors instead of strings for key sequences, when you plan to use -them for anything other than as arguments to @code{lookup-key} and -@code{define-key}. For example, you can use -@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and -@code{this-command-keys-vector} instead of @code{this-command-keys}. +by not storing keyboard events in strings containing control +characters or the like, but instead store them in the common Emacs +format as understood by @code{key-valid-p}. -@item -Use vectors to write key sequence constants containing meta characters, -even when passing them directly to @code{define-key}. - -@item -When you have to look at the contents of a key sequence that might be a -string, use @code{listify-key-sequence} (@pxref{Event Input Misc}) -first, to convert it to a list. -@end itemize + If you read a key sequence with @code{read-key-sequence-vector} (or +@code{read-key-sequence}), or access a key sequence with +@code{this-command-keys-vector} (or @code{this-command-keys}), you can +transform this to the recommended format by using @code{key-description}. The complexities stem from the modifier bits that keyboard input characters can include. Aside from the Meta modifier, none of these @@ -2635,10 +2976,14 @@ returns the key sequence as a vector, never as a string. @cindex upper case key sequence @cindex downcasing in @code{lookup-key} @cindex shift-translation +@vindex translate-upper-case-key-bindings If an input character is upper-case (or has the shift modifier) and has no key binding, but its lower-case equivalent has one, then -@code{read-key-sequence} converts the character to lower case. Note -that @code{lookup-key} does not perform case conversion in this way. +@code{read-key-sequence} converts the character to lower case. (This +behavior can be disabled by setting the +@code{translate-upper-case-key-bindings} user option to @code{nil}.) +Note that @code{lookup-key} does not perform case conversion in this +way. @vindex this-command-keys-shift-translated When reading input results in such a @dfn{shift-translation}, Emacs @@ -2871,7 +3216,7 @@ causes it to evaluate @code{help-form} and display the result. It then continues to wait for a valid input character, or keyboard-quit. @end defun -@defun read-multiple-choice prompt choices &optional help-string +@defun read-multiple-choice prompt choices &optional help-string show-help long-form Ask user a multiple choice question. @var{prompt} should be a string that will be displayed as the prompt. @@ -2886,6 +3231,15 @@ a string with a more detailed description of all choices. It will be displayed in a help buffer instead of the default auto-generated description when the user types @kbd{?}. +If optional argument @var{show-help} is non-@code{nil}, the help +buffer will be displayed immediately, before any user input. If it is +a string, use it as the name of the help buffer. + +If optional argument @var{long-form} is non-@code{nil}, the user +will have to type in long-form answers (using @code{completing-read}) +instead of hitting a single key. The answers must be among the second +elements of the values in the @var{choices} list. + The return value is the matching value from @var{choices}. @lisp @@ -2956,7 +3310,7 @@ supplied to input methods (@pxref{Input Methods}). Use if you want to translate characters after input methods operate. @end defvar -@defun keyboard-translate from to +@defun key-translate from to This function modifies @code{keyboard-translate-table} to translate character code @var{from} into character code @var{to}. It creates the keyboard translate table if necessary. @@ -2967,12 +3321,12 @@ make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste operations: @example -(keyboard-translate ?\C-x 'control-x) -(keyboard-translate ?\C-c 'control-c) -(keyboard-translate ?\C-v 'control-v) -(global-set-key [control-x] 'kill-region) -(global-set-key [control-c] 'kill-ring-save) -(global-set-key [control-v] 'yank) +(key-translate "C-x" "<control-x>") +(key-translate "C-c" "<control-c>") +(key-translate "C-v" "<control-v>") +(keymap-global-set "<control-x>" 'kill-region) +(keymap-global-set "<control-c>" 'kill-ring-save) +(keymap-global-set "<control-v>" 'yank) @end example @noindent @@ -3729,6 +4083,15 @@ what happens when a disabled command is invoked interactively. Disabling a command has no effect on calling it as a function from Lisp programs. +@findex command-query + The value of the @code{disabled} property can also be a list where +the first element is the symbol @code{query}. In that case, the user +will be queried whether to execute the command. The second element in +the list should be @code{nil} or non-@code{nil} to say whether to use +@code{y-or-n-p} or @code{yes-or-no-p}, respectively, and the third +element is the question to use. The @code{command-query} convenience +function should be used to enable querying for a command. + @deffn Command enable-command command Allow @var{command} (a symbol) to be executed without special confirmation from now on, and alter the user's init file (@pxref{Init diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index f336753a6c3..60fc11a22ed 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -61,7 +61,7 @@ Here is an example: @group (silly-loop 50000000) -@result{} 10.235304117202759 +@result{} 5.200886011123657 @end group @group @@ -71,12 +71,12 @@ Here is an example: @group (silly-loop 50000000) -@result{} 3.705854892730713 +@result{} 0.6239290237426758 @end group @end example - In this example, the interpreted code required 10 seconds to run, -whereas the byte-compiled code required less than 4 seconds. These + In this example, the interpreted code required more than 5 seconds to run, +whereas the byte-compiled code required less than 1 second. These results are representative, but actual results may vary. @node Compilation Functions @@ -135,10 +135,10 @@ definition of @var{symbol} (@pxref{Byte-Code Objects}). @group (byte-compile 'factorial) @result{} -#[(integer) - "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" - [integer 1 * factorial] - 4 "Compute factorial of INTEGER."] +#[257 + "\211\300U\203^H^@@\300\207\211\301^BS!_\207" + [1 factorial] 4 + "Compute factorial of INTEGER.\n\n(fn INTEGER)"] @end group @end example @@ -688,11 +688,11 @@ Lisp source; these do not appear in the output of @code{disassemble}. (disassemble 'factorial) @print{} byte-code for factorial: doc: Compute factorial of an integer. - args: (integer) + args: (arg1) @end group @group -0 varref integer ; @r{Get the value of @code{integer} and} +0 dup ; @r{Get the value of @code{integer} and} ; @r{push it onto the stack.} 1 constant 1 ; @r{Push 1 onto stack.} @end group @@ -707,9 +707,9 @@ Lisp source; these do not appear in the output of @code{disassemble}. 7 return ; @r{Return the top element of the stack.} @end group @group -8:1 varref integer ; @r{Push value of @code{integer} onto stack.} +8:1 dup ; @r{Push value of @code{integer} onto stack.} 9 constant factorial ; @r{Push @code{factorial} onto stack.} -10 varref integer ; @r{Push value of @code{integer} onto stack.} +10 stack-ref 2 ; @r{Push value of @code{integer} onto stack.} 11 sub1 ; @r{Pop @code{integer}, decrement value,} ; @r{push new value onto stack.} 12 call 1 ; @r{Call function @code{factorial} using first} @@ -717,9 +717,9 @@ Lisp source; these do not appear in the output of @code{disassemble}. ; @r{push returned value onto stack.} @end group @group -13 mult ; @r{Pop top two values off stack, multiply} +13 mult ; @r{Pop top two values off stack, multiply} ; @r{them, and push result onto stack.} -14 return ; @r{Return the top element of the stack.} +14 return ; @r{Return the top element of the stack.} @end group @end example @@ -740,7 +740,7 @@ The @code{silly-loop} function is somewhat more complex: (disassemble 'silly-loop) @print{} byte-code for silly-loop: doc: Return time before and after N iterations of a loop. - args: (n) + args: (arg1) @end group @group @@ -749,24 +749,21 @@ The @code{silly-loop} function is somewhat more complex: @end group @group 1 call 0 ; @r{Call @code{current-time-string} with no} - ; @r{argument, push result onto stack.} + ; @r{argument, push result onto stack as @code{t1}.} @end group @group -2 varbind t1 ; @r{Pop stack and bind @code{t1} to popped value.} -@end group -@group -3:1 varref n ; @r{Get value of @code{n} from the environment} +2:1 stack-ref 1 ; @r{Get value of the argument @code{n}} ; @r{and push the value on the stack.} -4 sub1 ; @r{Subtract 1 from top of stack.} +3 sub1 ; @r{Subtract 1 from top of stack.} @end group @group -5 dup ; @r{Duplicate top of stack; i.e., copy the top} +4 dup ; @r{Duplicate top of stack; i.e., copy the top} ; @r{of the stack and push copy onto stack.} -6 varset n ; @r{Pop the top of the stack,} - ; @r{and bind @code{n} to the value.} +5 stack-set 3 ; @r{Pop the top of the stack,} + ; @r{and set @code{n} to the value.} -;; @r{(In effect, the sequence @code{dup varset} copies the top of the stack} -;; @r{into the value of @code{n} without popping it.)} +;; @r{(In effect, the sequence @code{dup stack-set} copies the top of} +;; @r{the stack into the value of @code{n} without popping it.)} @end group @group @@ -781,16 +778,15 @@ The @code{silly-loop} function is somewhat more complex: ; @r{else continue.} @end group @group -12 varref t1 ; @r{Push value of @code{t1} onto stack.} +12 dup ; @r{Push value of @code{t1} onto stack.} 13 constant current-time-string ; @r{Push @code{current-time-string}} ; @r{onto the top of the stack.} 14 call 0 ; @r{Call @code{current-time-string} again.} @end group @group -15 unbind 1 ; @r{Unbind @code{t1} in local environment.} -16 list2 ; @r{Pop top two elements off stack, create a} +15 list2 ; @r{Pop top two elements off stack, create a} ; @r{list of them, and push it onto stack.} -17 return ; @r{Return value of the top of stack.} +16 return ; @r{Return value of the top of stack.} @end group @end example diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 34653d70565..d4520ebdee5 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1286,6 +1286,15 @@ bindings that can then be used inside @var{body}. The variable bindings are produced by destructuring binding of elements of @var{pattern} to the values of the corresponding elements of the evaluated @var{exp}. + +Here's a trivial example: + +@example +(pcase-let ((`(,major ,minor) + (split-string "image/png" "/"))) + minor) + @result{} "png" +@end example @end defmac @defmac pcase-let* bindings body@dots{} @@ -1320,6 +1329,20 @@ Assign values to variables in a @code{setq} form, destructuring each @var{value} according to its respective @var{pattern}. @end defmac +@defmac pcase-lambda lambda-list &rest body +This is like @code{lambda}, but allows each argument to be a pattern. +For instance, here's a simple function that takes a cons cell as the +argument: + +@example +(setq fun + (pcase-lambda (`(,key . ,val)) + (vector key (* val 10)))) +(funcall fun '(foo . 2)) + @result{} [foo 20] +@end example +@end defmac + @node Iteration @section Iteration @cindex iteration diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index 9c635baccf7..6ba35cffffe 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -376,7 +376,7 @@ name) and the new value, and should do whatever is necessary to update the value properly for this option (which may not mean simply setting the option as a Lisp variable); preferably, though, it should not modify its value argument destructively. The default for -@var{setfunction} is @code{set-default}. +@var{setfunction} is @code{set-default-toplevel-value}. If you specify this keyword, the variable's documentation string should describe how to do the same job in hand-written Lisp code. @@ -387,7 +387,7 @@ Specify @var{getfunction} as the way to extract the value of this option. The function @var{getfunction} should take one argument, a symbol, and should return whatever customize should use as the current value for that symbol (which need not be the symbol's Lisp -value). The default is @code{default-value}. +value). The default is @code{default-toplevel-value}. You have to really understand the workings of Custom to use @code{:get} correctly. It is meant for values that are treated in @@ -409,11 +409,11 @@ do not reinitialize it if it is already non-void. @item custom-initialize-default Like @code{custom-initialize-set}, but use the function -@code{set-default} to set the variable, instead of the variable's -@code{:set} function. This is the usual choice for a variable whose -@code{:set} function enables or disables a minor mode; with this choice, -defining the variable will not call the minor mode function, but -customizing the variable will do so. +@code{set-default-toplevel-value} to set the variable, instead of the +variable's @code{:set} function. This is the usual choice for a +variable whose @code{:set} function enables or disables a minor mode; +with this choice, defining the variable will not call the minor mode +function, but customizing the variable will do so. @item custom-initialize-reset Always use the @code{:set} function to initialize the variable. If @@ -424,7 +424,7 @@ This is the default @code{:initialize} function. @item custom-initialize-changed Use the @code{:set} function to initialize the variable, if it is already set or has been customized; otherwise, just use -@code{set-default}. +@code{set-default-toplevel-value}. @item custom-initialize-delay This function behaves like @code{custom-initialize-set}, but it @@ -654,10 +654,14 @@ you can specify that the value must be @code{nil} or @code{t}, but also specify the text to describe each value in a way that fits the specific meaning of the alternative. +@item key +The value is a valid key according to @kbd{key-valid-p}, and suitable +for use with, for example @code{keymap-set}. + @item key-sequence The value is a key sequence. The customization buffer shows the key sequence using the same syntax as the @kbd{kbd} function. @xref{Key -Sequences}. +Sequences}. This is a legacy type; use @code{key} instead. @item coding-system The value must be a coding-system name, and you can do completion with @@ -668,6 +672,10 @@ The value must be a valid color name. The widget provides completion for color names, as well as a sample and a button for selecting a color name from a list of color names shown in a @file{*Colors*} buffer. + +@item fringe-bitmap +The value must be a valid fringe bitmap name. The widget provides +completion. @end table @node Composite Types @@ -737,7 +745,7 @@ If omitted, @var{key-type} and @var{value-type} default to The user can add any key matching the specified key type, but you can give some keys a preferential treatment by specifying them with the -@code{:options} (see @ref{Variable Definitions}). The specified keys +@code{:options} (@pxref{Variable Definitions}). The specified keys will always be shown in the customize buffer (together with a suitable value), with a checkbox to include or exclude or disable the key/value pair from the alist. The user will not be able to edit the keys diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 469ff2d943d..9ae40949d1e 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -77,6 +77,7 @@ debugger recursively. @xref{Recursive Editing}. @menu * Error Debugging:: Entering the debugger when an error happens. +* Debugging Redisplay:: Getting backtraces from redisplay errors. * Infinite Loops:: Stopping and debugging a program that doesn't exit. * Function Debugging:: Entering it when a certain function is called. * Variable Debugging:: Entering it when a variable is modified. @@ -105,6 +106,10 @@ debugger, set the variable @code{debug-on-error} to non-@code{nil}. (The command @code{toggle-debug-on-error} provides an easy way to do this.) +Note that, for technical reasons, you cannot use the facilities +defined in this subsection to debug errors in Lisp that the redisplay +code has invoked. @xref{Debugging Redisplay}, for help with these. + @defopt debug-on-error This variable determines whether the debugger is called when an error is signaled and not handled. If @code{debug-on-error} is @code{t}, @@ -196,12 +201,62 @@ echo area. For example, this can be useful when trying to find the cause of a particular message. @end defvar +@defvar debug-allow-recursive-debug +You can evaluate forms in the current stack frame in the +@samp{*Backtrace*} buffer with the @key{e} command, and while +edebugging you can use the @key{e} and @key{C-x C-e} commands to do +something similar. By default, the debugger is inhibited by these +commands (because (re-)entering the debugger at this point will +usually take you out of the debugging context you're in). Set +@code{debug-allow-recursive-debug} to a non-@code{nil} value to allow +these commands to enter the debugger recursively. +@end defvar + To debug an error that happens during loading of the init file, use the option @samp{--debug-init}. This binds @code{debug-on-error} to @code{t} while loading the init file, and bypasses the @code{condition-case} which normally catches errors in the init file. +@node Debugging Redisplay +@subsection Debugging Redisplay Errors +@cindex redisplay errors +@cindex debugging redisplay errors + +When an error occurs in Lisp code which redisplay has invoked, Emacs's +usual debugging mechanisms are unusable, for technical reasons. This +subsection describes how to get a backtrace from such an error, which +should be helpful in debugging it. + +These directions apply to Lisp forms used, for example, in +@code{:eval} mode line constructs (@pxref{Mode Line Data}), and in all +hooks invoked from redisplay, such as: + +@itemize +@item +@code{fontification-functions} (@pxref{Auto Faces}). +@item +@code{window-scroll-functions} (@pxref{Window Hooks}). +@end itemize + +Note that if you have had an error in a hook function called from +redisplay, the error handling might have removed this function from +the hook. You will thus need to reinitialize that hook somehow, +perhaps with @code{add-hook}, to be able to replay the bug. + +To generate a backtrace in these circumstances, set the variable +@code{backtrace-on-redisplay-error} to non-@code{nil}. When the error +occurs, Emacs will dump the backtrace to the buffer +@file{*Redisplay-trace*}, but won't automatically display it in a +window. This is to avoid needlessly corrupting the redisplay you are +debugging. You will thus need to display the buffer yourself, with a +command such as @code{switch-to-buffer-other-frame} @key{C-x 5 b}. + +@defvar backtrace-on-redisplay-error +Set this variable to non-@code{nil} to enable the generation of a +backtrace when an error occurs in any Lisp called from redisplay. +@end defvar + @node Infinite Loops @subsection Debugging Infinite Loops @cindex infinite loops @@ -387,11 +442,9 @@ possibilities.) variable is temporarily set according to @code{eval-expression-debug-on-error}. If the latter variable is non-@code{nil}, @code{debug-on-error} will temporarily be set to -@code{t}. This means that any further errors that occur while doing a -debugging session will (by default) trigger another backtrace. If -this is not what you want, you can either set -@code{eval-expression-debug-on-error} to @code{nil}, or set -@code{debug-on-error} to @code{nil} in @code{debugger-mode-hook}. +@code{t}. However, further errors that occur while debugging won't +(by default) trigger another debugger, because @code{inhibit-debugger} +will also be bound to non-@code{nil}. The debugger itself must be run byte-compiled, since it makes assumptions about the state of the Lisp interpreter. These @@ -522,6 +575,7 @@ Flag the current frame like @kbd{b}. Then continue execution like @kbd{c}, but temporarily disable break-on-entry for all functions that are set up to do so by @code{debug-on-entry}. +@vindex debug-allow-recursive-debug @item e Read a Lisp expression in the minibuffer, evaluate it (with the relevant lexical environment, if applicable), and print the @@ -530,7 +584,11 @@ variables, and the current buffer, as part of its operation; @kbd{e} temporarily restores their values from outside the debugger, so you can examine and change them. This makes the debugger more transparent. By contrast, @kbd{M-:} does nothing special in the debugger; it shows you -the variable values within the debugger. +the variable values within the debugger. By default, this command +suppresses the debugger during evaluation, so that an error in the +evaluated expression won't add a new error on top of the existing one. +Set the @code{debug-allow-recursive-debug} user option to a +non-@code{nil} value to override this. @item R Like @kbd{e}, but also save the result of evaluation in the diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index b068c7d08c6..190364852af 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -27,6 +27,7 @@ that Emacs presents to the user. * Window Dividers:: Separating windows visually. * Display Property:: Images, margins, text size, etc. * Images:: Displaying images in Emacs buffers. +* Icons:: Displaying icons in Emacs buffers. * Xwidgets:: Displaying native widgets in Emacs buffers. * Buttons:: Adding clickable buttons to Emacs buffers. * Abstract Display:: Emacs's Widget for Object Collections. @@ -336,7 +337,10 @@ functions call it with no arguments when their argument message is Usually this function is called when the next input event arrives after displaying an echo-area message. The function is expected to clear the message displayed by its counterpart function specified by -@code{set-message-function}. +@code{set-message-function}, but doesn't have to. If the function +wants the echo area to remain uncleared, it should return the symbol +@code{dont-clear-message}; any other value will result in the echo +area being cleared. The default value is the function that clears the message displayed in an active minibuffer. @@ -561,6 +565,26 @@ You can rewrite the previous example with this macro as follows: @end example @end defmac +@defmac with-delayed-message (timeout message) body@dots{} +Sometimes it's unclear whether an operation will take a long time to +execute or not, or it can be inconvenient to implement a progress +reporter. This macro can be used in those situations. + +@lisp +(with-delayed-message (2 (format "Gathering data for %s" entry)) + (setq data (gather-data entry))) +@end lisp + +In this example, if the body takes more than two seconds to execute, +the message will be displayed. If it takes a shorter time than that, +the message won't be displayed. In either case, the body is evaluated +as normally, and the return value of the final element in the body is +the return value of the macro. + +The @var{message} element is evaluated before @var{body}, and is +always evaluated, whether the message is displayed or not. +@end defmac + @node Logging Messages @subsection Logging Messages in @file{*Messages*} @cindex logging echo-area messages @@ -592,6 +616,16 @@ how to display a message and prevent it from being logged: @end example @end defopt +@defvar messages-buffer-name +This variable has the name of the buffer where messages should be +logged to, and defaults to @file{*Messages*}. Some packages may find +it useful to temporarily redirect the output to a different buffer +(perhaps to write the buffer out to a log file later), and they can +bind this variable to a different buffer name. (Note that this buffer +(if it doesn't exist already), will be created and put into +@code{messages-buffer-mode}.) +@end defvar + To make @file{*Messages*} more convenient for the user, the logging facility combines successive identical messages. It also combines successive related messages for the sake of two cases: question @@ -1334,6 +1368,11 @@ are not resized. By default, this mode uses @code{fit-window-to-buffer} (@pxref{Resizing Windows}) for resizing. You can specify a different function by customizing the options @code{temp-buffer-max-height} and @code{temp-buffer-max-width} below. + +The effect of this option can be overridden by providing a suitable +@code{window-height}, @code{window-width} or @code{window-size} action +alist entry for @code{display-buffer} (@pxref{Buffer Display Action +Alists}). @end defopt @defopt temp-buffer-max-height @@ -1972,6 +2011,11 @@ Tables}). The width of a tab character is usually @code{tab-width} (@pxref{Usual Display}). @end defun +@defun char-uppercase-p char +Return non-@code{nil} if @var{char} is an uppercase character +according to Unicode. +@end defun + @defun string-width string &optional from to This function returns the width in columns of the string @var{string}, if it were displayed in the current buffer and the selected window. @@ -1983,7 +2027,8 @@ The return value is an approximation: it only considers the values returned by @code{char-width} for the constituent characters, always takes a tab character as taking @code{tab-width} columns, ignores display properties and fonts, etc. For these reasons, we recommend -using @code{window-text-pixel-size}, described below, instead. +using @code{window-text-pixel-size} or @code{string-pixel-width}, +described below, instead. @end defun @defun truncate-string-to-width string width &optional start-column padding ellipsis ellipsis-text-property @@ -2060,23 +2105,33 @@ displayed in a given window. This function is used by (@pxref{Resizing Windows}) to make a window exactly as large as the text it contains. -@defun window-text-pixel-size &optional window from to x-limit y-limit mode-lines +@defun window-text-pixel-size &optional window from to x-limit y-limit mode-lines ignore-line-at-end This function returns the size of the text of @var{window}'s buffer in pixels. @var{window} must be a live window and defaults to the selected one. The return value is a cons of the maximum pixel-width of any text line and the maximum pixel-height of all text lines. This function exists to allow Lisp programs to adjust the dimensions of -@var{window} to the buffer text it needs to display. +@var{window} to the buffer text it needs to display, and for other +similar situations. + +The return value can also optionally (see below) include the buffer +position of the first line whose dimensions were measured. The optional argument @var{from}, if non-@code{nil}, specifies the first text position to consider, and defaults to the minimum accessible position of the buffer. If @var{from} is @code{t}, it stands for the minimum accessible position that is not a newline -character. The optional argument @var{to}, if non-@code{nil}, -specifies the last text position to consider, and defaults to the -maximum accessible position of the buffer. If @var{to} is @code{t}, -it stands for the maximum accessible position that is not a newline -character. +character. If @var{from} is a cons, its @code{car} specifies a buffer +position, and its @code{cdr} specifies the vertical offset in pixels +from that position to the first screen line whose text is to be +measured. (The measurement will start from the visual beginning of +that screen line.) In that case, the return value will instead be a +list of the pixel-width, pixel-height, and the buffer position of the +first line that was measured. The optional argument @var{to}, if +non-@code{nil}, specifies the last text position to consider, and +defaults to the maximum accessible position of the buffer. If +@var{to} is @code{t}, it stands for the maximum accessible position +that is not a newline character. The optional argument @var{x-limit}, if non-@code{nil}, specifies the maximum X coordinate beyond which text should be ignored; it is @@ -2096,7 +2151,7 @@ the buffer might contain long lines that will be truncated anyway. The optional argument @var{y-limit}, if non-@code{nil}, specifies the maximum Y coordinate beyond which text is to be ignored; it is therefore also the maximum pixel-height that the function can return. -If @var{y-limit} is nil or omitted, it means to considers all the +If @var{y-limit} is @code{nil} or omitted, it means to consider all the lines of text till the buffer position specified by @var{to}. Since calculating the pixel-height of a large buffer can take some time, it makes sense to specify this argument; in particular, if the caller @@ -2110,6 +2165,12 @@ line, if present, in the return value. If it is @code{t}, include the height of all of these lines, if present, in the return value. @end defun +The optional argument @var{ignore-line-at-end} controls whether or +not to count the height of text in @var{to}'s screen line as part of +the returned pixel-height. This is useful if your Lisp program is +only interested in the dimensions of text up to and excluding the +visual beginning of @var{to}'s screen line. + @code{window-text-pixel-size} treats the text displayed in a window as a whole and does not care about the size of individual lines. The following function does. @@ -2175,12 +2236,59 @@ though when this function is run from an idle timer with a delay of zero seconds. @end defun +@defun buffer-text-pixel-size &optional buffer-or-name window from to x-limit y-limit +This is much like @code{window-text-pixel-size}, but can be used when +the buffer isn't shown in a window. (@code{window-text-pixel-size} is +faster when it is, so this function shouldn't be used in that case.) + +@var{buffer-or-name} must specify a live buffer or the name of a live +buffer and defaults to the current buffer. @var{window} must be a +live window and defaults to the selected one; the function will +compute the text dimensions as if @var{buffer} is displayed in +@var{window}. The return value is a cons of the maximum pixel-width +of any text line and the pixel-height of all the text lines of the +buffer specified by @var{buffer-or-name}. + +The optional arguments @var{x-limit} and @var{y-limit} have the same +meaning as with @code{window-text-pixel-size}. +@end defun + +@defun string-pixel-width string +This is a convenience function that uses @code{window-text-pixel-size} +to compute the width of @var{string} (in pixels). +@end defun + @defun line-pixel-height This function returns the height in pixels of the line at point in the selected window. The value includes the line spacing of the line (@pxref{Line Height}). @end defun +@cindex grapheme cluster +@defun string-glyph-split string +When character compositions are in effect, sequence of characters can +be composed for display to form @dfn{grapheme clusters}, for example +to display accented characters, or ligatures, or Emoji, or when +complex text shaping requires that for some scripts. When that +happens, characters no longer map in a simple way to display columns, +and display layout decisions with such strings, such as truncating too +wide strings, can be a complex job. This function helps in performing +suvh jobs: it splits up its argument @var{string} into a list of +substrings, where each substring produces a single grapheme cluster +that should be displayed as a unit. Lisp programs can then use this +list to construct visually-valid substrings of @var{string} which will +look correctly on display, or compute the width of any substring of +@var{string} by adding the width of its constituents in the returned +list, etc. + +For instance, if you want to display a string without the first glyph, +you can say: + +@example +(apply #'insert (cdr (string-glyph-split string)))) +@end example +@end defun + When a buffer is displayed with line numbers (@pxref{Display Custom,,, emacs, The GNU Emacs Manual}), it is sometimes useful to know the width taken for displaying the line numbers. The following function @@ -2367,13 +2475,22 @@ Otherwise, it returns @code{nil}. The following table lists all the face attributes, their possible values, and their effects. +@cindex unspecified, face attribute value Apart from the values given below, each face attribute can have the value @code{unspecified}. This special value means that the face doesn't specify that attribute directly. An @code{unspecified} attribute tells Emacs to refer instead to a parent face (see the description @code{:inherit} attribute below); or, failing that, to an -underlying face (@pxref{Displaying Faces}). The @code{default} face -must specify all attributes. +underlying face (@pxref{Displaying Faces}). (However, +@code{unspecified} is not a valid value in @code{defface}.) + +@cindex reset, face attribute value + A face attribute can also have the value @code{reset}. This special +value stands for the value of the corresponding attribute of the +@code{default} face. + + The @code{default} face must explicitly specify all attributes, and +cannot use the special value @code{reset}. Some of these attributes are meaningful only on certain kinds of displays. If your display cannot handle a certain attribute, the @@ -2394,8 +2511,9 @@ GNU Emacs Manual}. @item :width Relative character width. This should be one of the symbols @code{ultra-condensed}, @code{extra-condensed}, @code{condensed}, -@code{semi-condensed}, @code{normal}, @code{semi-expanded}, -@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}. +@code{semi-condensed}, @code{normal}, @code{regular}, @code{medium}, +@code{semi-expanded}, @code{expanded}, @code{extra-expanded}, or +@code{ultra-expanded}. @item :height The height of the font. In the simplest case, this is an integer in @@ -2463,13 +2581,16 @@ Underline with the foreground color of the face. @item @var{color} Underline in color @var{color}, a string specifying a color. -@item @code{(:color @var{color} :style @var{style})} +@item @code{(:color @var{color} :style @var{style} :position @var{position})} @var{color} is either a string, or the symbol @code{foreground-color}, meaning the foreground color of the face. Omitting the attribute @code{:color} means to use the foreground color of the face. @var{style} should be a symbol @code{line} or @code{wave}, meaning to use a straight or wavy line. Omitting the attribute @code{:style} -means to use a straight line. +means to use a straight line. @var{position}, if non-nil, means to +display the underline at the descent of the text, instead of at the +baseline level. If it is a number, then it specifies the amount of +pixels above the descent to display the underline. @end table @cindex overlined text @@ -2502,14 +2623,17 @@ Draw a box with lines of width 1, in the foreground color. Draw a box with lines of width 1, in color @var{color}. @item @code{(:line-width (@var{vwidth} . @var{hwidth}) :color @var{color} :style @var{style})} -This way you can explicitly specify all aspects of the box. The values -@var{vwidth} and @var{hwidth} specifies respectively the width of the -vertical and horizontal lines to draw; they default to (1 . 1). -A negative horizontal or vertical width @minus{}@var{n} means to draw a line -of width @var{n} that occupies the space of the underlying text, thus -avoiding any increase in the character height or width. For simplification -the width could be specified with only a single number @var{n} instead -of a list, such case is equivalent to @code{((abs @var{n}) . @var{n})}. +You can explicitly specify all aspects of the box with a plist on this +form. Any element in this plist can be omitted. + +The values @var{vwidth} and @var{hwidth} specifies respectively the +width of the vertical and horizontal lines to draw; they default to (1 +. 1). A negative horizontal or vertical width @minus{}@var{n} means +to draw a line of width @var{n} that occupies the space of the +underlying text, thus avoiding any increase in the character height or +width. For simplification the width could be specified with only a +single number @var{n} instead of a list, such case is equivalent to +@code{((abs @var{n}) . @var{n})}. The value @var{style} specifies whether to draw a 3D box. If it is @code{released-button}, the box looks like a 3D button that is not @@ -2717,8 +2841,9 @@ apply to. Here are the possible values of @var{characteristic}: @item type The kind of window system the terminal uses---either @code{graphic} (any graphics-capable display), @code{x}, @code{pc} (for the MS-DOS -console), @code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} (a -non-graphics-capable display). @xref{Window Systems, window-system}. +console), @code{w32} (for MS Windows 9X/NT/2K/XP), @code{haiku} (for +Haiku), @code{pgtk} (for pure GTK), or @code{tty} (a non-graphics-capable +display). @xref{Window Systems, window-system}. @item class What kinds of colors the terminal supports---either @code{color}, @@ -3232,6 +3357,16 @@ if you need to remove the remapping later. ;; Increase the size of the 'default' face by 50%: (face-remap-add-relative 'default :height 1.5) @end example + +Note that buffer-local face remapping does not work reliably for +parent faces of basic faces (@pxref{Basic Faces}). (These are the +faces that are used in mode lines, header lines, and other basic +decorations of windows and frames.) For instance, +@code{mode-line-inactive} inherits from @code{mode-line}, but +remapping @code{mode-line} won't normally have the desired effect on +@code{mode-line-inactive}, especially if done locally for some +buffers. Instead you have to remap @code{mode-line-inactive} +directly. @end defun @defun face-remap-remove-relative cookie @@ -3348,6 +3483,12 @@ function finishes are the ones that really matter. For efficiency, we recommend writing these functions so that they usually assign faces to around 400 to 600 characters at each call. + +When the buffer text includes very long lines, these functions are +called with the buffer narrowed to a relatively small region around +@var{pos}, and with narrowing locked, so the functions cannot use +@code{widen} to gain access to the rest of the buffer. +@xref{Narrowing}. @end defvar @node Basic Faces @@ -3357,10 +3498,10 @@ usually assign faces to around 400 to 600 characters at each call. If your Emacs Lisp program needs to assign some faces to text, it is often a good idea to use certain existing faces or inherit from them, rather than defining entirely new faces. This way, if other users -have customized the basic faces to give Emacs a certain look, your -program will fit in without additional customization. +have customized those existing faces to give Emacs a certain look, +your program will fit in without additional customization. - Some of the basic faces defined in Emacs are listed below. In + Some of the @dfn{basic faces} defined in Emacs are listed below. In addition to these, you might want to make use of the Font Lock faces for syntactic highlighting, if highlighting is not already handled by Font Lock mode, or if some Font Lock faces are not in use. @@ -3372,6 +3513,28 @@ The default face, whose attributes are all specified. All other faces implicitly inherit from it: any unspecified attribute defaults to the attribute on this face (@pxref{Face Attributes}). +@item mode-line-active +@itemx mode-line-inactive +@itemx header-line +@itemx tab-line +Basic faces used for the mode line, header line, and tab line. + +@item tool-bar +@itemx tab-bar +@itemx fringe +@itemx scroll-bar +@itemx window-divider +@itemx border +@itemx child-frame-border +Basic faces used for the corresponding decorations of GUI frames. + +@item cursor +The basic face used for the text cursor. + +@item mouse +The basic face used for displaying mouse-sensitive text when the mouse +pointer is on that text. + @item bold @itemx italic @itemx bold-italic @@ -4466,6 +4629,7 @@ Used to indicate buffer boundaries. Used for different types of fringe cursors. @item @code{exclamation-mark}, @code{question-mark} +@itemx @code{large-circle} Not used by core Emacs features. @end table @@ -4859,9 +5023,7 @@ window on a minibuffer-less frame. The @code{display} text property (or overlay property) is used to insert images into text, and to control other aspects of how text -displays. The value of the @code{display} property should be a -display specification, or a list or vector containing several display -specifications. Display specifications in the same @code{display} +displays. Display specifications in the same @code{display} property value generally apply in parallel to the text they cover. If several sources (overlays and/or a text property) specify values @@ -4869,6 +5031,50 @@ for the @code{display} property, only one of the values takes effect, following the rules of @code{get-char-property}. @xref{Examining Properties}. + The value of the @code{display} property should be a display +specification, or a list or vector containing several display +specifications. + +@defun get-display-property position prop &optional object properties +This convenience function can be used to get a specific display +property, no matter whether the @code{display} property is a vector, a +list or a simple property. This is like @code{get-text-property} +(@pxref{Examining Properties}), but works on the @code{display} +property only. + +@var{position} is the position in the buffer or string to examine, and +@var{prop} is the @code{display} property to return. The optional +@var{object} argument should be either a string or a buffer, and +defaults to the current buffer. If the optional @var{properties} +argument is non-@code{nil}, it should be a @code{display} property, +and in that case, @var{position} and @var{object} are ignored. (This +can be useful if you've already gotten the @code{display} property +with @code{get-char-property}, for instance (@pxref{Examining +Properties}). +@end defun + +@defun add-display-text-property start end prop value &optional object +Add @code{display} property @var{prop} of @var{value} to the text from +@var{start} to @var{end}. + +If any text in the region has a non-@code{nil} @code{display} +property, those properties are retained. For instance: + +@lisp +(add-display-text-property 4 8 'height 2.0) +(add-display-text-property 2 12 'raise 0.5) +@end lisp + +After doing this, the region from 2 to 4 will have the @code{raise} +@code{display} property, the region from 4 to 8 will have both the +@code{raise} and @code{height} @code{display} properties, and finally +the region from 8 to 12 will only have the @code{raise} @code{display} +property. + +If @var{object} is non-@code{nil}, it should be a string or a buffer. +If @code{nil}, this defaults to the current buffer. +@end defun + @cindex display property, unsafe evaluation @cindex security, and display specifications Some of the display specifications allow inclusion of Lisp forms, @@ -5144,6 +5350,24 @@ text that has the specification. It displays all of these spaces be an integer or float. Characters other than spaces are not affected at all; in particular, this has no effect on tab characters. +@item (min-width (@var{width})) +This display specification ensures the text that has it takes at least +@var{width} space on display, by adding a stretch of white space to +the end of the text if the text is shorter than @var{width}. The text +is partitioned using the identity of the parameter, which is why the +parameter is a list with one element. For instance: + +@lisp +(insert (propertize "foo" 'display '(min-width (6.0)))) +@end lisp + +This will add padding after @samp{foo} bringing the total width up to +the width of six normal characters. Note that the affected characters +are identified by the @code{(6.0)} list in the display property, +compared with @code{eq}. The element @var{width} can be either an +integer or a float specifying the required minimum width of the text +(@pxref{Pixel Specification}). + @item (height @var{height}) This display specification makes the text taller or shorter. Here are the possibilities for @var{height}: @@ -5344,13 +5568,19 @@ to modify the set of known names for these dynamic libraries. Supported image formats (and the required support libraries) include PBM and XBM (which do not depend on support libraries and are always available), XPM (@code{libXpm}), GIF (@code{libgif} or -@code{libungif}), JPEG (@code{libjpeg}), TIFF -(@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}). +@code{libungif}), JPEG (@code{libjpeg}), TIFF (@code{libtiff}), PNG +(@code{libpng}), SVG (@code{librsvg}), and WebP (@code{libwebp}). Each of these image formats is associated with an @dfn{image type symbol}. The symbols for the above formats are, respectively, -@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, -@code{jpeg}, @code{tiff}, @code{png}, and @code{svg}. +@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{jpeg}, +@code{tiff}, @code{png}, @code{svg}, and @code{webp}. + + On some platforms, the built-in image support that doesn't require +any optional libraries includes BMP images.@footnote{ +On MS-Windows, this requires @code{w32-use-native-image-API} to be set +non-@code{nil}. +} Furthermore, if you build Emacs with ImageMagick (@code{libMagickWand}) support, Emacs can display any image format @@ -5505,6 +5735,12 @@ are supported, unless the image type is @code{imagemagick}. Positive values rotate clockwise, negative values counter-clockwise. Rotation is performed after scaling and cropping. +@item :flip @var{flip} +If this is @code{t}, the image will be horizontally flipped. +Currently it has no effect if the image type is @code{imagemagick}. +Vertical flipping can be achieved by rotating the image 180 degrees +and toggling this value. + @item :transform-smoothing @var{smooth} If this is @code{t}, any image transform will have smoothing applied; if @code{nil}, no smoothing will be applied. The exact algorithm used @@ -5653,6 +5889,14 @@ When you click the mouse when the mouse pointer is over a hot-spot, an event is composed by combining the @var{id} of the hot-spot with the mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's @var{id} is @code{area4}. + +Note that the map's coordinates should reflect the displayed image +after all transforms have been done (rotation, scaling and so on), and +also note that Emacs (by default) performs auto-scaling of images, so +to make things match up, you should either specify @code{:scale 1.0} +when creating the image, or use the result of +@code{image-compute-scaling-factor} to compute the elements of the +map. @end table @defun image-mask-p spec &optional frame @@ -5718,13 +5962,10 @@ There are three formats you can use for @var{data}: @itemize @bullet @item A vector of strings or bool-vectors, each specifying one line of the -image. Do specify @code{:height} and @code{:width}. +image. Do specify @code{:data-height} and @code{:data-width}. @item A string containing the same byte sequence as an XBM file would contain. -You must not specify @code{:height} and @code{:width} in this case, -because omitting them is what indicates the data has the format of an -XBM file. The file contents specify the height and width of the image. @item A string or a bool-vector containing the bits of the image (plus @@ -5732,26 +5973,11 @@ perhaps some extra bits at the end that will not be used). It should contain at least @w{@code{@var{stride} * @var{height}}} bits, where @var{stride} is the smallest multiple of 8 greater than or equal to the width of the image. In this case, you should specify -@code{:height}, @code{:width} and @code{:stride}, both to indicate -that the string contains just the bits rather than a whole XBM file, -and to specify the size of the image. +@code{:data-height}, @code{:data-width} and @code{:stride}, both to +indicate that the string contains just the bits rather than a whole +XBM file, and to specify the size of the image. @end itemize -@item :width @var{width} -The value, @var{width}, specifies the width of the image, in pixels. - -@item :height @var{height} -The value, @var{height}, specifies the height of the image, in pixels. - -Note that @code{:width} and @code{:height} can only be used if passing -in data that doesn't specify the width and height (e.g., a string or a -vector containing the bits of the image). @acronym{XBM} files usually -specify this themselves, and it's an error to use these two properties -on these files. Also note that @code{:width} and @code{:height} are -used by most other image formats to specify what the displayed image -is supposed to be, which usually means performing some sort of -scaling. This isn't supported for @acronym{XBM} images. - @item :stride @var{stride} The number of bool vector entries stored for each row; the smallest multiple of 8 greater than or equal to @var{width}. @@ -6354,6 +6580,9 @@ Image type @code{png}. @item TIFF Image type @code{tiff}. Supports the @code{:index} property. @xref{Multi-Frame Images}. + +@item WebP +Image type @code{webp}. @end table @node Defining Images @@ -6505,7 +6734,7 @@ will compute a scaling factor based on the font pixel size. property yourself, but it is easier to use the functions in this section. -@defun insert-image image &optional string area slice +@defun insert-image image &optional string area slice inhibit-isearch This function inserts @var{image} in the current buffer at point. The value @var{image} should be an image descriptor; it could be a value returned by @code{create-image}, or the value of a symbol defined with @@ -6532,7 +6761,9 @@ image. Internally, this function inserts @var{string} in the buffer, and gives it a @code{display} property which specifies @var{image}. @xref{Display -Property}. +Property}. By default, doing interactive searches in the buffer will +consider @var{string} when searching. If @var{inhibit-isearch} is +non-@code{nil}, this is inhibited. @end defun @cindex slice, image @@ -6608,6 +6839,11 @@ cache, it can always be displayed, even if the value of @code{max-image-size} is subsequently changed (@pxref{Image Cache}). @end defvar +@defun image-at-point-p +This function returns @code{t} if point is on an image, and @code{nil} +otherwise. +@end defun + Images inserted with the insertion functions above also get a local keymap installed in the text properties (or overlays) that span the displayed image. This keymap defines the following commands: @@ -6627,6 +6863,12 @@ A prefix means to rotate by 90 degrees counter-clockwise instead. @item o Save the image to a file (@code{image-save}). + +@item c +Crop the image interactively (@code{image-crop}). + +@item x +Cut a rectangle from the image interactively (@code{image-cut}). @end table @node Multi-Frame Images @@ -6762,6 +7004,165 @@ bytes. An image of size 200x100 with 24 bits per color will have a cache size of 60000 bytes, for instance. @end defun +@node Icons +@section Icons + +Emacs sometimes uses buttons (for clicking on) or small graphics (to +illustrate something). Since Emacs is available on a wide variety of +systems with different capabilities, and users have different +preferences, Emacs provides a facility to handle this in a convenient +way, allowing customization, graceful degradation, accessibility, as +well as themability: @dfn{Icons}. + +The central macro here is @code{define-icon}, and here's a simple +example: + +@lisp +(define-icon outline-open button + '((image "right.svg" "open.xpm" "open.pbm" :height line) + (emoji "▶️") + (symbol "▶" "➤") + (text "open" :face icon-button)) + "Icon used for buttons for opening a section in outline buffers." + :version "29.1" + :help-echo "Open this section") +@end lisp + +Which alternative will actually be displayed depends on the value of +the user option @code{icon-preference} (@pxref{Icons,,, emacs, The GNU +Emacs Manual}) and on the results of run-time checks for what the +current frame's terminal can actually display. + +The macro in the example above defines @code{outline-open} as an icon, +and inherits properties from the icon called @code{button} (so this is +meant as a clickable button to be inserted in a buffer). It is +followed by a list of @dfn{icon types} along with the actual icon +shapes themselves. In addition, there's a doc string and various +keywords that contain additional information and properties. + +To instantiate an icon, you use @code{icon-string}, which will +consult the current Customize theming, and the @code{icon-preference} +user option, and finally what the Emacs is able to actually display. +If @code{icon-preference} is @code{(image emoji symbol text)} (i.e., +allowing all of these forms of icons), in this case, +@code{icon-string} will first check that Emacs is able to display +images at all, and then whether it has support for each of those +different image formats. If that fails, Emacs will check whether +Emacs can display emojis (in the current frame). If that fails, it'll +check whether it can display the symbol in question. If that fails, +it'll use the plain text version. + +For instance, if @code{icon-preference} doesn't contain @code{image} +or @code{emoji}, it'll skip those entries. + +Code can confidently call @code{icon-string} in all circumstances and +be sure that something readable will appear on the screen, no +matter whether the user is on a graphical terminal or a text terminal, +and no matter which features Emacs was built with. + +@defmac define-icon name parent specs doc &rest keywords +Define an icon @var{name}, a symbol, with the display alternatives in +@var{spec}, that can be later instantiated using @code{icon-string}. +The @var{name} is the name of the resulting keyword. + +The resulting icon will inherit specs from @var{parent}, and from +their parent's parents, and so on, and the lowest descendent element +wins. + +@var{specs} is a list of icon specifications. The first element of each +specification is the type, and the rest is something that can be used +as an icon of that type, and then optionally followed by a keyword +list. The following icon types are available: + +@cindex icon types +@table @code +@item image +In this case, there may be many images listed as candidates. Emacs +will choose the first one that the current Emacs instance can show. +If an image is listed is an absolute file name, it's used as is, but it's +otherwise looked up in the list @code{image-load-path} +(@pxref{Defining Images}). + +@item emoji +This should be a (possibly colorful) emoji. + +@item symbol +This should be a (monochrome) symbol character. + +@item text +Icons should also have a textual fallback. This can also be used for +the visually impaired: if @code{icon-preference} is just +@code{(text)}, all icons will be replaced by text. +@end table + +Various keywords may follow the list of icon specifications. For +instance: + +@example +(symbol "▶" "➤" :face icon-button) +@end example + +Unknown keywords are ignored. The following keywords are allowed: + +@cindex icon keywords +@table @code +@item :face +The face to be used for the icon. + +@item :height +This is only valid for @code{image} icons, and can be either a number +(which specifies the height in pixels), or the symbol @code{line}, +which will use the default line height in the currently selected +window. +@end table + +@var{doc} should be a doc string. + +@var{keywords} is a list of keyword/value pairs. The following +keywords are allowed: + +@table @code +@item :version +The (approximate) Emacs version this button first appeared. (This +keyword is mandatory.) + +@item :group +The customization group this icon belongs in. If not present, it is +inferred. + +@item :help-echo +The help string shown when hovering over the icon with the mouse +pointer. +@end table +@end defmac + +@defun icon-string icon +This function returns a string suitable for display in the current +buffer for @var{icon}. +@end defun + +@defun icon-elements icon +Alternatively, you can get a ``deconstructed'' version of @var{icon} +with this function. It returns a plist (@pxref{Property Lists}) where +the keys are @code{string}, @code{face} and @var{image}. (The latter +is only present if the icon is represented by an image.) This can be +useful if the icon isn't to be inserted directly in the buffer, but +needs some sort of pre-processing first. +@end defun + +Icons can be customized with @kbd{M-x customize-icon}. Themes can +specify changes to icons with, for instance: + +@lisp +(custom-theme-set-icons + 'my-theme + '(outline-open ((image :height 100) + (text " OPEN "))) + '(outline-close ((image :height 100) + (text " CLOSE " :face warning)))) +@end lisp + + @node Xwidgets @section Embedded Native Widgets @cindex xwidget @@ -6779,7 +7180,10 @@ xwidget object, and then use that object as the display specifier in a @code{display} text or overlay property (@pxref{Display Property}). -@defun make-xwidget type title width height arguments &optional buffer + Embedded widgets can send events notifying Lisp code about changes +occurring within them. (@pxref{Xwidget Events}). + +@defun make-xwidget type title width height arguments &optional buffer related This creates and returns an xwidget object. If @var{buffer} is omitted or @code{nil}, it defaults to the current buffer. If @var{buffer} names a buffer that doesn't exist, it will be @@ -6792,7 +7196,17 @@ The WebKit component. @end table The @var{width} and @var{height} arguments specify the widget size in -pixels, and @var{title}, a string, specifies its title. +pixels, and @var{title}, a string, specifies its title. @var{related} +is used internally by the WebKit widget, and specifies another WebKit +widget that the newly created widget should share settings and +subprocesses with. + +The xwidget that is returned will be killed alongside its buffer +(@pxref{Killing Buffers}). You can also kill it using +@code{kill-xwidget}. Once it is killed, the xwidget may continue to +exist as a Lisp object and act as a @code{display} property until all +references to it are gone, but most actions that can be performed on +live xwidgets will no longer be available. @end defun @defun xwidgetp object @@ -6800,6 +7214,17 @@ This function returns @code{t} if @var{object} is an xwidget, @code{nil} otherwise. @end defun +@defun xwidget-live-p object +This function returns @code{t} if @var{object} is an xwidget that +hasn't been killed, and @code{nil} otherwise. +@end defun + +@defun kill-xwidget xwidget +This function kills @var{xwidget}, by removing it from its buffer and +releasing window system resources it holds. +@end defun + +@cindex xwidget property list @defun xwidget-plist xwidget This function returns the property list of @var{xwidget}. @end defun @@ -6810,7 +7235,12 @@ property list given by @var{plist}. @end defun @defun xwidget-buffer xwidget -This function returns the buffer of @var{xwidget}. +This function returns the buffer of @var{xwidget}. If @var{xwidget} +has been killed, it returns @code{nil}. +@end defun + +@defun set-xwidget-buffer xwidget buffer +This function sets the buffer of @var{xwidget} to @var{buffer}. @end defun @defun get-buffer-xwidgets buffer @@ -6873,6 +7303,130 @@ This function returns the current setting of @var{xwidget}s query-on-exit flag, either @code{t} or @code{nil}. @end defun +@defun xwidget-perform-lispy-event xwidget event frame +Send an input event @var{event} to @var{xwidget}. The precise action +performed is platform-specific. @xref{Input Events}. + +You can optionally pass the frame on which the event was generated via +@var{frame}. On X11, modifier keys in key events will not be +considered if @var{frame} is @code{nil}, and the selected frame is not +an X-Windows frame. + +On GTK, only keyboard and function key events are supported. Mouse, +motion, and click events are dispatched to the xwidget without going +through Lisp code, and as such shouldn't require this function to be +called. +@end defun + +@defun xwidget-webkit-search query xwidget &optional case-insensitive backwards wrap-around +Start an incremental search on the WebKit widget @var{xwidget} with +the string @var{query} as the query. @var{case-insensitive} denotes +whether or not the search is case-insensitive, @var{backwards} +determines if the search is performed backwards towards the start of +the document, and @var{wrap-around} determines whether or not the +search terminates at the end of the document. + +If the function is called while a search query is already present, +then the query specified here will replace the existing query. + +To stop a search query, use @code{xwidget-webkit-finish-search}. +@end defun + +@defun xwidget-webkit-next-result xwidget +Display the next search result in @var{xwidget}. This function will +signal an error if a search query has not been already started in +@var{xwidget} through @code{xwidget-webkit-search}. + +If @code{wrap-around} was non-nil when @code{xwidget-webkit-search} +was called, then the search will restart from the beginning of the +document when its end is reached. +@end defun + +@defun xwidget-webkit-previous-result xwidget +Display the previous search result in @var{xwidget}. This function +signals an error if a search query has not been already started in +@var{xwidget} through @code{xwidget-webkit-search}. + +If @code{wrap-around} was non-nil when @code{xwidget-webkit-search} +was called, then the search will restart from the end of the +document when its beginning is reached. +@end defun + +@defun xwidget-webkit-finish-search xwidget +Finish a search operation started with @code{xwidget-webkit-search} in +@var{xwidget}. If there is no query currently ongoing, this function +signals an error. +@end defun + +@defun xwidget-webkit-load-html xwidget text &optional base-uri +Load @var{text}, a string, into @var{xwidget}, which should be a +WebKit xwidget. Any HTML markup in @var{text} will be processed +by @var{xwidget} while rendering the text. + +Optional argument @var{base-uri}, which should be a string, specifies +the absolute location of the web resources referenced by @var{text}, +to be used for resolving relative links in @var{text}. +@end defun + +@defun xwidget-webkit-goto-history xwidget rel-pos +Make @var{xwidget}, a WebKit widget, load the @var{rel-pos}th element +in its navigation history. + +If @var{rel-pos} is zero, the current page will be reloaded instead. +@end defun + +@defun xwidget-webkit-back-forward-list xwidget &optional limit +Return the navigation history of @var{xwidget}, up to @var{limit} +items in each direction. If not specified, @var{limit} defaults to +50. + +The returned value is a list of the form @w{@code{(@var{back} +@var{here} @var{forward})}}, where @var{here} is the current +navigation item, while @var{back} is a list of items containing the +items recorded by WebKit before the current navigation item, and +@var{forward} is a list of items recorded after the current navigation +item. @var{back}, @var{here} and @var{forward} can all be @code{nil}. + +When @var{here} is @code{nil}, it means that no items have been +recorded yet; if @var{back} or @var{forward} are @code{nil}, it means +that there is no history recorded before or after the current item +respectively. + +Navigation items are themselves lists of the form @w{@code{(@var{idx} +@var{title} @var{uri})}}. In these lists, @var{idx} is an index that +can be passed to @code{xwidget-webkit-goto-history}, @var{title} is +the human-readable title of the item, and @var{uri} is the URI of the +item. The user should normally have no reason to load @var{uri} +manually to reach a specific history item. Instead, @var{idx} should +be passed as an index to @code{xwidget-webkit-goto-history}. +@end defun + +@defun xwidget-webkit-estimated-load-progress xwidget +Return an estimate of how much data is remaining to be transferred +before the page displayed by the WebKit widget @var{xwidget} is fully +loaded. + +The value returned is a float ranging between 0.0 and 1.0. +@end defun + +@defun xwidget-webkit-set-cookie-storage-file xwidget file +Make the WebKit widget @var{xwidget} store cookies in @var{file}. + +@var{file} must be an absolute file name. The new setting will also +affect any xwidget that was created with @var{xwidget} as the +@code{related} argument to @code{make-xwidget}, and widgets related to +those as well. + +If this function is not called at least once on @var{xwidget} or a +related widget, @var{xwidget} will not store cookies on disk at all. +@end defun + +@defun xwidget-webkit-stop-loading xwidget +Terminate any data transfer still in progress in the WebKit widget +@var{xwidget} as part of a page-loading operation. If a page is not +being loaded, this function does nothing. +@end defun + @node Buttons @section Buttons @cindex buttons in buffers @@ -7067,7 +7621,7 @@ This inserts a button with the label @var{label} at point, using text properties. @end defun -@defun button-buttonize string callback &optional data +@defun buttonize string callback &optional data Sometimes it's more convenient to make a string into a button without inserting it into a buffer immediately, for instance when creating data structures that may then, later, be inserted into a buffer. This @@ -7195,7 +7749,7 @@ end of the buffer continues from the other end. If @var{display-message} is non-@code{nil}, the button's help-echo string is displayed. Any button with a non-@code{nil} @code{skip} property is skipped over. Returns the button found, and signals an error if no -buttons can be found. If @var{no-error} is non-@code{nil}, return nil +buttons can be found. If @var{no-error} is non-@code{nil}, return @code{nil} instead of signaling the error. @end deffn @@ -7207,7 +7761,7 @@ end of the buffer continues from the other end. If @var{display-message} is non-@code{nil}, the button's help-echo string is displayed. Any button with a non-@code{nil} @code{skip} property is skipped over. Returns the button found, and signals an error if no -buttons can be found. If @var{no-error} is non-@code{nil}, return nil +buttons can be found. If @var{no-error} is non-@code{nil}, return @code{nil} instead of signaling the error. @end deffn @@ -7543,16 +8097,14 @@ The string is formatted #RRGGBB (hash followed by six hex digits)." (kill-buffer nil)) (setq colorcomp-mode-map - (let ((m (make-sparse-keymap))) - (suppress-keymap m) - (define-key m "i" 'colorcomp-R-less) - (define-key m "o" 'colorcomp-R-more) - (define-key m "k" 'colorcomp-G-less) - (define-key m "l" 'colorcomp-G-more) - (define-key m "," 'colorcomp-B-less) - (define-key m "." 'colorcomp-B-more) - (define-key m " " 'colorcomp-copy-as-kill-and-exit) - m)) + (define-keymap :suppress t + "i" 'colorcomp-R-less + "o" 'colorcomp-R-more + "k" 'colorcomp-G-less + "l" 'colorcomp-G-more + "," 'colorcomp-B-less + "." 'colorcomp-B-more + "SPC" 'colorcomp-copy-as-kill-and-exit)) @end smallexample Note that we never modify the data in each node, which is fixed when the @@ -7855,7 +8407,10 @@ help buffer. The window's display table, if there is one, takes precedence over the buffer's display table. If neither exists, Emacs tries to use the standard display table; if that is @code{nil}, Emacs uses the usual -character display conventions (@pxref{Usual Display}). +character display conventions (@pxref{Usual Display}). (Emacs does +not ``merge'' display tables: For instance, if the window has a +display table, the buffer's display table and the standard display +table are completely ignored.) Note that display tables affect how the mode line is displayed, so if you want to force redisplay of the mode line using a new display @@ -7961,7 +8516,14 @@ there is no available font (on a graphical display), and characters which cannot be encoded by the terminal's coding system (on a text terminal). +@findex glyphless-display-mode +The @code{glyphless-display-mode} minor mode can be used to toggle +displaying glyphless characters in a convenient manner in the current +buffer. If this mode is enabled, all the glyphless characters are +displayed as boxes that display acronyms of their character names. + @defvar glyphless-char-display +For more fine-grained (and global) control, this variable can be used. The value of this variable is a char-table which defines glyphless characters and how they are displayed. Each entry must be one of the following display methods: @@ -7986,7 +8548,11 @@ hexadecimal notation. @item an @acronym{ASCII} string Display a box containing that string. The string should contain at -most 6 @acronym{ASCII} characters. +most 6 @acronym{ASCII} characters. As an exception, if the string +includes just one character, on text-mode terminals that character +will be displayed without a box; this allows to handle such +``acronyms'' as a replacement character for characters that cannot be +displayed by the terminal. @item a cons cell @code{(@var{graphical} . @var{text})} Display with @var{graphical} on graphical displays, and with @@ -8004,7 +8570,7 @@ square brackets, @samp{[]}. The char-table has one extra slot, which determines how to display any character that cannot be displayed with any available font, or cannot be encoded by the terminal's coding system. Its value should be one -of the above display methods, except @code{zero-width} or a cons cell. +of the above display methods, except @code{zero-width}. If a character has a non-@code{nil} entry in an active display table, the display table takes effect; in this case, Emacs does not consult @@ -8042,10 +8608,20 @@ Characters of Unicode General Category [Cf], such as U+200E @sc{left-to-right mark}, but excluding characters that have graphic images, such as U+00AD @sc{soft hyphen}. +@item bidi-control +This is a subset of @code{format-control}, but only includes +characters that are related to bidirectional formatting control, like +U+2069 @sc{pop directional isolate} and U+202A @sc{left-to-right +embedding}. @xref{Bidirectional Display}. + +Characters of Unicode General Category [Cf], such as U+200E +@sc{left-to-right mark}, but excluding characters that have graphic +images, such as U+00AD @sc{soft hyphen}. + @item variation-selectors -Unicode VS-1 through VS-16 (U+FE00 through U+FE0F), which are used to -select between different glyphs for the same codepoints (typically -emojis). +Unicode VS-1 through VS-256 (U+FE00 through U+FE0F and U+E0100 through +U+E01EF), which are used to select between different glyphs for the same +codepoints (typically emojis). @item no-font Characters for which there is no suitable font, or which cannot be @@ -8120,6 +8696,10 @@ Emacs is displaying the frame using the Nextstep interface (used on GNUstep and macOS). @item pc Emacs is displaying the frame using MS-DOS direct screen writes. +@item haiku +Emacs is displaying the frame using the Application Kit on Haiku. +@item pgtk +Emacs is displaying the frame using pure GTK facilities. @item nil Emacs is displaying the frame on a character-based terminal. @end table @@ -8166,13 +8746,15 @@ area. On text-mode (a.k.a.@: ``TTY'') frames, tooltips are always displayed in the echo area. @end defun -@vindex x-gtk-use-system-tooltips -When Emacs is built with GTK+ support, it by default displays tooltips -using GTK+ functions, and the appearance of the tooltips is then -controlled by GTK+ settings. GTK+ tooltips can be disabled by -changing the value of the variable @code{x-gtk-use-system-tooltips} to -@code{nil}. The rest of this subsection describes how to control -non-GTK+ tooltips, which are presented by Emacs itself. +@cindex system tooltips +@vindex use-system-tooltips +When Emacs is built with the GTK+ toolkit or Haiku windowing support, +it by default displays tooltips using toolkit functions, and the +appearance of the tooltips is then controlled by the toolkit's +settings. Toolkit-provided tooltips can be disabled by changing the +value of the variable @code{use-system-tooltips} to @code{nil}. The +rest of this subsection describes how to control non-toolkit tooltips, +which are presented by Emacs itself. @cindex tooltip frames Tooltips are displayed in special frames called tooltip frames, which diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 8f38e576242..56f7b7bdfad 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -700,8 +700,16 @@ on this process. @table @kbd @item e @var{exp} @key{RET} Evaluate expression @var{exp} in the context outside of Edebug -(@code{edebug-eval-expression}). That is, Edebug tries to minimize its -interference with the evaluation. +(@code{edebug-eval-expression}). That is, Edebug tries to minimize +its interference with the evaluation. The result is shown in the echo +area, or, if this command is given a prefix, pop up a new buffer and +pretty-print the result there. + +By default, this command +suppresses the debugger during evaluation, so that an error in the +evaluated expression won't add a new error on top of the existing one. +Set the @code{debug-allow-recursive-debug} user option to a +non-@code{nil} value to override this. @item M-: @var{exp} @key{RET} Evaluate expression @var{exp} in the context of Edebug itself @@ -711,7 +719,8 @@ Evaluate expression @var{exp} in the context of Edebug itself Evaluate the expression before point, in the context outside of Edebug (@code{edebug-eval-last-sexp}). With the prefix argument of zero (@kbd{C-u 0 C-x C-e}), don't shorten long items (like strings and -lists). +lists). Any other prefix will result in the value being +pretty-printed in a separate buffer. @end table @cindex lexical binding (Edebug) @@ -1266,7 +1275,7 @@ balanced parentheses, recursive processing of forms, and recursion via indirect specifications. Here's a table of the possible elements of a specification list, with -their meanings (see @ref{Specification Examples}, for the referenced +their meanings (@pxref{Specification Examples}, for the referenced examples): @table @code diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 70cdaee2929..a3d1d804086 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -365,6 +365,7 @@ Editing Types * Keymap Type:: What function a keystroke invokes. * Overlay Type:: How an overlay is represented. * Font Type:: Fonts for displaying text. +* Xwidget Type:: Embeddable widgets. Numbers @@ -447,6 +448,9 @@ Symbols * Creating Symbols:: How symbols are kept unique. * Symbol Properties:: Each symbol has a property list for recording miscellaneous information. +* Shorthands:: Properly organize your symbol names but + type less of them. +* Symbols with Position:: Symbol variants containing integer positions Symbol Properties @@ -525,6 +529,7 @@ Variables * Variables with Restricted Values:: Non-constant variables whose value can @emph{not} be an arbitrary Lisp object. * Generalized Variables:: Extending the concept of variables. +* Multisession Variables:: Variables that survive restarting Emacs. Scoping Rules for Variable Bindings @@ -546,6 +551,10 @@ Generalized Variables * Setting Generalized Variables:: The @code{setf} macro. * Adding Generalized Variables:: Defining new @code{setf} forms. +Multisession Variables + +* Multisession Variables:: Variables that survive restarting Emacs. + Functions * What Is a Function:: Lisp functions vs. primitives; terminology. @@ -583,6 +592,7 @@ Advising Emacs Lisp Functions * Advising Named Functions:: Advising named functions. * Advice Combinators:: Ways to compose advice. * Porting Old Advice:: Adapting code using the old defadvice. +* Advice and Byte Code:: Not all functions can be advised. Macros @@ -729,6 +739,7 @@ Reading and Printing Lisp Objects * Output Functions:: Functions to print Lisp objects as text. * Output Variables:: Variables that control what the printing functions do. +* Output Overrides:: Overriding output variables. Minibuffers @@ -839,6 +850,7 @@ Keymaps * Key Lookup:: Finding a key's binding in one keymap. * Functions for Key Lookup:: How to request key lookup. * Changing Key Bindings:: Redefining a key in a keymap. +* Low-Level Key Binding:: Legacy key syntax description. * Remapping Commands:: A keymap can translate one command to another. * Translation Keymaps:: Keymaps for translating sequences of events. * Key Binding Commands:: Interactive interfaces for redefining keys. @@ -1123,6 +1135,7 @@ Frames * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shape:: Specifying the shape of the mouse pointer. * Window System Selections::Transferring text to and from other X clients. +* Yanking Media:: Yanking things that aren't plain text. * Drag and Drop:: Internals of Drag-and-Drop implementation. * Color Names:: Getting the definitions of color names. * Text Terminal Colors:: Defining colors for text terminals. @@ -1220,7 +1233,9 @@ Text * Decompression:: Dealing with compressed data. * Base 64:: Conversion to or from base 64 encoding. * Checksum/Hash:: Computing cryptographic hashes. +* Suspicious Text:: Determining whether a string is suspicious. * GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS. +* Database:: Interacting with an SQL database. * Parsing HTML/XML:: Parsing HTML and XML. * Atomic Changes:: Installing several buffer changes atomically. * Change Hooks:: Supplying functions to be run when text is changed. diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index 7e5372765f7..44a62dcebca 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -98,6 +98,10 @@ Lisp reader, not to file I/O@. @xref{Input Functions}. @item file-already-exists This is a subcategory of @code{file-error}. @xref{Writing to Files}. +@item permission-denied +This is a subcategory of @code{file-error}, which occurs when the OS +doesn't allow Emacs to access a file or a directory for some reason. + @item file-date-error This is a subcategory of @code{file-error}. It occurs when @code{copy-file} tries and fails to set the last-modification time of diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index e94e222e6a6..6e29a5403f1 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -435,7 +435,7 @@ expansion. @cindex forms, special @cindex evaluation of special forms - A @dfn{special form} is a primitive function specially marked so that + A @dfn{special form} is a primitive specially marked so that its arguments are not all evaluated. Most special forms define control structures or perform variable bindings---things which functions cannot do. @@ -846,7 +846,7 @@ The depth limit counts internal uses of @code{eval}, @code{apply}, and expressions, and recursive evaluation of function call arguments and function body forms, as well as explicit calls in Lisp code. -The default value of this variable is 800. If you set it to a value +The default value of this variable is 1600. If you set it to a value less than 100, Lisp will reset it to 100 if the given value is reached. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself has room to diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 08677f789a5..986fb22c75b 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -581,9 +581,12 @@ 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. -It is possible to read a special file (such as a FIFO or an I/O device) -with @code{insert-file-contents}, as long as @var{replace} and -@var{visit} are @code{nil}. +It is possible to read a special file (such as a FIFO or an I/O +device) with @code{insert-file-contents}, as long as @var{replace}, +and @var{visit} and @var{beg} are @code{nil}. However, you should +normally use an @var{end} argument for these files to avoid inserting +(potentially) unlimited data into the buffer (for instance, when +inserting data from @file{/dev/urandom}). @end defun @defun insert-file-contents-literally filename &optional visit beg end replace @@ -1314,6 +1317,20 @@ on the 19th, @file{aug-20} was written on the 20th, and the file @end example @end defun +@defun file-has-changed-p filename tag +This function returns non-@code{nil} if the time stamp of +@var{filename} has changed since the last call. When called for the +first time for some @var{filename}, it records the last modification +time and size of the file, and returns non-@code{nil} when +@var{filename} exists. Thereafter, when called for the same +@var{filename}, it compares the current time stamp and size with the +recorded ones, and returns non-@code{nil} only if either the time +stamp or the size (or both) are different. This is useful when a Lisp +program wants to re-read a file whenever it changes. With an optional +argument @var{tag}, which must be a symbol, the size and modification +time comparisons are limited to calls with the same tag. +@end defun + @defun file-attributes filename &optional id-format @anchor{Definition of file-attributes} This function returns a list of attributes of file @var{filename}. If @@ -1436,13 +1453,19 @@ is owned by the user with name @samp{lh}. is in the group with name @samp{users}. @item (20614 64019 50040 152000) -was last accessed on October 23, 2012, at 20:12:03.050040152 UTC. +was last accessed on October 23, 2012, at 20:12:03.050040152 UTC@. +(This timestamp is @code{(1351023123050040152 . 1000000000)} +if @code{current-time-list} is @code{nil}.) @item (20000 23 0 0) -was last modified on July 15, 2001, at 08:53:43 UTC. +was last modified on July 15, 2001, at 08:53:43.000000000 UTC@. +(This timestamp is @code{(1310720023000000000 . 1000000000)} +if @code{current-time-list} is @code{nil}.) @item (20614 64555 902289 872000) -last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC. +last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC@. +(This timestamp is @code{(1351023659902289872 . 1000000000)} +if @code{current-time-list} is @code{nil}.) @item 122295 is 122295 bytes long. (It may not contain 122295 characters, though, @@ -2083,6 +2106,9 @@ directory. Therefore, Emacs considers a file name as having two main parts: the @dfn{directory name} part, and the @dfn{nondirectory} part (or @dfn{file name within the directory}). Either part may be empty. Concatenating these two parts reproduces the original file name. +@footnote{Emacs follows the GNU convention to use the term @emph{file name} +instead of the term @emph{pathname}. We use the term @emph{path} only for +search paths, which are lists of directory names.} On most systems, the directory part is everything up to and including the last slash (backslash is also allowed in input on MS-DOS or @@ -2227,6 +2253,19 @@ and @code{file-name-nondirectory}. For example, @end example @end defun +@defun file-name-split filename +This function splits a file name into its components, and can be +thought of as the inverse of @code{string-join} with the appropriate +directory separator. For example, + +@example +(file-name-split "/tmp/foo.txt") + @result{} ("" "tmp" "foo.txt") +(string-join (file-name-split "/tmp/foo.txt") "/") + @result{} "/tmp/foo.txt" +@end example +@end defun + @node Relative File Names @subsection Absolute and Relative File Names @cindex absolute file name @@ -2406,6 +2445,15 @@ You can use this function for directory names and for file names, because it recognizes abbreviations even as part of the name. @end defun +@defun file-parent-directory filename +This function returns the directory name of the parent directory of +@var{filename}. If @var{filename} is at the root directory of the +filesystem, it returns @code{nil}. A relative @var{filename} is +assumed to be relative to @code{default-directory}, and the return +value will also be relative in that case. If the return value is +non-@code{nil}, it ends in a slash. +@end defun + @node File Name Expansion @subsection Functions that Expand Filenames @cindex expansion of file names @@ -3076,10 +3124,16 @@ except those two. It is useful as the @var{match-regexp} argument to returns @code{nil}, if directory @samp{/foo} is empty. @end defvr -@defun file-expand-wildcards pattern &optional full +@defun file-expand-wildcards pattern &optional full regexp This function expands the wildcard pattern @var{pattern}, returning a list of file names that match it. +@var{pattern} is, by default, a ``glob''/wildcard string, e.g., +@samp{"/tmp/*.png"} or @samp{"/*/*/foo.png"}, but can also be a +regular expression if the optional @var{regexp} parameter is non-nil. +In any case, the matches are applied per sub-directory, so a match +can't span a parent/sub directory. + If @var{pattern} is written as an absolute file name, the values are absolute also. @@ -3278,8 +3332,8 @@ first, before handlers for jobs such as remote file access. @ifnottex @noindent -@code{access-file}, @code{add-name-to-file}, -@code{byte-compiler-base-file-name},@* +@code{abbreviate-file-name}, @code{access-file}, +@code{add-name-to-file}, @code{byte-compiler-base-file-name},@* @code{copy-directory}, @code{copy-file}, @code{delete-directory}, @code{delete-file}, @code{diff-latest-backup-file}, @@ -3314,6 +3368,7 @@ first, before handlers for jobs such as remote file access. @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents},@* +@code{list-system-processes}, @code{load}, @code{lock-file}, @code{make-auto-save-file-name}, @code{make-directory}, @@ -3322,7 +3377,7 @@ first, before handlers for jobs such as remote file access. @code{make-nearby-temp-file}, @code{make-process}, @code{make-symbolic-link},@* -@code{process-file}, +@code{process-attributes}, @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @code{set-file-selinux-context}, @code{set-file-times}, @code{set-visited-file-modtime}, @code{shell-command}, @@ -3338,7 +3393,8 @@ first, before handlers for jobs such as remote file access. @iftex @noindent @flushleft -@code{access-file}, @code{add-name-to-file}, +@code{abbreviate-file-name}, @code{access-file}, +@code{add-name-to-file}, @code{byte-com@discretionary{}{}{}piler-base-file-name}, @code{copy-directory}, @code{copy-file}, @code{delete-directory}, @code{delete-file}, @@ -3374,6 +3430,7 @@ first, before handlers for jobs such as remote file access. @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents}, +@code{list-system-processes}, @code{load}, @code{lock-file}, @code{make-auto-save-file-name}, @code{make-direc@discretionary{}{}{}tory}, @@ -3382,7 +3439,7 @@ first, before handlers for jobs such as remote file access. @code{make-nearby-temp-file}, @code{make-process}, @code{make-symbolic-link}, -@code{process-file}, +@code{process-attributes}, @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @code{set-file-selinux-context}, @code{set-file-times}, @code{set-visited-file-modtime}, @code{shell-command}, diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index fa033add0db..262b86672da 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -60,6 +60,8 @@ The frame is displayed on a GNUstep or Macintosh Cocoa graphical terminal. @item pc The frame is displayed on an MS-DOS terminal. +@item pgtk +The frame is displayed using pure GTK facilities. @end table @end defun @@ -105,6 +107,7 @@ window of another Emacs frame. @xref{Child Frames}. * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shape:: Specifying the shape of the mouse pointer. * Window System Selections:: Transferring text to and from other X clients. +* Yanking Media:: Yanking things that aren't plain text. * Drag and Drop:: Internals of Drag-and-Drop implementation. * Color Names:: Getting the definitions of color names. * Text Terminal Colors:: Defining colors for text terminals. @@ -170,7 +173,9 @@ usually not run for the initial frame, since Emacs reads the initial file only after creating that frame. However, if the initial frame is specified to use a separate minibuffer frame (@pxref{Minibuffers and Frames}), the functions will be run for both, the minibuffer-less and -the minibuffer frame. +the minibuffer frame. Alternatively, you can add functions to these +hooks in your ``early init file'' (@pxref{Init File}), in which case +they will be in effect for the initial frame as well. @defvar frame-inherited-parameters This variable specifies the list of frame parameters that a newly @@ -213,7 +218,8 @@ The terminal and keyboard coding systems used on the terminal. @item The kind of display associated with the terminal. This is the symbol returned by the function @code{terminal-live-p} (i.e., @code{x}, -@code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}. +@code{t}, @code{w32}, @code{ns}, @code{pc}, @code{haiku}, or @code{pgtk}). +@xref{Frames}. @item A list of terminal parameters. @xref{Terminal Parameters}. @@ -452,6 +458,18 @@ monitor, the same string as returned by the function @var{display} should be the name of an X display (a string). @end deffn +@cindex monitor change functions +@defvar display-monitors-changed-functions +This variable is an abnormal hook run when the monitor configuration +changes, which can happen if a monitor is rotated, moved, added or +removed from a multiple-monitor setup, if the primary monitor changes, +or if the resolution of a monitor changes. It is called with a single +argument consisting of the terminal on which the monitor configuration +changed. Programs should call @code{display-monitor-attributes-list} +with the terminal as the argument to retrieve the new monitor +configuration on that terminal. +@end defvar + @node Frame Geometry @section Frame Geometry @cindex frame geometry @@ -677,9 +695,9 @@ The position of the top left corner of the native frame specifies the indicate that position for the various builds: @itemize @w{} -@item (1) non-toolkit and terminal frames +@item (1) non-toolkit, Haiku, and terminal frames -@item (2) Lucid, Motif and MS-Windows frames +@item (2) Lucid, Motif, and MS-Windows frames @item (3) GTK+ and NS frames @end itemize @@ -1728,15 +1746,16 @@ fit will be clipped by the window manager. @item fullscreen This parameter specifies whether to maximize the frame's width, height or both. Its value can be @code{fullwidth}, @code{fullheight}, -@code{fullboth}, or @code{maximized}. A @dfn{fullwidth} frame is as -wide as possible, a @dfn{fullheight} frame is as tall as possible, and -a @dfn{fullboth} frame is both as wide and as tall as possible. A -@dfn{maximized} frame is like a ``fullboth'' frame, except that it usually -keeps its title bar and the buttons for resizing -and closing the frame. Also, maximized frames typically avoid hiding -any task bar or panels displayed on the desktop. A ``fullboth'' frame, -on the other hand, usually omits the title bar and occupies the entire -available screen space. +@code{fullboth}, or @code{maximized}.@footnote{On PGTK frames, setting +the values @code{fullheight} and @code{fullwidth} has no effect.} A +@dfn{fullwidth} frame is as wide as possible, a @dfn{fullheight} frame +is as tall as possible, and a @dfn{fullboth} frame is both as wide and +as tall as possible. A @dfn{maximized} frame is like a ``fullboth'' +frame, except that it usually keeps its title bar and the buttons for +resizing and closing the frame. Also, maximized frames typically +avoid hiding any task bar or panels displayed on the desktop. A +``fullboth'' frame, on the other hand, usually omits the title bar and +occupies the entire available screen space. Full-height and full-width frames are more similar to maximized frames in this regard. However, these typically display an external @@ -2160,6 +2179,21 @@ prevent hanging with those window managers. If non-@code{nil}, the frame is visible on all virtual desktops on systems with virtual desktops. +@vindex shaded@r{, a frame parameter} +@item shaded +If non-@code{nil}, tell the window manager to display the frame in a +way that its contents are hidden, leaving only the title bar. + +@vindex use-frame-synchronization@r{, a frame parameter} +@item use-frame-synchronization +If non-@code{nil}, synchronize the frame redisplay with the refresh +rate of the monitor to avoid graphics tearing. At present, this is +only implemented on Haiku and the X window system inside no-toolkit +and X toolkit builds, does not work correctly with toolkit scroll +bars, and requires a compositing manager supporting the relevant +display synchronization protocols. The @code{synchronizeResize} X +resource must also be set to the string @code{"extended"}. + @vindex inhibit-double-buffering@r{, a frame parameter} @item inhibit-double-buffering If non-@code{nil}, the frame is drawn to the screen without double @@ -2190,7 +2224,10 @@ either via @code{focus-follows-mouse} (@pxref{Input Focus}) or @code{mouse-autoselect-window} (@pxref{Mouse Window Auto-selection}). This may have the unwanted side-effect that a user cannot scroll a non-selected frame with the mouse. Some window managers may not honor -this parameter. +this parameter. On Haiku, it also has the side-effect that the window +will not be able to receive any keyboard input from the user, not even +if the user switches to the frame using the key combination +@kbd{Alt-@key{TAB}}. @vindex undecorated@r{, a frame parameter} @item undecorated @@ -2351,7 +2388,10 @@ driver for OTF and TTF fonts with text shaping by the Uniscribe engine), and @code{harfbuzz} (font driver for OTF and TTF fonts with HarfBuzz text shaping) (@pxref{Windows Fonts,,, emacs, The GNU Emacs Manual}). The @code{harfbuzz} driver is similarly recommended. On -other systems, there is only one available font backend, so it does +Haiku, there can be several font drivers (@pxref{Haiku Fonts,,, emacs, +The GNU Emacs Manual}). + +On other systems, there is only one available font backend, so it does not make sense to modify this frame parameter. @vindex background-mode@r{, a frame parameter} @@ -2419,6 +2459,16 @@ opacity when it is not selected. Some window systems do not support the @code{alpha} parameter for child frames (@pxref{Child Frames}). + +@vindex alpha-background@r{, a frame parameter} +@item alpha-background +@cindex opacity, frame +@cindex transparency, frame +Sets the background transparency of the frame. Unlike the @code{alpha} +frame parameter, this only controls the transparency of the background +while keeping foreground elements such as text fully opaque. It +should be an integer between 0 and 100, where 0 means +completely transparent and 100 means completely opaque (default). @end table The following frame parameters are semi-obsolete in that they are @@ -3246,12 +3296,16 @@ parent frame's window-system window. @cindex reparent frame @cindex nest frame - The @code{parent-frame} parameter can be changed at any time. Setting -it to another frame @dfn{reparents} the child frame. Setting it to -another child frame makes the frame a @dfn{nested} child frame. Setting -it to @code{nil} restores the frame's status as a top-level frame---a -frame whose window-system window is a child of its display's root -window. + The @code{parent-frame} parameter can be changed at any time. +Setting it to another frame @dfn{reparents} the child frame. Setting +it to another child frame makes the frame a @dfn{nested} child frame. +Setting it to @code{nil} restores the frame's status as a top-level +frame---a frame whose window-system window is a child of its display's +root window.@footnote{On Haiku, child frames are only visible when a +parent frame is active, owing to a limitation of the Haiku windowing +system. Owing to the same limitation, child frames are only +guaranteed to appear above their top-level parent; that is to say, the +top-most frame in the hierarchy, which does not have a parent frame.} Since child frames can be arbitrarily nested, a frame can be both a child and a parent frame. Also, the relative roles of child and parent @@ -3479,10 +3533,18 @@ enabled. Typically, @var{body} would use @code{read-event} to read the motion events and modify the display accordingly. @xref{Motion Events}, for the format of mouse motion events. -The value of @code{track-mouse} is that of the last form in @var{body}. -You should design @var{body} to return when it sees the up-event that -indicates the release of the button, or whatever kind of event means -it is time to stop tracking. +The value of @code{track-mouse} is that of the last form in +@var{body}. You should design @var{body} to return when it sees the +up-event that indicates the release of the button, or whatever kind of +event means it is time to stop tracking. Its value also controls how +mouse events are reported while a mouse button is held down: if it is +@code{dropping} or @code{drag-source}, the motion events are reported +relative to the frame underneath the pointer. If there is no such +frame, the events will be reported relative to the frame the mouse +buttons were first pressed on. In addition, the @code{posn-window} of +the mouse position list will be @code{nil} if the value is +@code{drag-source}. This is useful to determine if a frame is not +directly visible underneath the mouse pointer. The @code{track-mouse} form causes Emacs to generate mouse motion events by binding the variable @code{track-mouse} to a @@ -3726,6 +3788,13 @@ still use a menu keymap to implement it. To make the contents vary, add a hook function to @code{menu-bar-update-hook} to update the contents of the menu keymap as necessary. +@defvar x-pre-popup-menu-hook + A normal hook run immediately before a pop-up menu is displayed, +either directly by calling @code{x-popup-menu}, or through a menu +keymap. It won't be called if @code{x-popup-menu} returns for some +other reason without displaying a pop-up menu. +@end defvar + @node Dialog Boxes @section Dialog Boxes @cindex dialog boxes @@ -3829,8 +3898,9 @@ in the buffer. The default is to use the @code{arrow} (non-text) pointer style. @end defopt - When using X, you can specify what the @code{text} pointer style -really looks like by setting the variable @code{x-pointer-shape}. + When using some window systems, you can specify what the @code{text} +pointer style really looks like by setting the variable +@code{x-pointer-shape}. @defvar x-pointer-shape This variable specifies the pointer shape to use ordinarily in the @@ -3878,11 +3948,18 @@ upper-case names, in accord with X Window System conventions. If @var{type} is @code{nil}, that stands for @code{PRIMARY}. If @var{data} is @code{nil}, it means to clear out the selection. -Otherwise, @var{data} may be a string, a symbol, an integer (or a cons -of two integers or list of two integers), an overlay, or a cons of two -markers pointing to the same buffer. An overlay or a pair of markers -stands for text in the overlay or between the markers. The argument -@var{data} may also be a vector of valid non-vector selection values. +Otherwise, @var{data} may be a string, a symbol, an integer, an +overlay, or a cons of two markers pointing to the same buffer. An +overlay or a pair of markers stands for text in the overlay or between +the markers. The argument @var{data} may also be a vector of valid +non-vector selection values. + +If @var{data} is a string, then its text properties can specify values +used for individual data types. For example, if @var{data} has a +property named @code{text/uri-list}, then a call to +@code{gui-get-selection} with the data type @code{text/uri-list} will +result in the value of that property being used instead of @var{data} +itself. This function returns @var{data}. @end deffn @@ -3925,20 +4002,91 @@ For backward compatibility, there are obsolete aliases names of @code{gui-get-selection} and @code{gui-set-selection} before Emacs 25.1. +@node Yanking Media +@section Yanking Media + + If you choose, for instance, ``Copy Image'' in a web browser, that +image is put onto the clipboard, and Emacs can access it via +@code{gui-get-selection}. But in general, inserting image data into +an arbitrary buffer isn't very useful---you can't really do much with +it by default. + + So Emacs has a system to let modes register handlers for these +``complicated'' selections. + +@defun yank-media-handler types handler +@var{types} can be a @acronym{MIME} media type symbol, a regexp to +match these, or a list of these symbols and regexps. For instance: + +@example +(yank-media-handler 'text/html #'my-html-handler) +(yank-media-handler "image/.*" #'my-image-handler) +@end example + +A mode can register as many handlers as required. + + The @var{handler} function is called with two parameters: The +@acronym{MIME} media type symbol and the data (as a string). The +handler should then insert the object into the buffer, or save it, or +do whatever is appropriate for the mode. +@end defun + + The @code{yank-media} command will consult the registered handlers in +the current buffer, compare that with the available media types on the +clipboard, and then pass on the matching selection to the handler (if +any). If there's more than one matching selection, the user is +queried first. + + The @code{yank-media-types} command can be used to explore the +clipboard/primary selection. It lists all the media types that are +currently available, and can be handy when creating handlers---to see +what data is actually available. Some applications put a surprising +amount of different data types on the clipboard. + @node Drag and Drop @section Drag and Drop @cindex drag and drop + When the user drops something from another application over Emacs, +Emacs will try to insert any text and open any URL that was dropped. +If text was dropped, then it will always be inserted at the location +of the mouse pointer when the drop happened, or saved in the kill ring +if insertion failed (which can happen if the buffer is read-only). If +it was an URL, then Emacs tries to call an appropriate handler +function by first matching the URL against regexps defined in +@code{dnd-protocol-alist}, and then against @code{browse-url-handlers} +and @code{browse-url-default-handlers}, and failing that, inserting +the URL as plain text. + +@defvar dnd-protocol-alist + This variable is a list of cons cells of the form +@w{@code{(@var{pattern} . @var{action})}}. @var{pattern} is a regexp +that URLs are matched against after being dropped. @var{action} is a +function that is called with two arguments should a URL being dropped +match @var{pattern}: the URL being dropped, and the action being +performed for the drop (one of the symbols @code{copy}, @code{move}, +@code{link}, @code{private} or @code{ask}). +@end defvar + +@cindex drag and drop, X +@cindex drag and drop, other formats + Emacs implements drag-and-drop for text and URLs individually for +each window system, and does not by default support the dropping of +anything else. Code that wishes to support the dropping of content +types not supported by Emacs can utilize the X-specific interface +described below: + @vindex x-dnd-test-function @vindex x-dnd-known-types - When a user drags something from another application over Emacs, that other -application expects Emacs to tell it if Emacs can handle the data that is -dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine -what to reply. The default value is @code{x-dnd-default-test-function} -which accepts drops if the type of the data to be dropped is present in -@code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or -@code{x-dnd-known-types} if you want Emacs to accept or reject drops based -on some other criteria. + When a user drags something from another application over Emacs on +the X Window System, that other application expects Emacs to tell it +if Emacs can handle the data that was dragged. The variable +@code{x-dnd-test-function} is used by Emacs to determine what to +reply. The default value is @code{x-dnd-default-test-function} which +accepts drops if the type of the data to be dropped is present in +@code{x-dnd-known-types}. You can customize +@code{x-dnd-test-function} and/or @code{x-dnd-known-types} if you want +Emacs to accept or reject drops based on some other criteria. @vindex x-dnd-types-alist If you want to change the way Emacs handles drop of different types @@ -3946,16 +4094,228 @@ or add a new type, customize @code{x-dnd-types-alist}. This requires detailed knowledge of what types other applications use for drag and drop. -@vindex dnd-protocol-alist -@vindex browse-url-handlers -@vindex browse-url-default-handlers - When an URL is dropped on Emacs it may be a file, but it may also be -another URL type (https, etc.). Emacs first checks -@code{dnd-protocol-alist} to determine what to do with the URL@. If -there is no match there, Emacs looks for a match in -@code{browse-url-handlers} and @code{browse-url-default-handlers}. If -still no match has been found, the text for the URL is inserted. If -you want to alter Emacs behavior, you can customize these variables. + Those data types are typically implemented as special data types an +X selection provided by the other application can be converted to. +They can either be the same data types that are typically accepted by +@code{gui-set-selection}, or they can be MIME types, depending on the +specific drag-n-drop protocol being used. Plain text may be +@code{"STRING"} or @code{"text/plain"}, for example. + +@vindex x-dnd-direct-save-function + However, @code{x-dnd-types-alist} does not handle a special kind of +drop sent by a program which wants Emacs to save a file in a location +Emacs must determine by itself. These drops are handled via the +variable @code{x-dnd-direct-save-function}, which should be a function +that accepts two arguments. If the first argument is non-@code{nil}, +then the second argument is a string describing the name (with no +leading directory) that the other program recommends the file be saved +under, and the function should return the complete file name under +which it will be saved. Otherwise, the file has already been saved, +and the second argument is the complete name of the file. The +function should then perform whatever action is appropriate (i.e., +open the file or refresh the directory listing.) + +@cindex initiating drag-and-drop + On capable window systems, Emacs also supports dragging contents +from its frames to windows of other applications. + +@cindex drop target, in drag-and-drop operations +@defun dnd-begin-text-drag text &optional frame action allow-same-frame +This function begins dragging text from @var{frame} to another program +(known as the @dfn{drop target}), and returns the result of +drag-and-drop operation when the text is dropped or the drag-and-drop +operation is canceled. @var{text} is the text that will be inserted +by the drop target. + +@var{action} must be one of the symbols @code{copy} or @code{move}, +where @code{copy} means that @var{text} should be inserted by the drop +target, and @code{move} means the same as @code{copy}, but in addition +the caller may have to delete @var{text} from its source as explained +below. + +@var{frame} is the frame where the mouse is currently held down, or +@code{nil}, which means to use the selected frame. This function may +return immediately if no mouse buttons are held down, so it should be +only called immediately after a @code{down-mouse-1} or similar event +(@pxref{Mouse Events}), with @var{frame} set to the frame where that +event was generated (@pxref{Click Events}). + +@var{allow-same-frame} specifies whether or not drops on top of +@var{frame} itself are to be ignored. + +The return value specifies the action that the drop target actually +performed, and optionally what the caller should do. It can be one of +the following symbols: + +@table @code +@item copy +The drop target inserted the dropped text. + +@item move +The drop target inserted the dropped text, but in addition the caller +should delete @var{text} from wherever it originated, such as its +buffer. + +@item private +The drop target performed some other unspecified action. + +@item nil +The drag-and-drop operation was canceled. +@end table + +@end defun + +@defun dnd-begin-file-drag file &optional frame action allow-same-frame +This function begins dragging @var{file} from @var{frame} to another +program, and returns the result of the drag-and-drop operation when +the file is dropped or the drag-and-drop operation is canceled. + +If @var{file} is a remote file, then a temporary copy will be made. + +@var{action} must be one of the symbols @code{copy}, @code{move} or +@code{link}, where @code{copy} means that @var{file} should be opened +or copied by the drop target, @code{move} means the drop target should +move the file to another location, and @code{link} means the drop +target should create a symbolic link to @var{file}. It is an error to +specify @code{link} as the action if @var{file} is a remote file. + +@var{frame} and @var{allow-same-frame} have the same meaning as in +@code{dnd-begin-text-drag}. + +The return value is the action that the drop target actually +performed, which can be one of the following symbols: + +@table @code +@item copy +The drop target opened or copied @var{file} to a different location. + +@item move +The drop target moved @var{file} to a different location. + +@item link +The drop target (usually a file manager) created a symbolic link to +@var{file}. + +@item private +The drop target performed some other unspecified action. + +@item nil +The drag-and-drop operation was canceled. +@end table + +@end defun + +@defun dnd-begin-drag-files files &optional frame action allow-same-frame +This function is like @code{dnd-begin-file-drag}, except that +@var{files} is a list of files. If the drop target doesn't support +dropping multiple files, then the first file will be used instead. +@end defun + +@defun dnd-direct-save file name &optional frame allow-same-frame +This function is similar to @code{dnd-begin-file-drag} (with the +default action of copy), but instead of specifying the action you +specify the name of the copy created by the target program in +@code{name}. +@end defun + +@cindex initiating drag-and-drop, low-level + The high-level interfaces described above are implemented on top of +a lower-level primitive. If you need to drag content other than files +or text, use the low-level interface @code{x-begin-drag} +instead. However, using it will require detailed knowledge of the +data types and actions used by the programs to transfer content via +drag-and-drop on each platform you want to support. + +@defun x-begin-drag targets &optional action frame return-frame allow-current-frame follow-tooltip +This function begins a drag from @var{frame}, and returns when the +drag-and-drop operation ends, either because the drop was successful, +or because the drop was rejected. The drop occurs when all mouse +buttons are released on top of an X window other than @var{frame} (the +@dfn{drop target}), or any X window if @var{allow-current-frame} is +non-@code{nil}. If no mouse buttons are held down when the +drag-and-drop operation begins, this function may immediately return +@code{nil}. + +@var{targets} is a list of strings describing selection targets, much +like the @var{data-type} argument to @code{gui-get-selection}, that +the drop target can request from Emacs (@pxref{Window System +Selections}). + +@var{action} is a symbol describing the action recommended to the +target. It can either be @code{XdndActionCopy}, which +means to copy the contents of the selection @code{XdndSelection} to +the drop target; or @code{XdndActionMove}, which means copy as with +@code{XdndActionCopy}, and in addition the caller should delete +whatever was stored in that selection after copying it. + +@var{action} may also be an alist which associates between symbols +describing the available actions, and strings that the drop target is +expected to present to the user to choose between the available +actions. + +If @var{return-frame} is non-@code{nil} and the mouse moves over an +Emacs frame after first moving out of @var{frame}, then the frame to +which the mouse moves will be returned immediately. If +@var{return-frame} is the symbol @code{now}, then any frame underneath +the mouse pointer will be returned without waiting for the mouse to +first move out of @var{frame}. @var{return-frame} is useful when you +want to treat dragging content from one frame to another specially, +while also being able to drag content to other programs, but it is not +guaranteed to work on all systems and with all window managers. + +If @var{follow-tooltip} is non-@code{nil}, the position of any tooltip +(such as one shown by @code{tooltip-show}) will follow the location of +the mouse pointer whenever it moves during the drag-and-drop +operation. The tooltip will be hidden once all mouse buttons are +released. + +If the drop was rejected or no drop target was found, this function +returns @code{nil}. Otherwise, it returns a symbol describing the +action the target chose to perform, which can differ from @var{action} +if that isn't supported by the drop target. @code{XdndActionPrivate} +is also a valid return value in addition to @code{XdndActionCopy} and +@code{XdndActionMove}; it means that the drop target chose to perform +an unspecified action, and no further processing is required by the +caller. + +The caller must cooperate with the target to fully perform the action +chosen by the target. For example, callers should delete the buffer +text that was dragged if this function returns @code{XdndActionMove}. +@end defun + +@cindex drag and drop protocols, X + + On X Windows, several different drag-and-drop protocols are +supported by @code{x-begin-drag}. When dragging content that is known +to not be supported by a specific drag-and-drop protocol, it might be +desirable to turn that protocol off, by changing the values of the +following variables: + +@defvar x-dnd-disable-motif-protocol +When this is non-@code{nil}, the Motif drag and drop protocols are +disabled, and dropping onto programs that only understand them will +not work. +@end defvar + +@defvar x-dnd-use-offix-drop +When this is @code{nil}, the OffiX (old KDE) drag and drop protocol is +disabled. When this is the symbol @code{files}, the OffiX protocol +will only be used if @code{"FILE_NAME"} is one of the targets given to +@code{x-begin-drag}. Any other value means to use the OffiX protocol +to drop all supported content. +@end defvar + +@defvar x-dnd-use-unsupported-drop +When one of the @code{"STRING"}, @code{"UTF8_STRING"}, +@code{"COMPOUND_TEXT"} or @code{"TEXT"} targets is present in the list +given to @code{x-begin-drag}, Emacs will try to use synthesized mouse +events and the primary selection to insert the text if the drop target +doesn't support any drag-and-drop protocol at all. + +A side effect is that Emacs will become the owner of the primary +selection upon such a drop. If that is not desired, then the drop +emulation can be disabled by setting this variable to @code{nil}. +@end defvar @node Color Names @section Color Names diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index a70364c3cb5..983dfe2ec59 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -22,6 +22,7 @@ define them. * Function Cells:: Accessing or setting the function definition of a symbol. * Closures:: Functions that enclose a lexical environment. +* OClosures:: Function objects * Advising Functions:: Adding to the definition of a function. * Obsolete Functions:: Declaring functions obsolete. * Inline Functions:: Functions that the compiler will expand inline. @@ -145,7 +146,12 @@ function: This function returns @code{t} if @var{object} is any kind of function, i.e., can be passed to @code{funcall}. Note that @code{functionp} returns @code{t} for symbols that are function names, -and returns @code{nil} for special forms. +and returns @code{nil} for symbols that are macros or special forms. + +If @var{object} is not a function, this function ordinarily returns +@code{nil}. However, the representation of function objects is +complicated, and for efficiency reasons in rare cases this function +can return @code{t} even when @var{object} is not a function. @end defun It is also possible to find out how many arguments an arbitrary @@ -211,6 +217,16 @@ function. For example: @end example @end defun +@defun compiled-function-p object +This function returns @code{t} if @var{object} is a function object +that is not in the form of ELisp source code but something like +machine code or byte code instead. More specifically it returns +@code{t} if the function is built-in (a.k.a.@: ``primitive'', +@pxref{What Is a Function}), or byte-compiled (@pxref{Byte +Compilation}), or natively-compiled (@pxref{Native Compilation}), or +a function loaded from a dynamic module (@pxref{Dynamic Modules}). +@end defun + @defun subr-arity subr This works like @code{func-arity}, but only for built-in functions and without symbol indirection. It signals an error for non-built-in @@ -669,6 +685,22 @@ purposes, it is better to use @code{fset}, which does not keep such records. @xref{Function Cells}. @end defun +@defun function-alias-p object &optional noerror +Checks whether @var{object} is a function alias. If it is, it returns +a list of symbols representing the function alias chain, else +@code{nil}. For instance, if @code{a} is an alias for @code{b}, and +@code{b} is an alias for @code{c}: + +@example +(function-alias-p 'a) + @result{} (b c) +@end example + +If there's a loop in the definitions, an error will be signalled. If +@var{noerror} is non-@code{nil}, the non-looping parts of the chain is +returned instead. +@end defun + You cannot create a new primitive function with @code{defun} or @code{defalias}, but you can use them to change the function definition of any symbol, even one such as @code{car} or @code{x-popup-menu} whose @@ -969,14 +1001,14 @@ side-effects only---the values it returns are ignored, not collected into a list. @code{mapc} always returns @var{sequence}. @end defun -@defun mapconcat function sequence separator +@defun mapconcat function sequence &optional separator @code{mapconcat} applies @var{function} to each element of @var{sequence}; the results, which must be sequences of characters (strings, vectors, or lists), are concatenated into a single string return value. Between each pair of result sequences, @code{mapconcat} inserts the characters from @var{separator}, which also must be a -string, or a vector or list of characters. @xref{Sequences Arrays -Vectors}. +string, or a vector or list of characters; a @code{nil} value is +treated as the empty string. @xref{Sequences Arrays Vectors}. The argument @var{function} must be a function that can take one argument and returns a sequence of characters: a string, a vector, or @@ -994,8 +1026,7 @@ string. @group (mapconcat (lambda (x) (format "%c" (1+ x))) - "HAL-8000" - "") + "HAL-8000") @result{} "IBM.9111" @end group @end example @@ -1494,6 +1525,116 @@ exposed to the rest of the Lisp world is considered an internal implementation detail. For this reason, we recommend against directly examining or altering the structure of closure objects. +@node OClosures +@section Open Closures + +Traditionally, functions are opaque objects which offer no other +functionality but to call them. Emacs Lisp functions aren't fully +opaque since you can extract some info out of them such as their +docstring, their arglist, or their interactive spec, but they are +mostly opaque. This is usually what we want, but occasionally we need +functions to expose a bit more information about themselves. + +OClosures are functions which carry additional type information, +and expose some information in the form of slots which you can access +via accessor functions. + +They are defined in two steps: first @code{oclosure-define} is used to +define new OClosure types by specifying the slots carried by those +OClosures, and then @code{oclosure-lambda} is used to create an +OClosure object of a given type. + +Say we want to define keyboard macros, i.e. interactive functions +which re-execute a sequence of key events. You could do it with +a plain function as follows: +@example +(defun kbd-macro (key-sequence) + (lambda (&optional arg) + (interactive "P") + (execute-kbd-macro key-sequence arg))) +@end example +But with such a definition there is no easy way to extract the +@var{key-sequence} from that function, for example to print it. + +We can solve this problem using OClosures as follows. First we define +the type of our keyboard macros (to which we decided to add +a @code{counter} slot while at it): +@example +(oclosure-define kbd-macro + "Keyboard macro." + keys (counter :mutable t)) +@end example +After which we can rewrite our @code{kbd-macro} function: +@example +(defun kbd-macro (key-sequence) + (oclosure-lambda (kbd-macro (keys key-sequence) (counter 0)) + (&optional arg) + (interactive "p") + (execute-kbd-macro keys arg) + (setq counter (1+ counter)))) +@end example +As you can see, the @code{keys} and @code{counter} slots of the +OClosure can be accessed as local variables from within the body +of the OClosure. But we can now also access them from outside of the +body of the OClosure, for example to describe a keyboard macro: +@example +(defun describe-kbd-macro (km) + (if (not (eq 'kbd-macro (oclosure-type km))) + (message "Not a keyboard macro") + (let ((keys (kbd-macro--keys km)) + (counter (kbd-macro--counter km))) + (message "Keys=%S, called %d times" keys counter)))) +@end example +Where @code{kbd-macro--keys} and @code{kbd-macro--counter} are +accessor functions generated by the @code{oclosure-define} macro. + +@defmac oclosure-define name &optional docstring &rest slots +This macro defines a new OClosure type along with accessor functions +for its slots. @var{name} can be a symbol (the name of +the new type), or a list of the form @code{(@var{name} . @var{type-props})} in +which case @var{type-props} is a list of additional properties. +@var{slots} is a list of slot descriptions where each slot can be +either a symbol (the name of the slot) or it can be of the form +@code{(@var{slot-name} . @var{slot-props})} where @var{slot-props} is +a property list. + +For each slot, the macro creates an accessor function named +@code{@var{name}--@var{slot-name}}. By default slots are immutable. +If you need a slot to be mutable, you need to specify it with the +@code{:mutable} slot property, after which it can be mutated for +example with @code{setf}. + +Beside slot accessors, the macro can create a predicate and +functional update functions according to @var{type-props}: +a @code{(:predicate @var{pred-name})} in the @var{type-props} causes +the definition of a predicate function under the name @var{pred-name}, +and @code{(:copier @var{copier-name} @var{copier-arglist})} causes the +definition of a functional update function which takes an OClosure of +type @var{name} as first argument and returns a copy of it with the +slots named in @var{copier-arglist} modified to the value passed in the +corresponding argument. +@end defmac + +@defmac oclosure-lambda (type . slots) arglist &rest body +This macro creates an anonymous OClosure of type @var{type}. +@var{slots} should be a list of elements of the form @code{(@var{slot-name} +@var{exp})}. +At run time, each @var{exp} is evaluated, in order, after which +the OClosure is created with its slots initialized with the +resulting values. + +When called as a function, the OClosure will accept arguments +according to @var{arglist} and will execute the code in @var{body}. +@var{body} can refer to the value of any of its slot directly as if it +were a local variable that had been captured by static scoping. +@end defmac + +@defun oclosure-type object +This function returns the OClosure type (a symbol) of @var{object} if it is an +OClosure, and @code{nil} otherwise. +@end defun + + @node Advising Functions @section Advising Emacs Lisp Functions @cindex advising functions @@ -1586,6 +1727,7 @@ ways to do it. The added function is also called a piece of @emph{advice}. * Advising Named Functions:: Advising named functions. * Advice Combinators:: Ways to compose advice. * Porting Old Advice:: Adapting code using the old defadvice. +* Advice and Byte Code:: Not all functions can be advised. @end menu @node Core Advising Primitives @@ -2007,6 +2149,37 @@ changing @code{ad-return-value}, whereas new @code{:after} advice cannot, so when porting such old @code{after} advice, you'll need to turn it into new @code{:around} or @code{:filter-return} advice instead. +@c This is its own node because we link to it from *Help* buffers. +@node Advice and Byte Code +@subsection Advice and Byte Code +@cindex compiler macros, advising +@cindex @code{byte-compile} and @code{byte-optimize}, advising + + Not all functions can be reliably advised. The byte compiler may +choose to replace a call to a function with a sequence of instructions +that doesn't call the function you were interested in altering. + +This usually happens due to one of the three following mechanisms: + +@table @asis +@item @code{byte-compile} properties +If a function's symbol has a @code{byte-compile} property, that +property will be used instead of the symbol's function definition. +@xref{Compilation Functions}. + +@item @code{byte-optimize} properties +If a function's symbol has a @code{byte-optimize} property, the byte +compiler may rewrite the function arguments, or decide to use a +different function altogether. + +@item @code{compiler-macro} declare forms +A function can have a special @code{compiler-macro} @code{declare} +form in its definition (@pxref{Declare Form}) that defines an +@dfn{expander} to call when compiling the function. The expander +could then cause the produced byte-code not to call the original +function. +@end table + @node Obsolete Functions @section Declaring Functions Obsolete @cindex obsolete functions @@ -2138,8 +2311,8 @@ worry about how many times the body uses the arguments, as you do for macros. Alternatively, you can define a function by providing the code which -will inline it as a compiler macro. The following macros make this -possible. +will inline it as a compiler macro (@pxref{Declare Form}). The +following macros make this possible. @c FIXME: Can define-inline use the interactive spec? @defmac define-inline name args [doc] [declare] body@dots{} @@ -2295,6 +2468,7 @@ which case the warning message gives no extra details). @var{when} should be a string indicating when the function or macro was first made obsolete. +@cindex compiler macro @item (compiler-macro @var{expander}) This can only be used for functions, and tells the compiler to use @var{expander} as an optimization function. When encountering a call to the @@ -2334,6 +2508,10 @@ the current buffer. Specify that this command is meant to be applicable for @var{modes} only. +@item (interactive-args @var{arg} ...) +Specify the arguments that should be stored for @code{repeat-command}. +Each @var{arg} is on the form @code{@var{argument-name} @var{form}}. + @item (pure @var{val}) If @var{val} is non-@code{nil}, this function is @dfn{pure} (@pxref{What Is a Function}). This is the same as the @code{pure} diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index 34eda45b236..25a56bd7151 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -287,9 +287,13 @@ If two objects @var{obj1} and @var{obj2} are @code{equal}, then are the same integer. If the two objects are not @code{equal}, the values returned by -@code{sxhash-equal} are usually different, but not always; once in a -rare while, by luck, you will encounter two distinct-looking objects -that give the same result from @code{sxhash-equal}. +@code{sxhash-equal} are usually different, but not always. +@code{sxhash-equal} is designed to be reasonably fast (since it's used +for indexing hash tables) so it won't recurse deeply into nested +structures. In addition; once in a rare while, by luck, you will +encounter two distinct-looking simple objects that give the same +result from @code{sxhash-equal}. So you can't, in general, use +@code{sxhash-equal} to check whether an object has changed. @b{Common Lisp note:} In Common Lisp a similar function is called @code{sxhash}. Emacs provides this name as a compatibility alias for @@ -320,15 +324,13 @@ the same integer. compared case-insensitively. @example -(defun case-fold-string= (a b) - (eq t (compare-strings a nil nil b nil nil t))) -(defun case-fold-string-hash (a) +(defun string-hash-ignore-case (a) (sxhash-equal (upcase a))) -(define-hash-table-test 'case-fold - 'case-fold-string= 'case-fold-string-hash) +(define-hash-table-test 'ignore-case + 'string-equal-ignore-case 'string-hash-ignore-case) -(make-hash-table :test 'case-fold) +(make-hash-table :test 'ignore-case) @end example Here is how you could define a hash table test equivalent to the diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index fb0d3c203c8..154a7abeb63 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -158,6 +158,13 @@ the function definition has no documentation string. In that case, @code{documentation} returns @code{nil}. @end defun +@defun function-documentation function +Generic function used by @code{documentation} to extract the raw +docstring from a function object. You can specify how to get the +docstring of a specific function type by adding a corresponding method +to it. +@end defun + @defun face-documentation face This function returns the documentation string of @var{face} as a face. @@ -333,6 +340,16 @@ stands for no text itself. It is used only for a side effect: it specifies @var{mapvar}'s value as the keymap for any following @samp{\[@var{command}]} sequences in this documentation string. +@item \`@var{KEYSEQ}' +stands for a key sequence @var{KEYSEQ}, which will use the same face +as a command substitution. This should be used only when a key +sequence has no corresponding command, for example when it is read +directly with @code{read-key-sequence}. It must be a valid key +sequence according to @code{key-valid-p}. It can also be used with +command names, like @samp{\`M-x foo'}, where you want this to be +fontified like a keyboard sequence, but you want to inhibit +translating it into a key sequence like @samp{\[foo]} does. + @item ` (grave accent) stands for a left quote. This generates a left single quotation mark, an apostrophe, or a grave @@ -348,31 +365,16 @@ depending on the value of @code{text-quoting-style}. quotes the following character and is discarded; thus, @samp{\=`} puts @samp{`} into the output, @samp{\=\[} puts @samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the output. + +@item \+ +This indicates that the symbol directly following should not be marked +as link in the @file{*Help*} buffer. @end table @strong{Please note:} Each @samp{\} must be doubled when written in a string in Emacs Lisp. -@defopt text-quoting-style -@cindex curved quotes -@cindex curly quotes -The value of this variable is a symbol that specifies the style Emacs -should use for single quotes in the wording of help and messages. If -the variable's value is @code{curve}, the style is @t{‘like this’} -with curved single quotes. If the value is @code{straight}, the style -is @t{'like this'} with straight apostrophes. If the value is -@code{grave}, quotes are not translated and the style is @t{`like -this'} with grave accent and apostrophe, the standard style before -Emacs version 25. The default value @code{nil} acts like @code{curve} -if curved single quotes seem to be displayable, and like @code{grave} -otherwise. - -This option is useful on platforms that have problems with curved -quotes. You can customize it freely according to your personal -preference. -@end defopt - -@defun substitute-command-keys string &optional no-face +@defun substitute-command-keys string &optional no-face include-menus @vindex help-key-binding@r{ (face)} This function scans @var{string} for the above special sequences and replaces them by what they stand for, returning the result as a string. @@ -382,6 +384,11 @@ given a special face @code{help-key-binding}, but if the optional argument @var{no-face} is non-@code{nil}, the function doesn't add this face to the produced string. +@defun substitute-quotes string +This function works like @code{substitute-command-keys}, but only +replaces quote characters. +@end defun + @cindex advertised binding If a command has multiple bindings, this function normally uses the first one it finds. You can specify one particular key binding by @@ -422,6 +429,9 @@ RET minibuffer-complete-and-exit C-g abort-recursive-edit " +The keymap description will normally exclude menu items, but if +@var{include-menus} is non-@code{nil}, include them. + @group (substitute-command-keys "To abort a recursive edit from the minibuffer, type \ @@ -481,6 +491,13 @@ quotes. You can customize it freely according to your personal preference. @end defopt +@defun text-quoting-style +You should not read the value of the variable +@code{text-quoting-style} directly. Instead, use this function with +the same name to dynamically compute the correct quoting style on the +current terminal in the @code{nil} case described above. +@end defun + @node Describing Characters @section Describing Characters for Help Messages @cindex describe characters and events @@ -644,7 +661,7 @@ follows: @smallexample @group -(define-key global-map (string help-char) 'help-command) +(keymap-set global-map (key-description (string help-char)) 'help-command) (fset 'help-command help-map) @end group @end smallexample diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index 107d036202e..339e1387d2e 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -280,7 +280,6 @@ kbd-macro-termination-hook signal-hook-function C functions: -redisplay-end-trigger-functions x-lost-selection-functions x-sent-selection-functions @@ -290,7 +289,6 @@ auto-fill-function command-error-function compose-chars-after-function composition-function-table -deferred-action-function input-method-function load-read-function load-source-file-function diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 14d6c34e17d..8d2089bad8b 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -218,6 +218,14 @@ the Emacs executable that dumped them. If you want to use this function in an Emacs that was already dumped, you must run Emacs with the @samp{-batch} option. + +@vindex after-pdump-load-hook +If you're including @samp{.el} files in the dumped Emacs and that +@samp{.el} file has code that is normally run at load time, that code +won't be run when Emacs starts after dumping. To help work around +that problem, you can put functions on the +@code{after-pdump-load-hook} hook. This hook is run when starting +Emacs. @end defun @defun dump-emacs to-file from-file diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 5afd2f4ecf2..975215d6976 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -503,9 +503,11 @@ if the information is not available. @example @group emacs-build-time - @result{} (20614 63694 515336 438000) + @result{} (25194 55894 8547 617000) @end group @end example +(This timestamp is @code{(1651169878008547617 . 1000000000)} +if @code{current-time-list} was @code{nil} when Emacs was built.) @end defvar @defvar emacs-version diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 4b9252f1edf..1e4bf4eb861 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -30,6 +30,7 @@ is found. The whole process is called @dfn{key lookup}. * Key Lookup:: Finding a key's binding in one keymap. * Functions for Key Lookup:: How to request key lookup. * Changing Key Bindings:: Redefining a key in a keymap. +* Low-Level Key Binding:: Legacy key syntax description. * Remapping Commands:: A keymap can translate one command to another. * Translation Keymaps:: Keymaps for translating sequences of events. * Key Binding Commands:: Interactive interfaces for redefining keys. @@ -94,8 +95,15 @@ Manual}. (kbd "<f1> SPC") @result{} [f1 32] (kbd "C-M-<down>") @result{} [C-M-down] @end example + +@findex key-valid-p +The @code{kbd} function is very permissive, and will try to return +something sensible even if the syntax used isn't completely +conforming. To check whether the syntax is actually valid, use the +@code{key-valid-p} function. @end defun + @node Keymap Basics @section Keymap Basics @cindex key binding @@ -349,6 +357,105 @@ A full keymap is more efficient than a sparse keymap when it holds lots of bindings; for just a few, the sparse keymap is better. @end defun +@defun define-keymap &key options... &rest pairs... +You can create a keymap with the functions described above, and then +use @code{keymap-set} (@pxref{Changing Key Bindings}) to specify key +bindings in that map. When writing modes, however, you frequently +have to bind a large number of keys at once, and using +@code{keymap-set} on them all can be tedious and error-prone. Instead +you can use @code{define-keymap}, which creates a keymap and binds a +number of keys. Here's a very basic example: + +@lisp +(define-keymap + "n" #'forward-line + "f" #'previous-line + "C-c C-c" #'quit-window) +@end lisp + +This function creates a new sparse keymap, defines the keystrokes in +@var{pairs}, and returns the new keymap. It signals an error if there +are duplicate key bindings in @var{pairs}. + +@var{pairs} is a list of alternating key bindings and key definitions, +as accepted by @code{keymap-set}. In addition, the key can be the +special symbol @code{:menu}, in which case the definition should be a +menu definition as accepted by @code{easy-menu-define} (@pxref{Easy +Menu}). Here's a brief example of this usage: + +@lisp +(define-keymap :full t + "g" #'eww-reload + :menu '("Eww" + ["Exit" quit-window t] + ["Reload" eww-reload t])) +@end lisp + +A number of keywords can be used before the key/definition pairs to +change features of the new keymap. If any of the feature keywords is +missing from the @code{define-keymap} call, the default value for that +feature is @code{nil}. Here's a list of the available feature +keywords: + +@table @code +@item :full +If non-@code{nil}, create a char-table keymap (as from +@code{make-keymap}) instead of a sparse keymap (as from +@code{make-sparse-keymap} (@pxref{Creating Keymaps}). A sparse keymap +is the default. + +@item :parent +If non-@code{nil}, the value should be a keymap to use as the parent +(@pxref{Inheritance and Keymaps}). + +@item :keymap +If non-@code{nil}, the value should be a keymap. Instead of creating +a new keymap, the specified keymap is modified instead. + +@item :suppress +If non-@code{nil}, the keymap will be suppressed with +@code{suppress-keymap} (@pxref{Changing Key Bindings}). By default, +digits and the minus sign are exempt from suppressing, but if the +value is @code{nodigits}, this suppresses digits and minus-sign like +it does with other characters. + +@item :name +If non-@code{nil}, the value should be a string to use as the menu for +the keymap if you use it as a menu with @code{x-popup-menu} +(@pxref{Pop-Up Menus}). + +@item :prefix +If non-@code{nil}, the value should be a symbol to be used as a prefix +command (@pxref{Prefix Keys}). If this is the case, this symbol is +returned by @code{define-keymap} instead of the map itself. +@end table + +@end defun + +@defmac defvar-keymap name &key options... &rest pairs... +By far, the most common thing to do with a keymap is to bind it to a +variable. This is what virtually all modes do---a mode called +@code{foo} almost always has a variable called @code{foo-mode-map}. + +This macro defines @var{name} as a variable, passes @var{options} +and @var{pairs} to @code{define-keymap}, and uses the result as the +default value for the variable. It signals an error if there are +duplicate key bindings in @var{pairs}. + +@var{options} is like the keywords in @code{define-keymap}, but +there's an additional @code{:doc} keyword that provides the doc +string for the defined variable. + +Here's an example: + +@lisp +(defvar-keymap eww-textarea-map + :parent text-mode-map + "RET" #'forward-line + "TAB" #'shr-next-link) +@end lisp +@end defmac + @defun copy-keymap keymap This function returns a copy of @var{keymap}. This is almost never needed. If you want a keymap that's like another yet with a few @@ -359,7 +466,7 @@ I.e., something like: @group (let ((map (make-sparse-keymap))) (set-keymap-parent map <theirmap>) - (define-key map ...) + (keymap-set map ...) ...) @end group @end example @@ -412,10 +519,10 @@ The effect is that this keymap inherits all the bindings of but can add to them or override them with @var{elements}. If you change the bindings in @var{parent-keymap} using -@code{define-key} or other key-binding functions, these changed +@code{keymap-set} or other key-binding functions, these changed bindings are visible in the inheriting keymap, unless shadowed by the bindings made by @var{elements}. The converse is not true: if you use -@code{define-key} to change bindings in the inheriting keymap, these +@code{keymap-set} to change bindings in the inheriting keymap, these changes are recorded in @var{elements}, but have no effect on @var{parent-keymap}. @@ -474,11 +581,10 @@ override any non-@code{nil} binding in any other of the @var{maps}. @code{button-buffer-map} and @code{special-mode-map}: @example -(defvar help-mode-map - (let ((map (make-sparse-keymap))) - (set-keymap-parent map - (make-composed-keymap button-buffer-map special-mode-map)) - ... map) ... ) +(defvar-keymap help-mode-map + :parent (make-composed-keymap button-buffer-map + special-mode-map) + ...) @end example @@ -610,16 +716,16 @@ active keymap. @result{} nil @end group @group -(local-set-key "\C-p" ctl-x-map) +(keymap-local-set "C-p" ctl-x-map) @result{} nil @end group @group -(key-binding "\C-p\C-f") +(keymap-binding "C-p C-f") @result{} find-file @end group @group -(key-binding "\C-p6") +(keymap-binding "C-p 6") @result{} nil @end group @end example @@ -682,7 +788,7 @@ use, in place of the buffer's default local keymap. @cindex major mode keymap The local keymap is normally set by the buffer's major mode, and every buffer with the same major mode shares the same local keymap. -Hence, if you call @code{local-set-key} (@pxref{Key Binding Commands}) +Hence, if you call @code{keymap-local-set} (@pxref{Key Binding Commands}) to change the local keymap in one buffer, that also affects the local keymaps in other buffers with the same major mode. @@ -698,7 +804,7 @@ active keymaps, except for the global keymap. Secondly, the terminal-local variable @code{overriding-terminal-local-map} specifies a keymap that takes precedence over @emph{all} other keymaps (including @code{overriding-local-map}); this is normally used for -modal/transient keybindings (the function @code{set-transient-map} +modal/transient key bindings (the function @code{set-transient-map} provides a convenient interface for this). @xref{Controlling Active Maps}, for details. @@ -716,39 +822,7 @@ Normally it ignores @code{overriding-local-map} and then it pays attention to them. @var{position} can optionally be either an event position as returned by @code{event-start} or a buffer position, and may change the keymaps as described for -@code{key-binding}. -@end defun - -@defun key-binding key &optional accept-defaults no-remap position -This function returns the binding for @var{key} according to the -current active keymaps. The result is @code{nil} if @var{key} is -undefined in the keymaps. - -The argument @var{accept-defaults} controls checking for default -bindings, as in @code{lookup-key} (@pxref{Functions for Key Lookup}). - -When commands are remapped (@pxref{Remapping Commands}), -@code{key-binding} normally processes command remappings so as to -return the remapped command that will actually be executed. However, -if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores -remappings and returns the binding directly specified for @var{key}. - -If @var{key} starts with a mouse event (perhaps following a prefix -event), the maps to be consulted are determined based on the event's -position. Otherwise, they are determined based on the value of point. -However, you can override either of them by specifying @var{position}. -If @var{position} is non-@code{nil}, it should be either a buffer -position or an event position like the value of @code{event-start}. -Then the maps consulted are determined based on @var{position}. - -Emacs signals an error if @var{key} is not a string or a vector. - -@example -@group -(key-binding "\C-x\C-f") - @result{} find-file -@end group -@end example +@code{keymap-binding}. @end defun @node Searching Keymaps @@ -821,7 +895,7 @@ out with. This function returns the current global keymap. This is the same as the value of @code{global-map} unless you change one or the other. The return value is a reference, not a copy; if you use -@code{define-key} or other functions on it you will alter global +@code{keymap-set} or other functions on it you will alter global bindings. @example @@ -857,7 +931,7 @@ keymap. @end defun @code{current-local-map} returns a reference to the local keymap, not -a copy of it; if you use @code{define-key} or other functions on it +a copy of it; if you use @code{keymap-set} or other functions on it you will alter local bindings. @defun current-minor-mode-maps @@ -991,6 +1065,20 @@ The optional argument @var{on-exit}, if non-@code{nil}, specifies a function that is called, with no arguments, after @var{keymap} is deactivated. +The optional argument @var{message} specifies the message to display +after activating the transient map. If @var{message} is a string, it +is the format string for the message, and any @samp{%k} specifier in +that string is replaced with the list of keys from the transient map. +Any other non-@code{nil} value of @var{message} stands for the default +message format @samp{Repeat with %k}. + +@vindex set-transient-map-timeout +If the optional argument @var{timeout} is non-@code{nil}, it should be +a number that specifies how many seconds of idle time to wait before +deactivating @var{keymap}. The value of the variable +@code{set-transient-map-timeout}, if non-@code{nil}, overrides the +value of this argument. + This function works by adding and removing @var{keymap} from the variable @code{overriding-terminal-local-map}, which takes precedence over all other active keymaps (@pxref{Searching Keymaps}). @@ -1025,7 +1113,7 @@ keymap. Let's use the term @dfn{keymap entry} to describe the value found by looking up an event type in a keymap. (This doesn't include the item string and other extra elements in a keymap element for a menu item, because -@code{lookup-key} and other key lookup functions don't include them in +@code{keymap-lookup} and other key lookup functions don't include them in the returned value.) While any Lisp object may be stored in a keymap as a keymap entry, not all make sense for key lookup. Here is a table of the meaningful types of keymap entries: @@ -1113,22 +1201,18 @@ macro, a symbol that leads to one of them, or @code{nil}. Here are the functions and variables pertaining to key lookup. -@defun lookup-key keymap key &optional accept-defaults +@defun keymap-lookup keymap key &optional accept-defaults no-remap position This function returns the definition of @var{key} in @var{keymap}. All the other functions described in this chapter that look up keys use -@code{lookup-key}. Here are examples: +@code{keymap-lookup}. Here are examples: @example @group -(lookup-key (current-global-map) "\C-x\C-f") - @result{} find-file -@end group -@group -(lookup-key (current-global-map) (kbd "C-x C-f")) +(keymap-lookup (current-global-map) "C-x C-f") @result{} find-file @end group @group -(lookup-key (current-global-map) "\C-x\C-f12345") +(keymap-lookup (current-global-map) "C-x C-f 1 2 3 4 5") @result{} 2 @end group @end example @@ -1139,9 +1223,9 @@ and have extra events at the end that do not fit into a single key sequence. Then the value is a number, the number of events at the front of @var{key} that compose a complete key. -If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key} +If @var{accept-defaults} is non-@code{nil}, then @code{keymap-lookup} considers default bindings as well as bindings for the specific events -in @var{key}. Otherwise, @code{lookup-key} reports only bindings for +in @var{key}. Otherwise, @code{keymap-lookup} reports only bindings for the specific sequence @var{key}, ignoring default bindings except when you explicitly ask about them. (To do this, supply @code{t} as an element of @var{key}; see @ref{Format of Keymaps}.) @@ -1154,11 +1238,11 @@ the second example. @example @group -(lookup-key (current-global-map) "\M-f") +(keymap-lookup (current-global-map) "M-f") @result{} forward-word @end group @group -(lookup-key (current-global-map) "\ef") +(keymap-lookup (current-global-map) "ESC f") @result{} forward-word @end group @end example @@ -1169,6 +1253,20 @@ Unlike @code{read-key-sequence}, this function does not modify the specified events in ways that discard information (@pxref{Key Sequence Input}). In particular, it does not convert letters to lower case and it does not change drag events to clicks. + +Like the normal command loop, @code{keymap-lookup} will remap the +command resulting from looking up @var{key} by looking up the command +in the current keymaps. However, if the optional third argument +@var{no-remap} is non-@code{nil}, @code{keymap-lookup} returns the +command without remapping. + +If the optional argument @var{position} is non-@code{nil}, it +specifies a mouse position as returned by @code{event-start} and +@code{event-end}, and the lookup occurs in the keymaps associated with +that position, instead of in @var{keymap}. @var{position} can also be +a number or a marker, in which case it is interpreted as a buffer +position, and the function uses the keymap properties at that position +instead of at point. @end defun @deffn Command undefined @@ -1176,20 +1274,20 @@ Used in keymaps to undefine keys. It calls @code{ding}, but does not cause an error. @end deffn -@defun local-key-binding key &optional accept-defaults +@defun keymap-local-binding key &optional accept-defaults This function returns the binding for @var{key} in the current local keymap, or @code{nil} if it is undefined there. The argument @var{accept-defaults} controls checking for default bindings, -as in @code{lookup-key} (above). +as in @code{keymap-lookup} (above). @end defun -@defun global-key-binding key &optional accept-defaults +@defun keymap-global-binding key &optional accept-defaults This function returns the binding for command @var{key} in the current global keymap, or @code{nil} if it is undefined there. The argument @var{accept-defaults} controls checking for default bindings, -as in @code{lookup-key} (above). +as in @code{keymap-lookup} (above). @end defun @defun minor-mode-key-binding key &optional accept-defaults @@ -1206,7 +1304,7 @@ modes are omitted, since they would be completely shadowed. Similarly, the list omits non-prefix bindings that follow prefix bindings. The argument @var{accept-defaults} controls checking for default -bindings, as in @code{lookup-key} (above). +bindings, as in @code{keymap-lookup} (above). @end defun @defopt meta-prefix-char @@ -1267,51 +1365,63 @@ change a binding in the global keymap, the change is effective in all buffers (though it has no direct effect in buffers that shadow the global binding with a local one). If you change the current buffer's local map, that usually affects all buffers using the same major mode. -The @code{global-set-key} and @code{local-set-key} functions are +The @code{keymap-global-set} and @code{keymap-local-set} functions are convenient interfaces for these operations (@pxref{Key Binding -Commands}). You can also use @code{define-key}, a more general +Commands}). You can also use @code{keymap-set}, a more general function; then you must explicitly specify the map to change. When choosing the key sequences for Lisp programs to rebind, please follow the Emacs conventions for use of various keys (@pxref{Key Binding Conventions}). -@cindex meta character key constants -@cindex control character key constants - In writing the key sequence to rebind, it is good to use the special -escape sequences for control and meta characters (@pxref{String Type}). -The syntax @samp{\C-} means that the following character is a control -character and @samp{\M-} means that the following character is a meta -character. Thus, the string @code{"\M-x"} is read as containing a -single @kbd{M-x}, @code{"\C-f"} is read as containing a single -@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as -containing a single @kbd{C-M-x}. You can also use this escape syntax in -vectors, as well as others that aren't allowed in strings; one example -is @samp{[?\C-\H-x home]}. @xref{Character Type}. - - The key definition and lookup functions accept an alternate syntax for -event types in a key sequence that is a vector: you can use a list -containing modifier names plus one base event (a character or function -key name). For example, @code{(control ?a)} is equivalent to -@code{?\C-a} and @code{(hyper control left)} is equivalent to -@code{C-H-left}. One advantage of such lists is that the precise -numeric codes for the modifier bits don't appear in compiled files. - The functions below signal an error if @var{keymap} is not a keymap, -or if @var{key} is not a string or vector representing a key sequence. -You can use event types (symbols) as shorthand for events that are -lists. The @code{kbd} function (@pxref{Key Sequences}) is a -convenient way to specify the key sequence. +or if @var{key} is not a valid key. + +@var{key} is a string representing a single key or a series of key +strokes. Key strokes are separated by a single space character. -@defun define-key keymap key binding +Each key stroke is either a single character, or the name of an +event, surrounded by angle brackets. In addition, any key stroke +may be preceded by one or more modifier keys. Finally, a limited +number of characters have a special shorthand syntax. Here's some +example key sequences: + +@table @kbd +@item f +The key @kbd{f}. + +@item S o m +A three key sequence of the keys @kbd{S}, @kbd{o} and @kbd{m}. + +@item C-c o +A two key sequence of the keys @kbd{c} with the control modifier and +then the key @kbd{o} + +@item H-<left> +The key named @kbd{left} with the hyper modifier. + +@item M-RET +The @kbd{return} key with a meta modifier. + +@item C-M-<space> +The @kbd{space} key with both the control and meta modifiers. +@end table + +The only keys that have a special shorthand syntax are @kbd{NUL}, +@kbd{RET}, @kbd{TAB}, @kbd{LFD}, @kbd{ESC}, @kbd{SPC} and @kbd{DEL}. + +The modifiers have to be specified in alphabetical order: +@samp{A-C-H-M-S-s}, which is @samp{Alt-Control-Hyper-Meta-Shift-super}. + +@defun keymap-set keymap key binding This function sets the binding for @var{key} in @var{keymap}. (If @var{key} is more than one event long, the change is actually made in another keymap reached from @var{keymap}.) The argument @var{binding} can be any Lisp object, but only certain types are meaningful. (For a list of meaningful types, see @ref{Key Lookup}.) -The value returned by @code{define-key} is @var{binding}. +The value returned by @code{keymap-set} is @var{binding}. -If @var{key} is @code{[t]}, this sets the default binding in +If @var{key} is @kbd{<t>}, this sets the default binding in @var{keymap}. When an event has no binding of its own, the Emacs command loop uses the keymap's default binding, if there is one. @@ -1319,7 +1429,7 @@ command loop uses the keymap's default binding, if there is one. @cindex key sequence error Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap) or undefined; otherwise an error is signaled. If some prefix of -@var{key} is undefined, then @code{define-key} defines it as a prefix +@var{key} is undefined, then @code{keymap-set} defines it as a prefix key so that the rest of @var{key} can be defined as specified. If there was previously no binding for @var{key} in @var{keymap}, the @@ -1337,7 +1447,7 @@ bindings in it: @result{} (keymap) @end group @group -(define-key map "\C-f" 'forward-char) +(keymap-set map "C-f" 'forward-char) @result{} forward-char @end group @group @@ -1347,7 +1457,7 @@ map @group ;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.} -(define-key map (kbd "C-x f") 'forward-word) +(keymap-set map "C-x f" 'forward-word) @result{} forward-word @end group @group @@ -1360,14 +1470,14 @@ map @group ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.} -(define-key map (kbd "C-p") ctl-x-map) +(keymap-set map "C-p" ctl-x-map) ;; @code{ctl-x-map} @result{} [nil @dots{} find-file @dots{} backward-kill-sentence] @end group @group ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.} -(define-key map (kbd "C-p C-f") 'foo) +(keymap-set map "C-p C-f" 'foo) @result{} 'foo @end group @group @@ -1386,7 +1496,14 @@ changing an entry in @code{ctl-x-map}, and this has the effect of changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the default global map. - The function @code{substitute-key-definition} scans a keymap for +@code{keymap-set} is the general work horse for defining a key in a +keymap. When writing modes, however, you frequently have to bind a +large number of keys at once, and using @code{keymap-set} on them all +can be tedious and error-prone. Instead you can use +@code{define-keymap}, which creates a keymap and binds a number of +keys. @xref{Creating Keymaps}, for details. + +The function @code{substitute-key-definition} scans a keymap for keys that have a certain binding and rebinds them with a different binding. Another feature which is cleaner and can often produce the same results is to remap one command into another (@pxref{Remapping @@ -1485,13 +1602,181 @@ Modes}); then its keymap will automatically inherit from (defvar special-mode-map (let ((map (make-sparse-keymap))) (suppress-keymap map) - (define-key map "q" 'quit-window) + (keymap-set map "q" 'quit-window) @dots{} map)) @end group @end smallexample @end defun +@node Low-Level Key Binding +@section Low-Level Key Binding +@cindex low-level key bindings + + Historically, Emacs has supported a number of different syntaxes for +defining keys. The documented way to bind a key today is to use the +syntax supported by @code{key-valid-p}, which is what all the +functions like @code{keymap-set} and @code{keymap-lookup} supports. +This section documents the old-style syntax and interface functions; +they should not be used in new code. + +@cindex meta character key constants +@cindex control character key constants + @code{define-key} (and other low-level functions that are used to +rebind keys) understand a number of different syntaxes for the keys. + +@table @asis +@item A vector containing lists of keys. +You can use a list containing modifier names plus one base event (a +character or function key name). For example, @code{[(control ?a) +(meta b)]} is equivalent to @kbd{C-a M-b} and @code{[(hyper control +left)]} is equivalent to @kbd{C-H-left}. + +@item A string of characters with modifiers +Internally, key sequences are often represented as strings using the +special escape sequences for shift, control and meta modifiers +(@pxref{String Type}), but this representation can also be used by +users when rebinding keys. A string like @code{"\M-x"} is read as +containing a single @kbd{M-x}, @code{"\C-f"} is read as containing a +single @kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both +read as containing a single @kbd{C-M-x}. + +@item A vector of characters and key symbols +This is the other internal representation of key sequences. It +supports a fuller range of modifiers than the string representation, +and also support function keys. An example is @w{@samp{[?\C-\H-x +home]}}, which represents the @w{@kbd{C-H-x @key{home}}} key sequence. +@xref{Character Type}. +@end table + +@defun define-key keymap key binding &optional remove +This function is like @code{keymap-set} (@pxref{Changing Key +Bindings}, but understands only the legacy key syntaxes. + +In addition, this function also has a @var{remove} argument. If it is +non-@code{nil}, the definition will be removed. This is almost the +same as setting the definition to @code{nil}, but makes a difference +if the @var{keymap} has a parent, and @var{key} is shadowing the same +binding in the parent. With @var{remove}, subsequent lookups will +return the binding in the parent, whereas with a @code{nil} definition the +lookups will return @code{nil}. +@end defun + +Here are other legacy key definition functions and commands, with the +equivalent modern function to use instead in new code. + +@deffn Command global-set-key key binding +This function sets the binding of @var{key} in the current global map +to @var{binding}. Use @code{keymap-global-set} instead. +@end deffn + +@deffn Command global-unset-key key +This function removes the binding of @var{key} from the current +global map. Use @code{keymap-global-unset} instead. +@end deffn + +@deffn Command local-set-key key binding +This function sets the binding of @var{key} in the current local +keymap to @var{binding}. Use @code{keymap-local-set} instead. +@end deffn + +@deffn Command local-unset-key key +This function removes the binding of @var{key} from the current +local map. Use @code{keymap-local-unset} instead. +@end deffn + +@defun substitute-key-definition olddef newdef keymap &optional oldmap +This function replaces @var{olddef} with @var{newdef} for any keys in +@var{keymap} that were bound to @var{olddef}. In other words, +@var{olddef} is replaced with @var{newdef} wherever it appears. The +function returns @code{nil}. Use @code{keymap-substitute} instead. +@end defun + +@defun define-key-after map key binding &optional after +Define a binding in @var{map} for @var{key}, with value @var{binding}, +just like @code{define-key}, but position the binding in @var{map} after +the binding for the event @var{after}. The argument @var{key} should be +of length one---a vector or string with just one element. But +@var{after} should be a single event type---a symbol or a character, not +a sequence. The new binding goes after the binding for @var{after}. If +@var{after} is @code{t} or is omitted, then the new binding goes last, at +the end of the keymap. However, new bindings are added before any +inherited keymap. Use @code{keymap-set-after} instead of this function. +@end defun + +@defun keyboard-translate from to +This function modifies @code{keyboard-translate-table} to translate +character code @var{from} into character code @var{to}. It creates +the keyboard translate table if necessary. Use @code{key-translate} +instead. +@end defun + +@defun key-binding key &optional accept-defaults no-remap position +This function returns the binding for @var{key} according to the +current active keymaps. The result is @code{nil} if @var{key} is +undefined in the keymaps. The argument @var{accept-defaults} controls +checking for default bindings, as in @code{lookup-key} +(@pxref{Functions for Key Lookup}). If @var{no-remap} is +non-@code{nil}, @code{key-binding} ignores command remappings +(@pxref{Remapping Commands}) and returns the binding directly +specified for @var{key}. The optional argument @var{position} should +be either a buffer position or an event position like the value of +@code{event-start}; it tells the function to consult the maps +determined based on that @var{position}. + +Emacs signals an error if @var{key} is not a string or a vector. + +Use @code{keymap-lookup} instead of this function. +@end defun + +@defun lookup-key keymap key &optional accept-defaults +This function returns the definition of @var{key} in @var{keymap}. If +the string or vector @var{key} is not a valid key sequence according +to the prefix keys specified in @var{keymap}, it must be too long and +have extra events at the end that do not fit into a single key +sequence. Then the value is a number, the number of events at the +front of @var{key} that compose a complete key. + +If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key} +considers default bindings as well as bindings for the specific events +in @var{key}. Otherwise, @code{lookup-key} reports only bindings for +the specific sequence @var{key}, ignoring default bindings except when +you explicitly ask about them. + +Use @code{keymap-lookup} instead of this function. +@end defun + +@defun local-key-binding key &optional accept-defaults +This function returns the binding for @var{key} in the current +local keymap, or @code{nil} if it is undefined there. + +The argument @var{accept-defaults} controls checking for default bindings, +as in @code{lookup-key} (above). +@end defun + +@defun global-key-binding key &optional accept-defaults +This function returns the binding for command @var{key} in the +current global keymap, or @code{nil} if it is undefined there. + +The argument @var{accept-defaults} controls checking for default bindings, +as in @code{lookup-key} (above). +@end defun + +@defun event-convert-list list +This function converts a list of modifier names and a basic event type +to an event type which specifies all of them. The basic event type +must be the last element of the list. For example, + +@example +(event-convert-list '(control ?a)) + @result{} 1 +(event-convert-list '(control meta ?a)) + @result{} -134217727 +(event-convert-list '(control super f1)) + @result{} C-s-f1 +@end example +@end defun + @node Remapping Commands @section Remapping Commands @cindex remapping commands @@ -1510,7 +1795,7 @@ definition for a key binding). the following remapping: @smallexample -(define-key my-mode-map [remap kill-line] 'my-kill-line) +(keymap-set my-mode-map "<remap> <kill-line>" 'my-kill-line) @end smallexample @noindent @@ -1525,8 +1810,8 @@ In addition, remapping only works through a single level; in the following example, @smallexample -(define-key my-mode-map [remap kill-line] 'my-kill-line) -(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line) +(keymap-set my-mode-map "<remap> <kill-line>" 'my-kill-line) +(keymap-set my-mode-map "<remap> <my-kill-line>" 'my-other-kill-line) @end smallexample @noindent @@ -1538,7 +1823,7 @@ remapped to @code{my-kill-line}; if an ordinary binding specifies To undo the remapping of a command, remap it to @code{nil}; e.g., @smallexample -(define-key my-mode-map [remap kill-line] nil) +(keymap-set my-mode-map "<remap> <kill-line>" nil) @end smallexample @defun command-remapping command &optional position keymaps @@ -1671,7 +1956,7 @@ to turn the character that follows into a Hyper character: symbol (cons symbol (cdr e))))) -(define-key local-function-key-map "\C-ch" 'hyperify) +(keymap-set local-function-key-map "C-c h" 'hyperify) @end group @end example @@ -1701,55 +1986,34 @@ problematic suffixes/prefixes are @kbd{@key{ESC}}, @kbd{M-O} (which is really @section Commands for Binding Keys This section describes some convenient interactive interfaces for -changing key bindings. They work by calling @code{define-key}. +changing key bindings. They work by calling @code{keymap-set}. - People often use @code{global-set-key} in their init files + People often use @code{keymap-global-set} in their init files (@pxref{Init File}) for simple customization. For example, @smallexample -(global-set-key (kbd "C-x C-\\") 'next-line) -@end smallexample - -@noindent -or - -@smallexample -(global-set-key [?\C-x ?\C-\\] 'next-line) -@end smallexample - -@noindent -or - -@smallexample -(global-set-key [(control ?x) (control ?\\)] 'next-line) +(keymap-global-set "C-x C-\\" 'next-line) @end smallexample @noindent redefines @kbd{C-x C-\} to move down a line. @smallexample -(global-set-key [M-mouse-1] 'mouse-set-point) +(keymap-global-set "M-<mouse-1>" 'mouse-set-point) @end smallexample @noindent redefines the first (leftmost) mouse button, entered with the Meta key, to set point where you click. -@cindex non-@acronym{ASCII} text in keybindings +@cindex non-@acronym{ASCII} text in key bindings Be careful when using non-@acronym{ASCII} text characters in Lisp specifications of keys to bind. If these are read as multibyte text, as they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you must type the keys as multibyte too. For instance, if you use this: @smallexample -(global-set-key "ö" 'my-function) ; bind o-umlaut -@end smallexample - -@noindent -or - -@smallexample -(global-set-key ?ö 'my-function) ; bind o-umlaut +(keymap-global-set "ö" 'my-function) ; bind o-umlaut @end smallexample @noindent @@ -1760,20 +2024,20 @@ binding, you need to teach Emacs how to decode the keyboard by using an appropriate input method (@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}). -@deffn Command global-set-key key binding +@deffn Command keymap-global-set key binding This function sets the binding of @var{key} in the current global map to @var{binding}. @smallexample @group -(global-set-key @var{key} @var{binding}) +(keymap-global-set @var{key} @var{binding}) @equiv{} -(define-key (current-global-map) @var{key} @var{binding}) +(keymap-set (current-global-map) @var{key} @var{binding}) @end group @end smallexample @end deffn -@deffn Command global-unset-key key +@deffn Command keymap-global-unset key @cindex unbinding keys This function removes the binding of @var{key} from the current global map. @@ -1784,50 +2048,32 @@ that uses @var{key} as a prefix---which would not be allowed if @smallexample @group -(global-unset-key "\C-l") +(keymap-global-unset "C-l") @result{} nil @end group @group -(global-set-key "\C-l\C-l" 'redraw-display) +(keymap-global-set "C-l C-l" 'redraw-display) @result{} nil @end group @end smallexample - -This function is equivalent to using @code{define-key} as follows: - -@smallexample -@group -(global-unset-key @var{key}) -@equiv{} -(define-key (current-global-map) @var{key} nil) -@end group -@end smallexample @end deffn -@deffn Command local-set-key key binding +@deffn Command keymap-local-set key binding This function sets the binding of @var{key} in the current local keymap to @var{binding}. @smallexample @group -(local-set-key @var{key} @var{binding}) +(keymap-local-set @var{key} @var{binding}) @equiv{} -(define-key (current-local-map) @var{key} @var{binding}) +(keymap-set (current-local-map) @var{key} @var{binding}) @end group @end smallexample @end deffn -@deffn Command local-unset-key key +@deffn Command keymap-local-unset key This function removes the binding of @var{key} from the current local map. - -@smallexample -@group -(local-unset-key @var{key}) -@equiv{} -(define-key (current-local-map) @var{key} nil) -@end group -@end smallexample @end deffn @node Scanning Keymaps @@ -1979,6 +2225,11 @@ If @var{no-remap} is @code{nil}, return the bindings for non-@code{nil}, return the bindings for @var{command}, ignoring the fact that it is remapped. @end table + +If a command maps to a key binding like @code{[some-event]}, and +@code{some-event} has a symbol plist containing a non-@code{nil} +@code{non-key-event} property, then that binding is ignored by +@code{where-is-internal}. @end defun @deffn Command describe-bindings &optional prefix buffer-or-name @@ -2065,7 +2316,7 @@ the keymap. Since @code{define-key} puts new bindings at the front, you should define the menu items starting at the bottom of the menu and moving to the top, if you care about the order. When you add an item to an existing menu, you can specify its position in the menu using -@code{define-key-after} (@pxref{Modifying Menus}). +@code{keymap-set-after} (@pxref{Modifying Menus}). @menu * Simple Menu Items:: A simple kind of menu key binding. @@ -2228,6 +2479,12 @@ This property specifies that @var{string} is the string to display as the keyboard equivalent for this menu item. You can use the @samp{\\[...]} documentation construct in @var{string}. +This property can also be a function (which will be called with no +arguments). This function should return a string. This function will +be called every time the menu is computed, so using a function that +takes a lot of time to compute is not a good idea, and it should +expect to be called from any context. + @item :filter @var{filter-fn} This property provides a way to compute the menu item dynamically. The property value @var{filter-fn} should be a function of one argument; @@ -2654,6 +2911,10 @@ The @code{:rtl} property specifies an alternative image to use for right-to-left languages. Only the GTK+ version of Emacs supports this at present. +Some toolkits display both an image and a text in the toolbar. If you +want to force using only the image, use a @code{:vert-only} +non-@code{nil} property. + Like the menu bar, the tool bar can display separators (@pxref{Menu Separators}). Tool bar separators are vertical rather than horizontal, though, and only a single style is supported. They are @@ -2676,9 +2937,9 @@ using an indirection through @code{tool-bar-map}. By default, the global map binds @code{[tool-bar]} as follows: @example -(global-set-key [tool-bar] - `(menu-item ,(purecopy "tool bar") ignore - :filter tool-bar-make-keymap)) +(keymap-global-set "<tool-bar>" + `(menu-item ,(purecopy "tool bar") ignore + :filter tool-bar-make-keymap)) @end example @noindent @@ -2813,9 +3074,9 @@ To force recalculation of the tool bar, call When you insert a new item in an existing menu, you probably want to put it in a particular place among the menu's existing items. If you use @code{define-key} to add the item, it normally goes at the front of -the menu. To put it elsewhere in the menu, use @code{define-key-after}: +the menu. To put it elsewhere in the menu, use @code{keymap-set-after}: -@defun define-key-after map key binding &optional after +@defun keymap-set-after map key binding &optional after Define a binding in @var{map} for @var{key}, with value @var{binding}, just like @code{define-key}, but position the binding in @var{map} after the binding for the event @var{after}. The argument @var{key} should be @@ -2829,7 +3090,7 @@ inherited keymap. Here is an example: @example -(define-key-after my-menu [drink] +(keymap-set-after my-menu "<drink>" '("Drink" . drink-command) 'eat) @end example @@ -2841,7 +3102,7 @@ Here is how to insert an item called @samp{Work} in the @samp{Signals} menu of Shell mode, after the item @code{break}: @example -(define-key-after shell-mode-map [menu-bar signals work] +(keymap-set-after shell-mode-map "<menu-bar> <signals> <work>" '("Work" . work-command) 'break) @end example @end defun diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 4a862ab0de2..5c5c615f85d 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -340,6 +340,44 @@ If @var{n} is zero, @code{nthcdr} returns all of @end example @end defun +@defun take n list +This function returns the @var{n} first elements of @var{list}. Essentially, +it returns the part of @var{list} that @code{nthcdr} skips. + +@code{take} returns @var{list} if shorter than @var{n} elements; +it returns @code{nil} if @var{n} is zero or negative. + +@example +@group +(take 3 '(a b c d)) + @result{} (a b c) +@end group +@group +(take 10 '(a b c d)) + @result{} (a b c d) +@end group +@group +(take 0 '(a b c d)) + @result{} nil +@end group +@end example +@end defun + +@defun ntake n list +This is a version of @code{take} that works by destructively modifying +the list structure of the argument. That makes it faster, but the +original value of @var{list} may be lost. + +@code{ntake} returns @var{list} unmodified if shorter than @var{n} +elements; it returns @code{nil} if @var{n} is zero or negative. +Otherwise, it returns @var{list} truncated to its first @var{n} +elements. + +This means that it is usually a good idea to use the return value and +not just rely on the truncation effect unless @var{n} is known to be +positive. +@end defun + @defun last list &optional n This function returns the last link of @var{list}. The @code{car} of this link is the list's last element. If @var{list} is null, @@ -1925,9 +1963,10 @@ and later discarded; this is not possible with a property list. The following functions can be used to manipulate property lists. They all compare property names using @code{eq}. -@defun plist-get plist property +@defun plist-get plist property &optional predicate This returns the value of the @var{property} property stored in the -property list @var{plist}. It accepts a malformed @var{plist} +property list @var{plist}. Comparisons are done with @var{predicate}, +and defaults to @code{eq}. It accepts a malformed @var{plist} argument. If @var{property} is not found in the @var{plist}, it returns @code{nil}. For example, @@ -1943,9 +1982,10 @@ returns @code{nil}. For example, @end example @end defun -@defun plist-put plist property value +@defun plist-put plist property value &optional predicate This stores @var{value} as the value of the @var{property} property in -the property list @var{plist}. It may modify @var{plist} destructively, +the property list @var{plist}. Comparisons are done with @var{predicate}, +and defaults to @code{eq}. It may modify @var{plist} destructively, or it may construct a new list structure without altering the old. The function returns the modified property list, so you can store that back in the place where you got @var{plist}. For example, @@ -1961,19 +2001,20 @@ in the place where you got @var{plist}. For example, @end defun @defun lax-plist-get plist property -Like @code{plist-get} except that it compares properties -using @code{equal} instead of @code{eq}. +This obsolete function is like @code{plist-get} except that it +compares properties using @code{equal} instead of @code{eq}. @end defun @defun lax-plist-put plist property value -Like @code{plist-put} except that it compares properties -using @code{equal} instead of @code{eq}. +This obsolete function is like @code{plist-put} except that it +compares properties using @code{equal} instead of @code{eq}. @end defun -@defun plist-member plist property +@defun plist-member plist property &optional predicate This returns non-@code{nil} if @var{plist} contains the given -@var{property}. Unlike @code{plist-get}, this allows you to distinguish -between a missing property and a property with the value @code{nil}. -The value is actually the tail of @var{plist} whose @code{car} is -@var{property}. +@var{property}. Comparisons are done with @var{predicate}, and +defaults to @code{eq}. Unlike @code{plist-get}, this allows you to +distinguish between a missing property and a property with the value +@code{nil}. The value is actually the tail of @var{plist} whose +@code{car} is @var{property}. @end defun diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 723b4dd20a6..4e4f12dc324 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -149,10 +149,9 @@ up the execution of uncompiled code. Sometimes, this macro expansion cannot be done, owing to a cyclic dependency. In the simplest example of this, the file you are loading refers to a macro defined in another file, and that file in turn requires the file you are -loading. This is generally harmless. Emacs prints a warning +loading. Emacs will issue an error about (@samp{Eager macro-expansion skipped due to cycle@dots{}}) -giving details of the problem, but it still loads the file, just -leaving the macro unexpanded for now. You may wish to restructure +giving details of the problem. You have to restructure your code so that this does not happen. Loading a compiled file does not cause macroexpansion, because this should already have happened during compilation. @xref{Compiling Macros}. @@ -291,29 +290,35 @@ a directory) or @code{nil} (which stands for the current working directory). @end defvar - When Emacs starts up, it sets up the value of @code{load-path} -in several steps. First, it initializes @code{load-path} using -default locations set when Emacs was compiled. Normally, this -is a directory something like + When Emacs starts up, it sets up the value of @code{load-path} in +several steps. First, it looks for the directory containing its own +Lisp files, using default locations set when Emacs was compiled. It +saves this directory in @code{lisp-directory}. Normally, this is a +directory where the @file{*.elc} files are installed, something like @example "/usr/local/share/emacs/@var{version}/lisp" @end example -(In this and the following examples, replace @file{/usr/local} with -the installation prefix appropriate for your Emacs.) -These directories contain the standard Lisp files that come with -Emacs. If Emacs cannot find them, it will not start correctly. +@noindent +where @var{version} is the Emacs version. (In this and the following +examples, replace @file{/usr/local} with the prefix appropriate for +your Emacs installation.) This directory and its subdirectories +contain the standard Lisp files that come with Emacs. If Emacs cannot +find its own Lisp files, it will not start correctly. If you run Emacs from the directory where it was built---that is, an -executable that has not been formally installed---Emacs instead -initializes @code{load-path} using the @file{lisp} -directory in the directory containing the sources from which it -was built. +executable that has not been installed yet---Emacs instead initializes +@code{lisp-directory} using the @file{lisp} subdirectory of the +directory containing the sources from which it was built. + +Emacs then initializes @code{load-path} with this @code{lisp-directory}. @c Though there should be no *.el files in builddir/lisp, so it's pointless. If you built Emacs in a separate directory from the -sources, it also adds the lisp directories from the build directory. -(In all cases, elements are represented as absolute file names.) +sources, it also adds the @file{lisp} subdirectory of the build directory. + +All of these directories are stored in the above two variables as +absolute file names. @cindex site-lisp directories Unless you start Emacs with the @option{--no-site-lisp} option, @@ -333,12 +338,12 @@ and @end example @noindent -The first one is for locally installed files for a specific Emacs -version; the second is for locally installed files meant for use -with all installed Emacs versions. (If Emacs is running uninstalled, -it also adds @file{site-lisp} directories from the source and build -directories, if they exist. Normally these directories do not contain -@file{site-lisp} directories.) +The first one is for locally installed files for the current Emacs +@var{version}; the second is for locally installed files meant for use +with any installed Emacs version. (If Emacs is running uninstalled, +it also adds @file{site-lisp} subdirectories from the source and build +directories, if they exist. However, normally the source and build +directories do not contain @file{site-lisp} subdirectories.) @cindex @env{EMACSLOADPATH} environment variable If the environment variable @env{EMACSLOADPATH} is set, it modifies @@ -360,9 +365,10 @@ export EMACSLOADPATH=/home/foo/.emacs.d/lisp: @end example An empty element in the value of the environment variable, whether -trailing (as in the above example), leading, or embedded, is replaced -by the default value of @code{load-path} as determined by the standard -initialization procedure. If there are no such empty elements, then +trailing (as in the above example, note the trailing @samp{:}), +leading, or embedded, is replaced by the default value of +@code{load-path} as determined by the standard initialization +procedure. If there are no such empty elements, then @env{EMACSLOADPATH} specifies the entire @code{load-path}. You must include either an empty element, or the explicit path to the directory containing the standard Lisp files, else Emacs will not function. @@ -391,11 +397,23 @@ add one or more directories to @code{load-path}. For example: (push "~/.emacs.d/lisp" load-path) @end example +@noindent +@xref{List Variables, push}, for the description of @code{push}. + Dumping Emacs uses a special value of @code{load-path}. If you use a @file{site-load.el} or @file{site-init.el} file to customize the dumped Emacs (@pxref{Building Emacs}), any changes to @code{load-path} that these files make will be lost after dumping. +@defvar lisp-directory +This variable holds a string naming the directory which holds +Emacs's own @file{*.el} and @file{*.elc} files. This is usually the +place where those files are located in the Emacs installation tree, +unless Emacs is run from its build directory in which case it points +to the @file{lisp} subdirectory in the source directory from which +Emacs was built. +@end defvar + @deffn Command locate-library library &optional nosuffix path interactive-call This command finds the precise file name for library @var{library}. It searches for the library in the same way @code{load} does, and the @@ -422,7 +440,7 @@ similarly-named file in a directory earlier on @code{load-path}. For instance, suppose @code{load-path} is set to @example - ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp") + ("/opt/emacs/site-lisp" "/usr/share/emacs/29.1/lisp") @end example @noindent @@ -482,7 +500,7 @@ automatically. However, if this does make a difference, you can force a particular Lisp file to be interpreted as unibyte by writing @samp{coding: raw-text} in a local variables section. With that designator, the file will unconditionally be interpreted as -unibyte. This can matter when making keybindings to +unibyte. This can matter when making key bindings to non-@acronym{ASCII} characters written as @code{?v@var{literal}}. @node Autoload @@ -510,7 +528,7 @@ primitive for autoloading; any Lisp program can call @code{autoload} at any time. Magic comments are the most convenient way to make a function autoload, for packages installed along with Emacs. These comments do nothing on their own, but they serve as a guide for the command -@code{update-file-autoloads}, which constructs calls to @code{autoload} +@code{loaddefs-generate}, which constructs calls to @code{autoload} and arranges to execute them when Emacs is built. @defun autoload function filename &optional docstring interactive type @@ -552,7 +570,7 @@ An autoloaded keymap loads automatically during key lookup when a prefix key's binding is the symbol @var{function}. Autoloading does not occur for other kinds of access to the keymap. In particular, it does not happen when a Lisp program gets the keymap from the value of a variable -and calls @code{define-key}; not even if the variable name is the same +and calls @code{keymap-set}; not even if the variable name is the same symbol @var{function}. @cindex function cell in autoload @@ -608,22 +626,19 @@ subroutines not loaded successfully because they come later in the file. macro, then an error is signaled with data @code{"Autoloading failed to define function @var{function-name}"}. -@findex update-file-autoloads -@findex make-directory-autoloads +@findex loaddefs-generate @cindex magic autoload comment @cindex autoload cookie @anchor{autoload cookie} A magic autoload comment (often called an @dfn{autoload cookie}) consists of @samp{;;;###autoload}, on a line by itself, just before the real definition of the function in its -autoloadable source file. The command @kbd{M-x update-file-autoloads} +autoloadable source file. The function @code{loaddefs-generate} writes a corresponding @code{autoload} call into @file{loaddefs.el}. (The string that serves as the autoload cookie and the name of the -file generated by @code{update-file-autoloads} can be changed from the +file generated by @code{loaddefs-generate} can be changed from the above defaults, see below.) Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}. -@kbd{M-x make-directory-autoloads} is even more powerful; it updates -autoloads for all files in the current directory. The same magic comment can copy any kind of form into @file{loaddefs.el}. The form following the magic comment is copied @@ -656,7 +671,7 @@ and @code{define-global-minor-mode}. @emph{without} executing it when the file itself is loaded. To do this, write the form @emph{on the same line} as the magic comment. Since it is in a comment, it does nothing when you load the source file; but -@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where +@code{loaddefs-generate} copies it to @file{loaddefs.el}, where it is executed while building Emacs. The following example shows how @code{doctor} is prepared for @@ -683,14 +698,13 @@ Switch to *doctor* buffer and start giving psychotherapy. @noindent @cindex @code{fn} in function's documentation string -The backslash and newline immediately following the double-quote are a -convention used only in the preloaded uncompiled Lisp files such as -@file{loaddefs.el}; they tell @code{make-docfile} to put the -documentation string in the @file{etc/DOC} file. @xref{Building Emacs}. -See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)} -in the usage part of the documentation string is replaced with the -function's name when the various help functions (@pxref{Help -Functions}) display it. +While the @file{loaddefs.el} isn't for editing, we try to keep it +somewhat readable for people. For instance, control characters in +@code{defvar} values are escaped, and we insert a backslash and +newline immediately following the double-quote of the doc string to +keep the line length down. @samp{(fn)} in the usage part of the +documentation string is replaced with the function's name when the +various help functions (@pxref{Help Functions}) display it. If you write a function definition with an unusual macro that is not one of the known and recognized function definition methods, use of an @@ -709,11 +723,11 @@ corresponding autoload calls written into a file whose name is different from the default @file{loaddefs.el}. Emacs provides two variables to control this: -@defvar generate-autoload-cookie -The value of this variable should be a string whose syntax is a Lisp -comment. @kbd{M-x update-file-autoloads} copies the Lisp form that -follows the cookie into the autoload file it generates. The default -value of this variable is @code{";;;###autoload"}. +@defvar lisp-mode-autoload-regexp +The value of this constant is a regexp that matches autoload cookies. +@code{loaddefs-generate} copies the Lisp form that follows the +cookie into the autoload file it generates. This will match comments +like @samp{;;;###autoload} and @samp{;;;###calc-autoload}. @end defvar @defvar generated-autoload-file @@ -750,7 +764,7 @@ contain definitions matching the prefix being completed. The variable @code{definition-prefixes} holds a hashtable which maps a prefix to the corresponding list of files to load for it. Entries to this mapping are added by calls to @code{register-definition-prefixes} -which are generated by @code{update-file-autoloads} +which are generated by @code{loaddefs-generate} (@pxref{Autoload}). Files which don't contain any definitions worth loading (test files, for example), should set @code{autoload-compute-prefixes} to @code{nil} as a file-local @@ -1017,7 +1031,7 @@ with a call to @code{provide}. The order of the elements in the @cindex symbol, where defined @cindex where was a symbol defined -@defun symbol-file symbol &optional type +@defun symbol-file symbol &optional type native-p This function returns the name of the file that defined @var{symbol}. If @var{type} is @code{nil}, then any kind of definition is acceptable. If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that @@ -1028,6 +1042,14 @@ The value is normally an absolute file name. It can also be @code{nil}, if the definition is not associated with any file. If @var{symbol} specifies an autoloaded function, the value can be a relative file name without extension. + +If the optional third argument @var{native-p} is non-@code{nil}, and +Emacs was built with native compilation support (@pxref{Native +Compilation}), this function will try to find the @file{.eln} file +that defined @var{symbol}, instead of the @file{.elc} or @file{.el} +file. If such a @file{.eln} file is found and is not outdated, the +function will return its absolute file name; otherwise it will report +the name of either the source or the byte-compiled file. @end defun The basis for @code{symbol-file} is the data in the variable @@ -1048,13 +1070,8 @@ list elements have these forms: The symbol @var{var} was defined as a variable. @item (defun . @var{fun}) The function @var{fun} was defined. -@item (t . @var{fun}) -The function @var{fun} was previously an autoload before this library -redefined it as a function. The following element is always @code{(defun . @var{fun})}, which represents defining @var{fun} as a function. -@item (autoload . @var{fun}) -The function @var{fun} was defined as an autoload. @item (defface . @var{face}) The face @var{face} was defined. @item (require . @var{feature}) @@ -1077,6 +1094,23 @@ The value of @code{load-history} may have one element whose @sc{car} is by adding the symbols defined to the element for the file being visited, rather than replacing that element. @xref{Eval}. +@kindex function-history @r{(function symbol property)} +In addition to @code{load-history}, every function keeps track of its +own history in the symbol property @code{function-history}. +The reason why functions are treated specially in this respect is that +it is common for functions to be defined in two steps in two different +files (typically, one of them is an autoload), so in order to be +able to properly @emph{unload} a file, we need to know more precisely +what that file did to the function definition. + +The symbol property @code{function-history} holds a list of the form +@w{@code{(@var{file1} @var{def2} @var{file2} @var{def3} ...)}}, where +@var{file1} is the last file that changed the definition and +@var{def2} was the definition before @var{file1}, set by @var{file2}, +etc. Logically this list should end with the name of the first file +that defined this function, but to save space this last element +is usually omitted. + @node Unloading @section Unloading @cindex unloading packages @@ -1091,7 +1125,7 @@ It undefines all functions, macros, and variables defined in that library with @code{defun}, @code{defalias}, @code{defsubst}, @code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}. It then restores any autoloads formerly associated with those symbols. -(Loading saves these in the @code{autoload} property of the symbol.) +(Loading saves these in the @code{function-history} property of the symbol.) Before restoring the previous definitions, @code{unload-feature} runs @code{remove-hook} to remove functions defined by the library from certain @@ -1156,7 +1190,7 @@ You don't need to give a directory or extension in the file name @var{library}. Normally, you just give a bare file name, like this: @example -(with-eval-after-load "js" (define-key js-mode-map "\C-c\C-c" 'js-eval)) +(with-eval-after-load "js" (keymap-set js-mode-map "C-c C-c" 'js-eval)) @end example To restrict which files can trigger the evaluation, include a diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index bc2f14883cb..089ae41f32e 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -244,6 +244,13 @@ This function works by calling the value)) @end group @end smallexample + +@findex read-string-from-buffer +If you have a long string (for instance, one that is several lines +long) that you wish to edit, using @code{read-string} may not be +ideal. In that case, popping to a new, normal buffer where the user +can edit the string may be more convenient, and you can use the +@code{read-string-from-buffer} function to do that. @end defun @defun read-regexp prompt &optional defaults history @@ -302,6 +309,22 @@ The optional argument @var{history}, if non-@code{nil}, is a symbol specifying a minibuffer history list to use (@pxref{Minibuffer History}). If it is omitted or @code{nil}, the history list defaults to @code{regexp-history}. + +@cindex @code{case-fold}, text property +@findex read-regexp-case-fold-search +The user can use the @kbd{M-c} command to indicate whether case +folding should be on or off. If the user has used this command, the +returned string will have the text property @code{case-fold} set to +either @code{fold} or @code{inhibit-fold}. It is up to the caller of +@code{read-regexp} to actually use this value, and the convenience +function @code{read-regexp-case-fold-search} is provided for that. A +typical usage pattern here might look like: + +@lisp +(let* ((regexp (read-regexp "Search for: ")) + (case-fold-search (read-regexp-case-fold-search regexp))) + (re-search-forward regexp)) +@end lisp @end defun @defopt read-regexp-defaults-function @@ -467,6 +490,9 @@ If @var{default} is @code{nil}, there is no default value, and therefore no ``default value'' string is included in the result value. If @var{default} is a non-@code{nil} list, the first element of the list is used in the prompt. + +Both @var{prompt} and @code{minibuffer-default-prompt-format} are run +through @code{substitute-command-keys} (@pxref{Keys in Documentation}). @end defun @defvar read-minibuffer-restore-windows @@ -1115,6 +1141,11 @@ completion command (i.e., one of the commands in not an element of @var{collection}. @xref{Completion Commands}. @item +If a function, it is called with the input as the only argument. The +function should return a non-@code{nil} value if the input is +acceptable. + +@item Any other value of @var{require-match} behaves like @code{t}, except that the exit commands won't exit if it performs completion. @end itemize diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index cb748606ed9..75eb21522f1 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -269,6 +269,18 @@ normal-mode}), but tries to force it not to choose any modes in @var{avoided-modes}, if that argument is non-@code{nil}. @end defun +@defun clean-mode +Changing the major mode clears out most local variables, but it +doesn't remove all artifacts in the buffer (like text properties and +overlays). It's rare to change a buffer from one major mode to +another (except from @code{fundamental-mode} to everything else), so +this is usually not a concern. It can sometimes be convenient (mostly +when debugging a problem in a buffer) to do a ``full reset'' of the +buffer, and that's what the @code{clean-mode} major mode offers. It +will kill all local variables (even the permanently local ones), and +also removes all overlays and text properties. +@end defun + The easiest way to write a major mode is to use the macro @code{define-derived-mode}, which sets up the new mode as a variant of an existing major mode. @xref{Derived Modes}. We recommend using @@ -907,10 +919,8 @@ which in turn may have been changed in a mode hook. Here is a hypothetical example: @example -(defvar hypertext-mode-map - (let ((map (make-sparse-keymap))) - (define-key map [down-mouse-3] 'do-hyper-link) - map)) +(defvar-keymap hypertext-mode-map + "<down-mouse-3>" #'do-hyper-link) (define-derived-mode hypertext-mode text-mode "Hypertext" @@ -1051,12 +1061,22 @@ very end of every properly-written major mode command. @cindex Tabulated List mode Tabulated List mode is a major mode for displaying tabulated data, -i.e., data consisting of @dfn{entries}, each entry occupying one row of -text with its contents divided into columns. Tabulated List mode +i.e., data consisting of @dfn{entries}, each entry occupying one row +of text with its contents divided into columns. Tabulated List mode provides facilities for pretty-printing rows and columns, and sorting the rows according to the values in each column. It is derived from Special mode (@pxref{Basic Major Modes}). +@findex make-vtable +@cindex variable pitch tables + Tabulated List mode is geared towards displaying text using +monospaced fonts, using a single font and text size. If you want to +display a table using variable pitch fonts or images, +@code{make-vtable} can be used instead. vtable also support having +more than a single table in a buffer, or having a buffer that contains +both a table and additional text in it. @xref{Introduction,,, vtable}, +for more information. + Tabulated List mode is intended to be used as a parent mode by a more specialized major mode. Examples include Process Menu mode (@pxref{Process Information}) and Package Menu mode (@pxref{Package @@ -1141,10 +1161,11 @@ re-sorting entries. Comparison is done with @code{equal}. @item @var{contents} is a vector with the same number of elements as @code{tabulated-list-format}. Each vector element is either a string, -which is inserted into the buffer as-is, or a list @code{(@var{label} -. @var{properties})}, which means to insert a text button by calling -@code{insert-text-button} with @var{label} and @var{properties} as -arguments (@pxref{Making Buttons}). +which is inserted into the buffer as-is; an image descriptor, which is +used to insert an image (@pxref{Image Descriptors}); or a list +@w{@code{(@var{label} . @var{properties})}}, which means to insert a +text button by calling @code{insert-text-button} with @var{label} and +@var{properties} as arguments (@pxref{Making Buttons}). There should be no newlines in any of these strings. @end itemize @@ -1334,14 +1355,11 @@ the conventions listed above: ;; @r{Create the keymap for this mode.} @group -(defvar text-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\e\t" 'ispell-complete-word) - @dots{} - map) - "Keymap for `text-mode'. -Many other modes, such as `mail-mode', `outline-mode' and -`indented-text-mode', inherit all the commands defined in this map.") +(defvar-keymap text-mode-map + :doc "Keymap for `text-mode'. +Many other modes, such as `mail-mode' and `outline-mode', inherit all +the commands defined in this map." + "C-M-i" #'ispell-complete-word) @end group @end smallexample @@ -1411,13 +1429,11 @@ common. The following code sets up the common commands: @smallexample @group -(defvar lisp-mode-shared-map - (let ((map (make-sparse-keymap))) - (set-keymap-parent map prog-mode-map) - (define-key map "\e\C-q" 'indent-sexp) - (define-key map "\177" 'backward-delete-char-untabify) - map) - "Keymap for commands shared by all sorts of Lisp modes.") +(defvar-keymap lisp-mode-shared-map + :parent prog-mode-map + :doc "Keymap for commands shared by all sorts of Lisp modes." + "C-M-q" #'indent-sexp + "DEL" #'backward-delete-char-untabify) @end group @end smallexample @@ -1426,16 +1442,12 @@ And here is the code to set up the keymap for Lisp mode: @smallexample @group -(defvar lisp-mode-map - (let ((map (make-sparse-keymap)) - (menu-map (make-sparse-keymap "Lisp"))) - (set-keymap-parent map lisp-mode-shared-map) - (define-key map "\e\C-x" 'lisp-eval-defun) - (define-key map "\C-c\C-z" 'run-lisp) - @dots{} - map) - "Keymap for ordinary Lisp mode. -All commands in `lisp-mode-shared-map' are inherited by this map.") +(defvar-keymap lisp-mode-map + :doc "Keymap for ordinary Lisp mode. +All commands in `lisp-mode-shared-map' are inherited by this map." + :parent lisp-mode-shared-map + "C-M-x" #'lisp-eval-defun + "C-c C-z" #'run-lisp) @end group @end smallexample @@ -1899,6 +1911,16 @@ This means ``use in modes derived from @code{text-mode}, but nowhere else''. (There's an implicit @code{nil} element at the end.) @end defmac +@findex buffer-local-restore-state +@defmac buffer-local-set-state variable value... +Minor modes often set buffer-local variables that affect some features +in Emacs. When a minor mode is switched off, the mode is expected to +restore the previous state of these variables. This convenience macro +helps with doing that: It works much like @code{setq-local}, but +returns an object that can be used to restore these values back to +their previous values/states (using the companion function +@code{buffer-local-restore-state}). +@end defmac @node Mode Line Format @section Mode Line Format @@ -1961,8 +1983,26 @@ This function also forces an update of the menu bar and frame title. @end defun The selected window's mode line is usually displayed in a different -color using the face @code{mode-line}. Other windows' mode lines appear -in the face @code{mode-line-inactive} instead. @xref{Faces}. +color using the face @code{mode-line-active}. Other windows' mode +lines appear in the face @code{mode-line-inactive} instead. +@xref{Faces}. + +@defun mode-line-window-selected-p +If you want to have more extensive differences between the mode lines +in selected and non-selected windows, you can use this predicate in an +@code{:eval} construct. For instance, if you want to display the +buffer name in bold in selected windows, but in italics in the other +windows, you can say something like: + +@lisp +(setq-default + mode-line-buffer-identification + '(:eval (propertize "%12b" + 'face (if (mode-line-window-selected-p) + 'bold + 'italic)))) +@end lisp +@end defun @vindex mode-line-compact Some modes put a lot of data in the mode line, pushing elements at @@ -2534,7 +2574,23 @@ mode line feature, except that it's controlled by This variable, local in every buffer, specifies how to display the header line, for windows displaying the buffer. The format of the value is the same as for @code{mode-line-format} (@pxref{Mode Line Data}). -It is normally @code{nil}, so that ordinary buffers have no header line. +It is normally @code{nil}, so that ordinary buffers have no header +line. + +@findex header-line-indent-mode +If @code{display-line-numbers-mode} is used, and you want the header +line to be indented by the same amount as the buffer contents, you can +use the @code{header-line-indent-mode} minor mode. This minor mode +keeps the @code{header-line-indent} variable updated, so that you can +say something like: + +@lisp +(setq header-line-format + `("" header-line-format ,my-header-line)) +@end lisp + +This can be useful if you're displaying columnar data, and the header +line should align with that data in the buffer. @end defvar @defun window-header-line-height &optional window @@ -3173,7 +3229,9 @@ Non-@code{nil} means that regular expression matching for the sake of You can use @code{font-lock-add-keywords} to add additional search-based fontification rules to a major mode, and -@code{font-lock-remove-keywords} to remove rules. +@code{font-lock-remove-keywords} to remove rules. You can also +customize the @code{font-lock-ignore} option to selectively disable +fontification rules for keywords that match certain criteria. @defun font-lock-add-keywords mode keywords &optional how This function adds highlighting @var{keywords}, for the current buffer @@ -3243,6 +3301,99 @@ mode @emph{and} all modes derived from it, do this instead: font-lock-keyword-face))))) @end smallexample +@defopt font-lock-ignore +@cindex selectively disabling font-lock fontifications +This option defines conditions for selectively disabling +fontifications due to certain Font Lock keywords. If non-@code{nil}, +its value is a list of elements of the following form: + +@example +(@var{symbol} @var{condition} @dots{}) +@end example + +Here, @var{symbol} is a symbol, usually a major or minor mode. The +subsequent @var{condition}s of a @var{symbol}'s list element will be in +effect if @var{symbol} is bound and its value is non-@code{nil}. For +a mode's symbol, it means that the current major mode is derived from +that mode, or that minor mode is enabled in the buffer. When a +@var{condition} is in effect, any fontifications caused by +@code{font-lock-keywords} elements that match the @var{condition} will +be disabled. + +Each @var{condition} can be one of the following: + +@table @asis +@item a symbol +This condition matches any element of Font Lock keywords that +references the symbol. This is usually a face, but can be any symbol +referenced by an element of the @code{font-lock-keywords} list. The +symbol can contain wildcards: @code{*} matches any string in the +symbol'ss name, @code{?} matches a single character, and +@code{[@var{char-set}]}, where @var{char-set} is a string of one or +more characters, matches a single character from the set. + +@item a string +This condition matches any element of Font Lock keywords whose +@var{matcher} is a regexp which matches the string. In other words, +this condition matches a Font Lock rule which highlights the string. +Thus, the string could be a specific program keyword whose +highlighting you want to disable. + +@item @code{(pred @var{function})} +This condition matches any element of Font Lock keywords for which +@var{function}, when called with the element as the argument, returns +non-@code{nil}. + +@item @code{(not @var{condition})} +This matches if @var{condition} doesn’t. + +@item @code{(and @var{condition} @dots{})} +This matches if each of the @var{condition}s matches. + +@item @code{(or @var{condition} @dots{})} +This matches if at least one of the @var{condition}s matches. + +@item @code{(except @var{condition})} +This condition can only be used at top level or inside an +@code{or} clause. It undoes the effect of a previously matching +condition on the same level. +@end table +@end defopt + +As an example, consider the following setting: + +@smallexample +(setq font-lock-ignore + '((prog-mode font-lock-*-face + (except help-echo)) + (emacs-lisp-mode (except ";;;###autoload)") + (whitespace-mode whitespace-empty-at-bob-regexp) + (makefile-mode (except *)))) +@end smallexample + +Line by line, this does the following: + +@enumerate +@item +In all programming modes, disable fontifications due to all font-lock +keywords that apply one of the standard font-lock faces (excluding +strings and comments, which are covered by syntactic Font Lock). + +@item +However, keep any keywords that add a @code{help-echo} text property. + +@item +In Emacs Lisp mode, also keep the highlighting of autoload cookies, +which would have been excluded by the first condition. + +@item +When @code{whitespace-mode} (a minor mode) is enabled, also don't +highlight an empty line at beginning of buffer. + +@item +Finally, in Makefile mode, don't apply any conditions. +@end enumerate + @node Other Font Lock Variables @subsection Other Font Lock Variables @@ -3527,6 +3678,10 @@ the value is @code{nil}, Font Lock will call @code{jit-lock-register} (@pxref{Other Font Lock Variables}) to set up for automatic refontification of buffer text following a modified line to reflect the new syntactic context due to the change. + +To use only syntactic fontification, this variable should +be non-@code{nil}, while @code{font-lock-keywords} should be set to +@code{nil} (@pxref{Font Lock Basics}). @end defvar @defvar font-lock-syntax-table diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index 6dc23637a79..71fee45c4a5 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -404,9 +404,12 @@ This returns @code{t} if @var{charcode} is a valid character, and @cindex maximum value of character codepoint @cindex codepoint, largest value -@defun max-char +@defun max-char &optional unicode This function returns the largest value that a valid character -codepoint can have. +codepoint can have in Emacs. If the optional argument @var{unicode} +is non-@code{nil}, it returns the largest character codepoint defined +by the Unicode Standard (which is smaller than the maximum codepoint +supported by Emacs). @example @group diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index a715b45a6c2..7b5e9adee29 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -1541,6 +1541,7 @@ editing. * Keymap Type:: What function a keystroke invokes. * Overlay Type:: How an overlay is represented. * Font Type:: Fonts for displaying text. +* Xwidget Type:: Embeddable widgets. @end menu @node Buffer Type @@ -1866,6 +1867,20 @@ syntax looks like @samp{#<font-object>}, @samp{#<font-spec>}, and @samp{#<font-entity>} respectively. @xref{Low-Level Font}, for a description of these Lisp objects. +@node Xwidget Type +@subsection Xwidget Type +@cindex xwidget type +@cindex xwidget-view type + + An @dfn{xwidget} is a special display element, such as a web +browser, that can be embedded inside a buffer. Each window that +displays an xwidget will also have an @dfn{xwidget view}, which on +X-Windows corresponds to a single X window used to display the widget. + +Neither of these objects are readable; their print syntaxes look like +@samp{#<xwidget>} and @samp{#<xwidget-view>}, respectively. +@xref{Xwidgets}, for a more detailed description of xwidgets. + @node Circular Objects @section Read Syntax for Circular Objects @cindex circular structure, read syntax @@ -2007,6 +2022,9 @@ with references to further information. @item byte-code-function-p @xref{Byte-Code Type, byte-code-function-p}. +@item compiled-function-p +@xref{Byte-Code Type, compiled-function-p}. + @item case-table-p @xref{Case Tables, case-table-p}. diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index e7ce40b1f25..3e16ac0eb49 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -329,10 +329,10 @@ file will not inhibit the message for someone else. @end defopt @defopt initial-scratch-message -This variable, if non-@code{nil}, should be a string, which is -treated as documentation to be -inserted into the @file{*scratch*} buffer when Emacs starts up. If it -is @code{nil}, the @file{*scratch*} buffer is empty. +This variable, if non-@code{nil}, should be a string, which is treated +as documentation to be inserted into the @file{*scratch*} buffer when +Emacs starts up or when that buffer is recreated. If it is +@code{nil}, the @file{*scratch*} buffer is empty. @end defopt @noindent @@ -363,6 +363,9 @@ Do not load the @file{site-start} library. @itemx -Q Equivalent to @samp{-q --no-site-file --no-splash}. @c and --no-site-lisp, but let's not mention that here. + +@item --init-directory +Specify the directory to use when finding the Emacs init files. @end table @@ -696,7 +699,7 @@ If you started Emacs from a terminal, the parent process normally resumes control. The low-level primitive for killing Emacs is @code{kill-emacs}. -@deffn Command kill-emacs &optional exit-data +@deffn Command kill-emacs &optional exit-data restart This command calls the hook @code{kill-emacs-hook}, then exits the Emacs process and kills it. @@ -711,6 +714,10 @@ input) can read them. If @var{exit-data} is neither an integer nor a string, or is omitted, that means to use the (system-specific) exit status which indicates successful program termination. + +If @var{restart} is non-@code{nil}, instead of just exiting at the +end, start a new Emacs process, using the same command line arguments +as the currently running Emacs process. @end deffn @cindex SIGTERM @@ -753,6 +760,13 @@ the remaining functions in this hook. Calling @code{kill-emacs} directly does not run this hook. @end defopt +@deffn Command restart-emacs +This command does the same as @code{save-buffers-kill-emacs}, but +instead of just killing the current Emacs process at the end, it'll +restart a new Emacs process, using the same command line arguments as +the currently running Emacs process. +@end deffn + @node Suspending Emacs @subsection Suspending Emacs @cindex suspending Emacs @@ -947,6 +961,9 @@ actually Linux is just the kernel, not the whole system.) @item gnu/kfreebsd A GNU (glibc-based) system with a FreeBSD kernel. +@item haiku +The Haiku operating system, a derivative of the Be Operating System. + @item hpux Hewlett-Packard HPUX operating system. @@ -1297,10 +1314,16 @@ zone. @cindex Lisp timestamp @cindex timestamp, Lisp +@cindex Coordinated Universal Time +@cindex Universal Time +@cindex UTC +@cindex leap seconds Many functions like @code{current-time} and @code{file-attributes} return @dfn{Lisp timestamp} values that count seconds, and that can represent absolute time by counting seconds since the @dfn{epoch} of -1970-01-01 00:00:00 UTC. +1970-01-01 00:00:00 UTC (Coordinated Universal Time). Typically these +counts ignore leap seconds; however, GNU and some other operating +systems can be configured to count leap seconds. Although traditionally Lisp timestamps were integer pairs, their form has evolved and programs ordinarily should not depend on the @@ -1322,11 +1345,7 @@ A pair of integers @code{(@var{ticks} . @var{hz})}, where @var{hz} is positive. This represents @var{ticks}/@var{hz} seconds, which is the same time as plain @var{ticks} if @var{hz} is 1. A common value for @var{hz} is 1000000000, for a nanosecond-resolution -clock.@footnote{Currently @var{hz} should be at least 65536 to avoid -compatibility warnings when the timestamp is passed to standard -functions, as previous versions of Emacs would interpret such a -timestamps differently due to backward-compatibility concerns. These -warnings are intended to be removed in a future Emacs version.} +clock. @item A list of four integers @code{(@var{high} @var{low} @var{micro} @@ -1340,7 +1359,8 @@ This represents the number of seconds using the formula: @tex $high \times 2^{16} + low + micro \times 10^{-6} + pico \times 10^{-12}$. @end tex -In some cases, functions may default to returning two- or +If @code{current-time-list} is @code{t}, +some functions may default to returning two- or three-element lists, with omitted @var{micro} and @var{pico} components defaulting to zero. On all current machines @var{pico} is a multiple of 1000, but this @@ -1349,9 +1369,9 @@ may change as higher-resolution clocks become available. @cindex time value Function arguments, e.g., the @var{time} argument to -@code{current-time-string}, accept a more-general @dfn{time value} +@code{format-time-string}, accept a more-general @dfn{time value} format, which can be a Lisp timestamp, @code{nil} for the current -time, a single floating-point number for seconds, or a list +time, a finite floating-point number for seconds, or a list @code{(@var{high} @var{low} @var{micro})} or @code{(@var{high} @var{low})} that is a truncated list timestamp with missing elements taken to be zero. @@ -1361,8 +1381,8 @@ Time values can be converted to and from calendrical and other forms. Some of these conversions rely on operating system functions that limit the range of possible time values, and signal an error such as @samp{"Specified time is not representable"} if the -limits are exceeded. For instance, a system may not support years -before 1970, or years before 1901, or years far in the future. +limits are exceeded. For instance, a system might not support +timestamps before the epoch, or years far in the future. You can convert a time value into a human-readable string using @code{format-time-string}, into a Lisp timestamp using @code{time-convert}, and into other forms using @@ -1394,13 +1414,28 @@ The operating system limits the range of time and zone values. @end example @end defun +@defvar current-time-list +This boolean variable is a transition aid. If @code{t}, +@code{current-time} and related functions return timestamps in list +form, typically @code{(@var{high} @var{low} @var{micro} @var{pico})}; +otherwise, they use @code{(@var{ticks} . @var{hz})} form. Currently +this variable defaults to @code{t}, for behavior compatible with +previous Emacs versions. Developers are encouraged to test +timestamp-related code with this variable set to @code{nil}, as it +will default to @code{nil} in a future Emacs version, and will be +removed in some version after that. +@end defvar + @defun current-time This function returns the current time as a Lisp timestamp. -Although the timestamp takes the form @code{(@var{high} @var{low} -@var{micro} @var{pico})} in the current Emacs release, this is -planned to change in a future Emacs version. You can use the -@code{time-convert} function to convert a timestamp to some other -form. @xref{Time Conversion}. +If @code{current-time-list} is @code{nil}, +the timestamp has the form @code{(@var{ticks} . @var{hz})} where +@var{ticks} counts clock ticks and @var{hz} is the clock ticks per second. +Otherwise, the timestamp has the list form +@code{(@var{high} @var{low} @var{usec} @var{psec})}. +You can use @code{(time-convert nil t)} or @code{(time-convert nil 'list)} +to obtain a particular form regardless of the value of +@code{current-time-list}. @xref{Time Conversion}. @end defun @defun float-time &optional time @@ -1416,6 +1451,13 @@ as @samp{0.1} but is slightly greater than 1/10. @code{time-to-seconds} is an alias for this function. @end defun +@defun current-cpu-time +Return the current @acronym{CPU} time along with its resolution. The +return value is a pair @code{(CPU-TICKS . TICKS-PER-SEC)}. The +@var{CPU-TICKS} counter can wrap around, so values cannot be +meaningfully compared if too much time has passed between them. +@end defun + @node Time Zone Rules @section Time Zone Rules @cindex time zone rules @@ -1428,11 +1470,11 @@ to default to Universal Time with @code{(setenv "TZ" "UTC0")}. If which is a platform-dependent default time zone. The set of supported @env{TZ} strings is system-dependent. GNU and -many other systems support the tzdata database, e.g., +many other systems support TZDB timezones, e.g., @samp{"America/New_York"} specifies the time zone and daylight saving time history for locations near New York City. GNU and most other systems support POSIX-style @env{TZ} strings, e.g., -@samp{"EST+5EDT,M4.1.0/2,M10.5.0/2"} specifies the rules used in New +@samp{"EST5EDT,M4.1.0,M10.5.0"} specifies the rules used in New York from 1987 through 2006. All systems support the string @samp{"UTC0"} meaning Universal Time. @@ -1484,46 +1526,45 @@ The operating system limits the range of time and zone values. These functions convert time values (@pxref{Time of Day}) to Lisp timestamps, or into calendrical information and vice versa. - Many 32-bit operating systems are limited to system times containing -32 bits of information in their seconds component; these systems -typically handle only the times from 1901-12-13 20:45:52 through -2038-01-19 03:14:07 Universal Time. However, 64-bit and some 32-bit operating -systems have larger seconds components, and can represent times far in -the past or future. - - Calendrical conversion functions always use the Gregorian calendar, even -for dates before the Gregorian calendar was introduced. Year numbers -count the number of years since the year 1 BC, and do not skip zero + Many operating systems use 64-bit signed integers to count seconds, +and can represent times far in the past or future. However, some are +more limited. For example, old-fashioned operating systems that use +32-bit signed integers typically handle only times from 1901-12-13 +20:45:52 through 2038-01-19 03:14:07 Universal Time. + + Calendrical conversion functions use the Gregorian calendar even for +dates before the Gregorian calendar was introduced, and for dates in +the far distant past or future for which the Gregorian calendar +is wildly inaccurate and disagrees with common practice in scientific fields +like astronomy and paleontology, which use Julian-calendar year lengths. +Year numbers count since the year 1 BCE, and do not skip zero as traditional Gregorian years do; for example, the year number -@minus{}37 represents the Gregorian year 38 BC@. +@minus{}37 represents the Gregorian year 38 BCE@. -@defun time-convert time &optional form +@defun time-convert time form This function converts a time value into a Lisp timestamp. -The optional @var{form} argument specifies the timestamp form to be -returned. If @var{form} is the symbol @code{integer}, this function -returns an integer count of seconds. If @var{form} is a positive -integer, it specifies a clock frequency and this function returns an -integer-pair timestamp @code{(@var{ticks} -. @var{form})}.@footnote{Currently a positive integer @var{form} -should be at least 65536 if the returned value is intended to be given -to standard functions expecting Lisp timestamps.} If @var{form} is +The @var{form} argument specifies the timestamp form to be returned. +If @var{form} is the symbol @code{integer}, this function returns an +integer count of seconds. If @var{form} is a positive integer, it +specifies a clock frequency and this function returns an integer-pair +timestamp @code{(@var{ticks} . @var{form})}. If @var{form} is @code{t}, this function treats it as a positive integer suitable for representing the timestamp; for example, it is treated as 1000000000 -if @var{time} is nil and the platform timestamp has nanosecond +if @var{time} is @code{nil} and the platform timestamp has nanosecond resolution. If @var{form} is @code{list}, this function returns an integer list @code{(@var{high} @var{low} @var{micro} @var{pico})}. -Although an omitted or @code{nil} @var{form} currently acts like +Although a @code{nil} @var{form} currently acts like @code{list}, this is planned to change in a future Emacs version, so callers requiring list timestamps should pass @code{list} explicitly. -If @var{time} is infinite or a NaN, this function signals an error. +If @var{time} is not a time value, this function signals an error. Otherwise, if @var{time} cannot be represented exactly, conversion truncates it toward minus infinity. When @var{form} is @code{t}, conversion is always exact so no truncation occurs, and the returned clock resolution is no less than that of @var{time}. By way of -contrast, @code{float-time} can convert any Lisp time value without -signaling an error, although the result might not be exact. +contrast, although @code{float-time} can also convert any time value +without signaling an error, the result might not be exact. @xref{Time of Day}. For efficiency this function might return a value that is @code{eq} to @@ -1608,62 +1649,15 @@ this default may change in future Emacs releases, so callers requiring a particular form should specify @var{form}. @strong{Common Lisp Note:} Common Lisp has different meanings for -@var{dow} and @var{utcoff}, and its @var{second} is an integer between -0 and 59 inclusive. +@var{dow}, @code{dst} and @var{utcoff}, and its @var{second} is an +integer between 0 and 59 inclusive. -To access (or alter) the elements in the time value, the +To access (or alter) the elements in the calendrical information, the @code{decoded-time-second}, @code{decoded-time-minute}, @code{decoded-time-hour}, @code{decoded-time-day}, @code{decoded-time-month}, @code{decoded-time-year}, @code{decoded-time-weekday}, @code{decoded-time-dst} and @code{decoded-time-zone} accessors can be used. - -For instance, to increase the year in a decoded time, you could say: - -@lisp -(setf (decoded-time-year decoded-time) - (+ (decoded-time-year decoded-time) 4)) -@end lisp - -Also see the following function. - -@end defun - -@defun decoded-time-add time delta -This function takes a decoded time structure and adds @var{delta} -(also a decoded time structure) to it. Elements in @var{delta} that -are @code{nil} are ignored. - -For instance, if you want ``same time next month'', you -could say: - -@lisp -(let ((time (decode-time nil nil t)) - (delta (make-decoded-time :month 2))) - (encode-time (decoded-time-add time delta))) -@end lisp - -If this date doesn't exist (if you're running this on January 31st, -for instance), then the date will be shifted back until you get a -valid date (which will be February 28th or 29th, depending). - -Fields are added in a most to least significant order, so if the -adjustment described above happens, it happens before adding days, -hours, minutes or seconds. - -The values in @var{delta} can be negative to subtract values instead. - -The return value is a decoded time structure. -@end defun - -@defun make-decoded-time &key second minute hour day month year dst zone -Return a decoded time structure with only the given keywords filled -out, leaving the rest @code{nil}. For instance, to get a structure -that represents ``two months'', you could say: - -@lisp -(make-decoded-time :month 2) -@end lisp @end defun @defun encode-time time &rest obsolescent-arguments @@ -1673,9 +1667,26 @@ It can act as the inverse of @code{decode-time}. Ordinarily the first argument is a list @code{(@var{second} @var{minute} @var{hour} @var{day} @var{month} @var{year} @var{ignored} @var{dst} @var{zone})} that specifies a -decoded time in the style of @code{decode-time}, so that -@code{(encode-time (decode-time ...))} works. For the meanings of -these list members, see the table under @code{decode-time}. +decoded time in the style of @code{decode-time}. For the meanings of +these list elements, see the table under @code{decode-time}. +In particular, @var{dst} says how to interpret timestamps during a +daylight saving fallback when timestamps are repeated. +If @var{dst} is @minus{}1, the DST value is guessed; if it +is @code{t} or @code{nil} the timestamp with that DST value +is returned, with an error signaled if no such timestamp exists. +Unfortunately a @var{dst} value of @code{t} or @code{nil} does not +disambiguate timestamps duplicated when a TZDB-based timezone moves +further west of Greenwich, such as disambiguating the two +standard-time timestamps 2020-12-27 01:30 when @var{zone} is +@samp{"Europe/Volgograd"}, which at 02:00 that day changed +standard time from 4 to 3 hours east of Greenwich; if you need to +handle situations like this you can use a numeric @var{zone} to +disambiguate instead. + +The first argument can also be a list @code{(@var{second} @var{minute} +@var{hour} @var{day} @var{month} @var{year})}, which is treated like +the list @code{(@var{second} @var{minute} @var{hour} @var{day} +@var{month} @var{year} nil -1 nil)}. As an obsolescent calling convention, this function can be given six or more arguments. The first six arguments @var{second}, @@ -1684,14 +1695,18 @@ specify most of the components of a decoded time. If there are more than six arguments the @emph{last} argument is used as @var{zone} and any other extra arguments are ignored, so that @code{(apply #'encode-time (decode-time ...))} works. In this obsolescent -convention, @var{zone} defaults to the current time zone rule -(@pxref{Time Zone Rules}), and @var{dst} is treated as if it was -@minus{}1. +convention, @var{dst} is @minus{}1 and @var{zone} defaults to the +current time zone rule (@pxref{Time Zone Rules}). +When modernizing an obsolescent caller, ensure that the more-modern +list equivalent contains 9 elements with a @code{dst} element that +is @minus{}1, not @code{nil}. Year numbers less than 100 are not treated specially. If you want them to stand for years above 1900, or years above 2000, you must alter them yourself before you call @code{encode-time}. The operating system limits the range of time and zone values. +However, timestamps ranging from the epoch to the near future are +always supported. The @code{encode-time} function acts as a rough inverse to @code{decode-time}. For example, you can pass the output of @@ -1704,6 +1719,33 @@ the latter to the former as follows: You can perform simple date arithmetic by using out-of-range values for @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}; for example, day 0 means the day preceding the given month. +Take care when doing so, as it is common for this to fail in some cases. +For example: + +@lisp +;; Try to compute the time one month from now. +;; Watch out; this might not work as expected. +(let ((time (decode-time))) + (setf (decoded-time-month time) + (+ (decoded-time-month time) 1)) + time) +@end lisp + +@noindent +Unfortunately, this code might not work as expected if the resulting +time is invalid due to month length differences, +daylight saving transitions, time zone changes, +or missing leap days or leap seconds. For example, if executed on +January 30 this code yields a nonexistent date February 30, +which @code{encode-time} would adjust to early March. +Similarly, adding four years to February 29, 2096 would yield the +nonexistent date February 29, 2100; and adding one hour to 01:30 on +March 13, 2022 in New York would yield a timestamp 02:30 that does not +exist because clocks sprang forward from 02:00 to 03:00 that day. +To avoid some (though not all) of the problem, you +can base calculations on the middle of the affected unit, e.g., start +at the 15th of the month when adding months. Alternatively, you can use the +@file{calendar} and @file{time-date} libraries. @end defun @node Time Parsing @@ -1712,36 +1754,27 @@ for example, day 0 means the day preceding the given month. @cindex time formatting @cindex formatting time values - These functions convert time values to text in a string, and vice versa. -Time values include @code{nil}, numbers, and Lisp timestamps -(@pxref{Time of Day}). + These functions convert time values to text in a string, and vice +versa. Time values are either represented as a Lisp timestamp +(@pxref{Time of Day}) or a decoded time structure (@pxref{Time +Conversion}). @defun date-to-time string This function parses the time-string @var{string} and returns the corresponding Lisp timestamp. The argument @var{string} should represent a date-time, and should be in one of the forms recognized by @code{parse-time-string} (see below). This function assumes Universal -Time if @var{string} lacks explicit time zone information. +Time if @var{string} lacks explicit time zone information, +and assumes earliest values if @var{string} lacks month, day, or time. The operating system limits the range of time and zone values. @end defun @defun parse-time-string string -This function parses the time-string @var{string} into a list of the -following form: - -@example -(@var{sec} @var{min} @var{hour} @var{day} @var{mon} @var{year} @var{dow} @var{dst} @var{tz}) -@end example - -@noindent -The format of this list is the same as what @code{decode-time} accepts -(@pxref{Time Conversion}), and is described in more detail there. Any -@code{dst} element that cannot be determined from the input is set to -@minus{}1, and any other unknown element is set to -@code{nil}. The argument @var{string} should resemble an RFC 822 (or later) or -ISO 8601 string, like ``Fri, 25 Mar 2016 16:24:56 +0100'' or -``1998-09-12T12:21:54-0200'', but this function will attempt to parse -less well-formed time strings as well. +This function parses the time-string @var{string} into a decoded time +structure (@pxref{Time Conversion}). The argument @var{string} should +resemble an RFC 822 (or later) or ISO 8601 string, like ``Fri, 25 Mar +2016 16:24:56 +0100'' or ``1998-09-12T12:21:54-0200'', but this +function will attempt to parse less well-formed time strings as well. @end defun @vindex ISO 8601 date/time strings @@ -1758,11 +1791,11 @@ time structures, except the final one, which returns three of them @end defun @defun format-time-string format-string &optional time zone - -This function converts @var{time} (or the current time, if -@var{time} is omitted or @code{nil}) to a string according to -@var{format-string}. The conversion uses the time zone rule @var{zone}, which -defaults to the current time zone rule. @xref{Time Zone Rules}. The argument +This function converts @var{time} (which should be a Lisp timestamp, +and defaults to the current time if @var{time} is omitted or +@code{nil}) to a string according to @var{format-string}. The +conversion uses the time zone rule @var{zone}, which defaults to the +current time zone rule. @xref{Time Zone Rules}. 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: @@ -1957,6 +1990,10 @@ encountered. For example, the default format used by @w{@code{"%Y, %D, %H, %M, %z%S"}} means that the number of seconds will always be produced, but years, days, hours, and minutes will only be shown if they are non-zero. +@item %x +Non-printing control flag that works along the same lines as +@samp{%z}, but instead suppresses printing of trailing zero-value time +elements. @item %% Produces a literal @samp{%}. @end table @@ -2020,25 +2057,28 @@ interactively, it prints the duration in the echo area. These functions perform calendrical computations using time values (@pxref{Time of Day}). As with any time value, a value of @code{nil} for any of their -time-value arguments stands for the current system time, and a single +time-value arguments stands for the current system time, and a finite number stands for the number of seconds since the epoch. @defun time-less-p t1 t2 -This returns @code{t} if time value @var{t1} is less than time value +This returns @code{t} if the time value @var{t1} is less than the time value @var{t2}. -The result is @code{nil} if either argument is a NaN. @end defun @defun time-equal-p t1 t2 -This returns @code{t} if @var{t1} and @var{t2} are equal time values. -The result is @code{nil} if either argument is a NaN. +This returns @code{t} if the two time values @var{t1} and @var{t2} are +equal. The result is @code{nil} if either argument is a NaN. +For the purpose of comparison, a @code{nil} argument represents the +current time with infinite resolution, so this function returns +@code{nil} if one argument is @code{nil} and the other is not, and +callers can therefore use @code{nil} to represent an unknown time +value that does not equal any timestamp. @end defun @defun time-subtract t1 t2 This returns the time difference @var{t1} @minus{} @var{t2} between -two time values, as a Lisp time value. The result is exact and its clock +two time values, as a Lisp timestamp. The result is exact and its clock resolution is no worse than the worse of its two arguments' resolutions. -The result is floating-point only if it is infinite or a NaN@. If you need the difference in units of elapsed seconds, you can convert it with @code{time-convert} or @code{float-time}. @xref{Time Conversion}. @@ -2187,7 +2227,13 @@ In most cases, @var{repeat} has no effect on when @emph{first} call takes place---@var{time} alone specifies that. There is one exception: if @var{time} is @code{t}, then the timer runs whenever the time is a multiple of @var{repeat} seconds after the epoch. This is useful for -functions like @code{display-time}. +functions like @code{display-time}. For instance, the following will +make @var{function} run at every ``whole'' minute (e.g., +@samp{11:03:00}, @samp{11:04:00}, etc): + +@example +(run-at-time t 60 @var{function}) +@end example If Emacs didn't get any CPU time when the timer would have run (for example if the system was busy running another process or if the @@ -2697,6 +2743,13 @@ if it is non-@code{nil}; this can be overridden by binding @code{coding-system-for-write} to a coding system of you choice (@pxref{Explicit Encoding}). +In batch mode, Emacs will enlarge the value of the +@code{gc-cons-percentage} variable from the default of @samp{0.1} up to +@samp{1.0}. Batch jobs that are supposed to run for a long time +should adjust the limit back down again, because this means that less +garbage collection will be performed by default (and more memory +consumed). + @defvar noninteractive This variable is non-@code{nil} when Emacs is running in batch mode. @end defvar @@ -3122,6 +3175,9 @@ This is not detected by this function, and so a non-@code{nil} return value does not guarantee that changes on @var{file} will be actually notified. +If @var{file} is a symlink, it doesn't follow that link. Just +@var{file} itself will be watched. + @var{flags} is a list of conditions to set what will be watched for. It can include the following symbols: @@ -3242,6 +3298,14 @@ Removes an existing file watch specified by its @var{descriptor}. @code{file-notify-add-watch}. @end defun +@deffn Command file-notify-rm-all-watches +Removes all existing file notification watches from Emacs. + +Use this command with caution, because it could have unexpected side +effects on packages relying on file watches. It is intended mainly +for debugging purposes, or when Emacs has been stalled. +@end deffn + @defun file-notify-valid-p descriptor Checks a watch specified by its @var{descriptor} for validity. @var{descriptor} should be an object returned by diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index ca1166caac4..7945232bf8f 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -387,6 +387,16 @@ Return the position that @code{(end-of-line @var{count})} would move to. @end defun +@defun pos-bol &optional count +Like @code{line-beginning-position}, but ignores fields (and is more +efficient). +@end defun + +@defun pos-eol &optional count +Like @code{line-end-position}, but ignores fields (and is more +efficient). +@end defun + @deffn Command forward-line &optional count @cindex beginning of line This function moves point forward @var{count} lines, to the beginning of @@ -1002,6 +1012,12 @@ positions. In an interactive call, @var{start} and @var{end} are set to the bounds of the current region (point and the mark, with the smallest first). + +Note that, in rare circumstances, Emacs may decide to leave, for +performance reasons, the accessible portion of the buffer unchanged +after a call to @code{narrow-to-region}. This can happen when a Lisp +program is called via low-level hooks, such as +@code{jit-lock-functions}, @code{post-command-hook}, etc. @end deffn @deffn Command narrow-to-page &optional move-count @@ -1027,6 +1043,12 @@ It is equivalent to the following expression: @end example @end deffn +Note that, in rare circumstances, Emacs may decide to leave, for +performance reasons, the accessible portion of the buffer unchanged +after a call to @code{widen}. This can happen when a Lisp program is +called via low-level hooks, such as @code{jit-lock-functions}, +@code{post-command-hook}, etc. + @defun buffer-narrowed-p This function returns non-@code{nil} if the buffer is narrowed, and @code{nil} otherwise. diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 3fa6c844ae9..db6b4c35ef7 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -197,7 +197,7 @@ gives special treatment to certain characters, and if these characters occur in the file name, they will confuse the shell. To handle these characters, use the function @code{shell-quote-argument}: -@defun shell-quote-argument argument +@defun shell-quote-argument argument &optional posix This function returns a string that represents, in shell syntax, an argument whose actual contents are @var{argument}. It should work reliably to concatenate the return value into a shell command @@ -227,6 +227,15 @@ a shell command: " " (shell-quote-argument newfile)) @end example + +If the optional @var{posix} argument is non-@code{nil}, @var{argument} +is quoted according to POSIX shell quoting rules, regardless of the +system’s shell. This is useful when your shell could run on a remote +host, which requires a POSIX shell in general. + +@example +(shell-quote-argument "foo > bar" (file-remote-p default-directory)) +@end example @end defun @cindex quoting and unquoting command-line arguments @@ -696,12 +705,13 @@ coding system will apply. @xref{Default Coding Systems}. Initialize the type of device used to communicate with the subprocess. Possible values are @code{pty} to use a pty, @code{pipe} to use a pipe, or @code{nil} to use the default derived from the value of the -@code{process-connection-type} variable. This parameter and the value -of @code{process-connection-type} are ignored if a non-@code{nil} -value is specified for the @code{:stderr} parameter; in that case, the -type will always be @code{pipe}. On systems where ptys are not -available (MS-Windows), this parameter is likewise ignored, and pipes -are used unconditionally. +@code{process-connection-type} variable. If @var{type} is a cons cell +@w{@code{(@var{input} . @var{output})}}, then @var{input} will be used +for standard input and @var{output} for standard output (and standard +error if @code{:stderr} is @code{nil}). + +On systems where ptys are not available (MS-Windows), this parameter +is ignored, and pipes are used unconditionally. @item :noquery @var{query-flag} Initialize the process query flag to @var{query-flag}. @@ -966,6 +976,15 @@ use the function @code{process-tty-name} (@pxref{Process Information}). @end defvar +@defvar process-error-pause-time +If a process sentinel/filter function has an error, Emacs will (by +default) pause Emacs for @code{process-error-pause-time} seconds after +displaying this error, so that users will see the error in question. +However, this can lead to situations where Emacs becomes unresponsive +(if there's a lot of these errors happening), so this can be disabled +by setting @code{process-error-pause-time} to 0. +@end defvar + @node Deleting Processes @section Deleting Processes @cindex deleting processes @@ -993,16 +1012,18 @@ terminated (due to calling @code{exit} or to a signal). If it is they exit. @end defopt -@defun delete-process process +@defun delete-process &optional process This function deletes a process, killing it with a @code{SIGKILL} signal if the process was running a program. The argument may be a process, the name of a process, a buffer, or the name of a buffer. (A buffer or buffer-name stands for the process that -@code{get-buffer-process} returns.) Calling @code{delete-process} on -a running process terminates it, updates the process status, and runs -the sentinel immediately. If the process has already terminated, -calling @code{delete-process} has no effect on its status, or on the -running of its sentinel (which will happen sooner or later). +@code{get-buffer-process} returns, and a missing or @code{nil} +@var{process} means that the current buffer's process should be +killed.) Calling @code{delete-process} on a running process +terminates it, updates the process status, and runs the sentinel +immediately. If the process has already terminated, calling +@code{delete-process} has no effect on its status, or on the running +of its sentinel (which will happen sooner or later). If the process object represents a network, serial, or pipe connection, its status changes to @code{closed}; otherwise, it changes @@ -1222,15 +1243,24 @@ that are already closed, the value is either 0 or 256, depending on whether the connection was closed normally or abnormally. @end defun -@defun process-tty-name process +@defun process-tty-name process &optional stream 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 pty (see @code{process-connection-type} in -@ref{Asynchronous Processes}). If @var{process} represents a program -running on a remote host, the terminal name used by that program on -the remote host is provided as process property @code{remote-tty}. If -@var{process} represents a network, serial, or pipe connection, the -value is @code{nil}. +@ref{Asynchronous Processes}). By default, this function returns the +terminal name if any of @var{process}'s standard streams use a +terminal. If @var{stream} is one of @code{stdin}, @code{stdout}, or +@code{stderr}, this function returns the terminal name (or @code{nil}, +as above) that @var{process} uses for that stream specifically. You +can use this to determine whether a particular stream uses a pipe or a +pty. + +If @var{process} represents a program running on a remote host, this +function returns the @emph{local} terminal name that communicates with +@var{process}; you can get the terminal name used by that program on +the remote host with the process property @code{remote-tty}. If +@var{process} represents a network, serial, or pipe connection, this +function always returns @code{nil}. @end defun @defun process-coding-system process @@ -1413,11 +1443,13 @@ non-@code{nil}, you can think of this function as typing @kbd{C-c} on the terminal by which Emacs talks to the subprocess. @end defun -@defun kill-process &optional process current-group -This function kills the process @var{process} by sending the +@deffn Command kill-process &optional process current-group +This command kills the process @var{process} by sending the signal @code{SIGKILL}. This signal kills the subprocess immediately, -and cannot be handled by the subprocess. -@end defun +and cannot be handled by the subprocess. Interactively, it'll prompt +the user for a process name, defaulting to the process (if any) in the +current buffer. +@end deffn @defun quit-process &optional process current-group This function sends the signal @code{SIGQUIT} to the process @@ -1452,7 +1484,7 @@ incoming data from the connection. For serial connections, data that arrived during the time the process was stopped might be lost. @end defun -@deffn Command signal-process process signal +@deffn Command signal-process process signal &optional remote This function sends a signal to process @var{process}. The argument @var{signal} specifies which signal to send; it should be an integer, or a symbol whose name is a signal. @@ -1460,12 +1492,18 @@ or a symbol whose name is a signal. The @var{process} argument can be a system process @acronym{ID} (an integer); that allows you to send signals to processes that are not children of Emacs. @xref{System Processes}. + +If @var{process} is a process object which contains the property +@code{remote-pid}, or @var{process} is a number and @var{remote} is a +remote file name, @var{process} is interpreted as process on the +respective remote host, which will be the process to signal. @end deffn Sometimes, it is necessary to send a signal to a non-local asynchronous process. This is possible by writing an own -@code{interrupt-process} implementation. This function must be added -then to @code{interrupt-process-functions}. +@code{interrupt-process} or @code{signal-process} implementation. +This function must be added then to @code{interrupt-process-functions} +or @code{signal-process-functions}, respectively. @defvar interrupt-process-functions This variable is a list of functions to be called for @@ -1478,6 +1516,17 @@ default function, which shall always be the last in this list, is This is the mechanism, how Tramp implements @code{interrupt-process}. @end defvar +@defvar signal-process-functions +This variable is a list of functions to be called for +@code{signal-process}. The arguments of the functions are the same as +for @code{signal-process}. These functions are called in the order of +the list, until one of them returns non-@code{nil}. The default +function, which shall always be the last in this list, is +@code{internal-default-signal-process}. + +This is the mechanism, how Tramp implements @code{signal-process}. +@end defvar + @node Output from Processes @section Receiving Output from Processes @cindex process output @@ -1491,20 +1540,11 @@ a buffer, which is called the associated buffer of the process default filter discards the output. If the subprocess writes to its standard error stream, by default -the error output is also passed to the process filter function. If -Emacs uses a pseudo-TTY (pty) for communication with the subprocess, -then it is impossible to separate the standard output and standard -error streams of the subprocess, because a pseudo-TTY has only one -output channel. In that case, if you want to keep the output to those -streams separate, you should redirect one of them to a file---for -example, by using an appropriate shell command via -@code{start-process-shell-command} or a similar function. - - Alternatively, you could use the @code{:stderr} parameter with a +the error output is also passed to the process filter function. +Alternatively, you could use the @code{:stderr} parameter with a non-@code{nil} value in a call to @code{make-process} (@pxref{Asynchronous Processes, make-process}) to make the destination -of the error output separate from the standard output; in that case, -Emacs will use pipes for communicating with the subprocess. +of the error output separate from the standard output. When a subprocess terminates, Emacs reads any pending output, then stops reading output from that subprocess. Therefore, if the @@ -1920,7 +1960,6 @@ because @var{seconds} can be floating point to specify waiting a fractional number of seconds. If @var{seconds} is 0, the function accepts whatever output is pending but does not wait. -@c Emacs 22.1 feature If @var{process} is a process, and the argument @var{just-this-one} is non-@code{nil}, only output from that process is handled, suspending output from other processes until some output has been received from that @@ -2221,9 +2260,8 @@ query flag of all processes is ignored. In addition to accessing and manipulating processes that are subprocesses of the current Emacs session, Emacs Lisp programs can -also access other processes running on the same machine. We call -these @dfn{system processes}, to distinguish them from Emacs -subprocesses. +also access other processes. We call these @dfn{system processes}, to +distinguish them from Emacs subprocesses. Emacs provides several primitives for accessing system processes. Not all platforms support these primitives; on those which don't, @@ -2235,6 +2273,9 @@ system. Each process is identified by its @acronym{PID}, a numerical process ID that is assigned by the OS and distinguishes the process from all the other processes running on the same machine at the same time. + +If @code{default-directory} points to a remote host, processes of that +host are returned. @end defun @defun process-attributes pid @@ -2246,6 +2287,9 @@ attribute @var{key}s that this function can return are listed below. Not all platforms support all of these attributes; if an attribute is not supported, its association will not appear in the returned alist. +If @code{default-directory} points to a remote host, @var{pid} is +regarded as process of that host. + @table @code @item euid The effective user ID of the user who invoked the process. The @@ -2371,8 +2415,9 @@ occupied by the process in the machine's physical memory. @item pcpu The percentage of the CPU time used by the process since it started. -The corresponding @var{value} is a floating-point number between 0 and -100. +The corresponding @var{value} is a nonnegative floating-point number. +Although in theory the number can exceed 100 on a multicore platform, +it is usually less than 100 because Emacs is typically single-threaded. @item pmem The percentage of the total physical memory installed on the machine @@ -3159,20 +3204,39 @@ If the vector does not include the port number, @var{p}, or if @code{:@var{p}} suffix. @end defun -@defun network-lookup-address-info name &optional family -This function is used to perform hostname lookups on @var{name}, which -is expected to be an ASCII-only string, otherwise an error is -signaled. Call @code{puny-encode-domain} on @var{name} -first if you wish to lookup internationalized hostnames. +@defun network-lookup-address-info name &optional family hints +This function perform hostname lookups on @var{name}, which is +expected to be an ASCII-only string, otherwise it signals an error. Call +@code{puny-encode-domain} on @var{name} first if you wish to lookup +internationalized hostnames. -If successful it returns a list of Lisp representations of network -addresses, otherwise it returns @code{nil}. In the latter case, it -also displays the error message hopefully explaining what went wrong. +If successful, this function returns a list of Lisp representations of network +addresses (@pxref{Network Processes}, for a description of the +format), otherwise return @code{nil}. In the latter case, it also logs +an error message hopefully explaining what went wrong. -By default both IPv4 and IPv6 lookups are attempted. The optional -argument @var{family} controls this behavior, specifying the symbol -@code{ipv4} or @code{ipv6} restricts lookups to IPv4 and IPv6 +By default, this function attempts both IPv4 and IPv6 lookups. The +optional argument @var{family} controls this behavior, specifying the +symbol @code{ipv4} or @code{ipv6} restricts lookups to IPv4 and IPv6 respectively. + +If optional argument @var{hints} is @code{numeric}, the function +treats the @var{name} as a numerical IP address (and does not perform DNS +lookups). This can be used to check whether a string is a valid +numerical representation of an IP address, or to convert a numerical +string to its canonical representation. e.g.@: + +@example +(network-lookup-address-info "127.1" 'ipv4 'numeric) + @result{} ([127 0 0 1 0]) + +(network-lookup-address-info "::1" nil 'numeric) + @result{} ([0 0 0 0 0 0 0 1 0]) +@end example + +Be warned that there are some surprising valid forms, +especially for IPv4, e.g @samp{0xe3010203} and @samp{0343.1.2.3} are both +valid, as are @samp{0} and @samp{1} (but they are invalid for IPv6). @end defun @node Serial Ports @@ -3425,20 +3489,64 @@ type values: @itemx byte Unsigned byte, with length 1. -@item uint @var{bitlen} -Unsigned integer in network byte order, with @var{bitlen} bits. +@item uint @var{bitlen} &optional @var{le} +Unsigned integer in network byte order (big-endian), with @var{bitlen} bits. @var{bitlen} has to be a multiple of 8. +If @var{le} is non-@code{nil}, then use little-endian byte order. -@item uintr @var{bitlen} -Unsigned integer in little endian order, with @var{bitlen} bits. +@item sint @var{bitlen} @var{le} +Signed integer in network byte order (big-endian), with @var{bitlen} bits. @var{bitlen} has to be a multiple of 8. +If @var{le} is non-@code{nil}, then use little-endian byte order. @item str @var{len} -String of bytes of length @var{len}. +Unibyte string (@pxref{Text Representations}) of length @var{len} bytes. +When packing, the first @var{len} bytes of the input string are copied +to the packed output. If the input string is shorter than @var{len}, +the remaining bytes will be null (zero) unless a pre-allocated string +was provided to @code{bindat-pack}, in which case the remaining bytes +are left unmodified. If the input string is multibyte with only ASCII +and @code{eight-bit} characters, it is converted to unibyte before it +is packed; other multibyte strings signal an error. When unpacking, +any null bytes in the packed input string will appear in the unpacked +output. @item strz &optional @var{len} -Zero-terminated string of bytes, can be of arbitrary length or in a fixed-size -field with length @var{len}. +If @var{len} is not provided, this is a variable-length +null-terminated unibyte string (@pxref{Text Representations}). When +packing into @code{strz}, the entire input string is copied to the +packed output followed by a null (zero) byte. (If pre-allocated +string is provided for packing into @code{strz}, that pre-allocated +string should have enough space for the additional null byte appended +to the output string contents, @pxref{Bindat Functions}). The length +of the packed output is the length of the input string plus one (for +the null terminator). The input string must not contain any null +bytes. If the input string is multibyte with only ASCII and +@code{eight-bit} characters, it is converted to unibyte before it is +packed; other multibyte strings signal an error. When unpacking a +@code{strz}, the resulting output string will contain all bytes up to +(but excluding) the null byte that terminated the input string. + +If @var{len} is provided, @code{strz} behaves the same as @code{str}, +but with a couple of differences: + +@itemize @bullet +@item +When packing, a null terminator is written after the packed input +string if the number of characters in the input string is less than +@var{len}. + +@item +When unpacking, the first null byte encountered in the packed string +is interpreted as the terminating byte, and it and all subsequent +bytes are excluded from the result of the unpacking. +@end itemize + +@quotation Caution +The packed output will not be null-terminated unless the input string +is shorter than @var{len} bytes or it contains a null byte within the +first @var{len} bytes. +@end quotation @item vec @var{len} [@var{type}] Vector of @var{len} elements. The type of the elements is given by @@ -3458,7 +3566,7 @@ and @code{#x1c} @code{#x28} to @w{@code{(3 5 10 11 12)}}. @item fill @var{len} @var{len} bytes used as a mere filler. In packing, these bytes are -are left unchanged, which normally means they remain zero. +left unchanged, which normally means they remain zero. When unpacking, this just returns nil. @item align @var{len} diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index fe4de0abbb2..5ee139a11d3 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -549,12 +549,12 @@ can act. It is poor practice to depend on this behavior; quote the special character anyway, regardless of where it appears. As a @samp{\} is not special inside a character alternative, it can -never remove the special meaning of @samp{-} or @samp{]}. So you -should not quote these characters when they have no special meaning -either. This would not clarify anything, since backslashes can -legitimately precede these characters where they @emph{have} special -meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), -which matches any single character except a backslash. +never remove the special meaning of @samp{-}, @samp{^} or @samp{]}. +You should not quote these characters when they have no special +meaning. This would not clarify anything, since backslashes +can legitimately precede these characters where they @emph{have} +special meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string +syntax), which matches any single character except a backslash. In practice, most @samp{]} that occur in regular expressions close a character alternative and hence are special. However, occasionally a @@ -823,21 +823,22 @@ the characters that stand for them. matches any character whose syntax is not @var{code}. @cindex category, regexp search for -@item \c@var{c} -matches any character whose category is @var{c}. Here @var{c} is a -character that represents a category: thus, @samp{c} for Chinese -characters or @samp{g} for Greek characters in the standard category -table. You can see the list of all the currently defined categories -with @kbd{M-x describe-categories @key{RET}}. You can also define -your own categories in addition to the standard ones using the -@code{define-category} function (@pxref{Categories}). - -@item \C@var{c} -matches any character whose category is not @var{c}. +@item \c@var{code} +matches any character whose category is @var{code}. Here @var{code} +is a character that represents a category: for example, in the standard +category table, @samp{c} stands for Chinese characters and @samp{g} +stands for Greek characters. You can see the list of all the +currently defined categories with @w{@kbd{M-x describe-categories +@key{RET}}}. You can also define your own categories in addition to +the standard ones using the @code{define-category} function +(@pxref{Categories}). + +@item \C@var{code} +matches any character whose category is not @var{code}. @end table The following regular expression constructs match the empty string---that is, -they don't use up any characters---but whether they match depends on the +they don't consume any characters---but whether they match depends on the context. For all, the beginning and end of the accessible portion of the buffer are treated as if they were the actual beginning and end of the buffer. @@ -2045,7 +2046,7 @@ feature for matching regular expressions from end to beginning. It's not worth the trouble of implementing that. @end deffn -@defun string-match regexp string &optional start +@defun string-match regexp string &optional start inhibit-modify This function returns the index of the start of the first match for the regular expression @var{regexp} in @var{string}, or @code{nil} if there is no match. If @var{start} is non-@code{nil}, the search starts @@ -2070,8 +2071,10 @@ For example, The index of the first character of the string is 0, the index of the second character is 1, and so on. -If this function finds a match, the index of the first character beyond -the match is available as @code{(match-end 0)}. @xref{Match Data}. +By default, if this function finds a match, the index of the first +character beyond the match is available as @code{(match-end 0)}. +@xref{Match Data}. If @var{inhibit-modify} is non-@code{nil}, the +match data isn't modified. @example @group @@ -2092,16 +2095,18 @@ This predicate function does what @code{string-match} does, but it avoids modifying the match data. @end defun -@defun looking-at regexp +@defun looking-at regexp &optional inhibit-modify This function determines whether the text in the current buffer directly following point matches the regular expression @var{regexp}. ``Directly following'' means precisely that: the search is ``anchored'' and it can succeed only starting with the first character following point. The result is @code{t} if so, @code{nil} otherwise. -This function does not move point, but it does update the match data. -@xref{Match Data}. If you need to test for a match without modifying -the match data, use @code{looking-at-p}, described below. +This function does not move point, but it does update the match data +(if @var{inhibit-modify} is @code{nil} or missing, which is the +default). @xref{Match Data}. As a convenience, instead of using the +@var{inhibit-modify} argument, you can use @code{looking-at-p}, +described below. In this example, point is located directly before the @samp{T}. If it were anywhere else, the result would be @code{nil}. @@ -2208,13 +2213,13 @@ backtracking specified by the POSIX standard for regular expression matching. @end deffn -@defun posix-looking-at regexp +@defun posix-looking-at regexp &optional inhibit-modify 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 +@defun posix-string-match regexp string &optional start inhibit-modify This is like @code{string-match} except that it performs the full backtracking specified by the POSIX standard for regular expression matching. @@ -2850,7 +2855,7 @@ Display some help, then ask again. @defvar multi-query-replace-map This variable holds a keymap that extends @code{query-replace-map} by -providing additional keybindings that are useful in multi-buffer +providing additional key bindings that are useful in multi-buffer replacements. The additional bindings are: @table @code diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index c3f4cff3015..12c15e6f9a2 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -446,8 +446,7 @@ useful example of @code{sort}. @cindex seq library @cindex sequences, generalized The @file{seq.el} library provides the following additional sequence -manipulation macros and functions, prefixed with @code{seq-}. To use -them, you must first load the @file{seq} library. +manipulation macros and functions, prefixed with @code{seq-}. All functions defined in this library are free of side-effects; i.e., they do not modify any sequence (list, vector, or string) that @@ -577,6 +576,20 @@ starting from the first one for which @var{predicate} returns @code{nil}. @end example @end defun +@defun seq-split sequence length + This function returns a list consisting of sub-sequences of +@var{sequence} of (at most) length @var{length}. (The final element +may be shorter than @var{length} if the length of @var{sequence} isn't +a multiple of @var{length}. + +@example +@group +(seq-split [0 1 2 3 4] 2) +@result{} ([0 1] [2 3] [4]) +@end group +@end example +@end defun + @defun seq-do function sequence This function applies @var{function} to each element of @var{sequence} in turn (presumably for side effects), and returns @@ -667,6 +680,24 @@ for which @var{predicate} returns @code{nil}. @end example @end defun +@defun seq-remove-at-position sequence n +@cindex removing from sequences +This function returns a copy of @var{sequence} where the element at +(zero-based) index @var{n} got removed. The result is a sequence of +the same type as @var{sequence}. + +@example +@group +(seq-remove-at-position [1 -1 3 -3 5] 0) +@result{} [-1 3 -3 5] +@end group +@group +(seq-remove-at-position [1 -1 3 -3 5] 3) +@result{} [1 -1 3 5] +@end group +@end example +@end defun + @defun seq-reduce function sequence initial-value @cindex reducing sequences This function returns the result of calling @var{function} with @@ -850,7 +881,7 @@ arguments to use instead of the default @code{equal}. @end defun @defun seq-position sequence elt &optional function - This function returns the index of the first element in + This function returns the (zero-based) index of the first element in @var{sequence} that is equal to @var{elt}. If the optional argument @var{function} is non-@code{nil}, it is a function of two arguments to use instead of the default @code{equal}. @@ -867,6 +898,27 @@ use instead of the default @code{equal}. @end example @end defun +@defun seq-positions sequence elt &optional testfn + This function returns a list of the (zero-based) indices of the +elements in @var{sequence} for which @var{testfn} returns +non-@code{nil} when passed the element and @var{elt} as +arguments. @var{testfn} defaults to @code{equal}. + +@example +@group +(seq-positions '(a b c a d) 'a) +@result{} (0 3) +@end group +@group +(seq-positions '(a b c a d) 'z) +@result{} nil +@end group +@group +(seq-positions '(11 5 7 12 9 15) 10 #'>=) +@result{} (0 3 5) +@end group +@end example +@end defun @defun seq-uniq sequence &optional function This function returns a list of the elements of @var{sequence} with diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi index c6b3397ae11..bba1dc2eee9 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -21,6 +21,7 @@ reading) or where to put it (if printing). * Output Streams:: Various data types that can be used as output streams. * Output Functions:: Functions to print Lisp objects as text. * Output Variables:: Variables that control what the printing functions do. +* Output Overrides:: Overriding output variables. @end menu @node Streams Intro @@ -327,6 +328,15 @@ For example: @end example @end defun +@defun read-positioning-symbols &optional stream +This function reads one textual expression from @var{stream}, like +@code{read} does, but additionally positions the read symbols to the +positions in @var{stream} where they occurred. Only the symbol +@code{nil} is not positioned, this for efficiency reasons. +@xref{Symbols with Position}. This function is used by the byte +compiler. +@end defun + @defvar standard-input This variable holds the default input stream---the stream that @code{read} uses when the @var{stream} argument is @code{nil}. @@ -358,6 +368,15 @@ mode for @var{stream}. On POSIX hosts, it always returns a non-@code{nil} value and does nothing except flushing pending output. @end defun +@defun readablep object +@cindex readable syntax +This predicate says whether @var{object} has @dfn{readable syntax}, +i.e., it can be written out and then read back by the Emacs Lisp +reader. If it can't, this function returns @code{nil}; if it can, +this function returns a printed representation (via @code{prin1}, +@pxref{Output Functions}) of @var{object}. +@end defun + @node Output Streams @section Output Streams @cindex stream (for printing) @@ -616,7 +635,7 @@ characters are used. @code{print} returns @var{object}. For example: @end example @end defun -@defun prin1 object &optional stream +@defun prin1 object &optional stream overrides This function outputs the printed representation of @var{object} to @var{stream}. It does not print newlines to separate output as @code{print} does, but it does use quoting characters just like @@ -631,6 +650,10 @@ This function outputs the printed representation of @var{object} to @result{} " came back" @end group @end example + +If @var{overrides} is non-@code{nil}, it should either be @code{t} +(which tells @code{prin1} to use the defaults for all printer related +variables), or a list of settings. @xref{Output Overrides}, for details. @end defun @defun princ object &optional stream @@ -667,7 +690,16 @@ This function outputs @var{character} to @var{stream}. It returns @var{character}. @end defun -@defun prin1-to-string object &optional noescape +@defun flush-standard-output +If you have Emacs-based batch scripts that send output to the +terminal, Emacs will automatically display the output whenever you +write a newline characters to @code{standard-output}. This function +allows you to flush to @code{standard-output} without sending a +newline character first, which enables you to display incomplete +lines. +@end defun + +@defun prin1-to-string object &optional noescape overrides @cindex object to string This function returns a string containing the text that @code{prin1} would have printed for the same argument. @@ -681,6 +713,10 @@ would have printed for the same argument. (prin1-to-string (mark-marker)) @result{} "#<marker at 2773 in strings.texi>" @end group + +If @var{overrides} is non-@code{nil}, it should either be @code{t} +(which tells @code{prin1} to use the defaults for all printer related +variables), or a list of settings. @xref{Output Overrides}, for details. @end example If @var{noescape} is non-@code{nil}, that inhibits use of quoting @@ -872,6 +908,32 @@ If non-@code{nil}, this variable enables detection of circular and shared structure in printing. @xref{Circular Objects}. @end defvar +@defvar print-unreadable-function +By default, Emacs prints unreadable objects as @samp{#<...>"}. For +instance: + +@example +(prin1-to-string (make-marker)) + @result{} "#<marker in no buffer>" +@end example + +If this variable is non-@code{nil}, it should be a function that will +be called to handle printing of these objects. The function will be +called with two arguments: the object and the @var{noescape} flag used by +the printing functions (@pxref{Output Functions}). + +The function should return either @code{nil} (print the object as +usual), or a string (which will be printed), or any other object +(don't print the object). For instance: + +@example +(let ((print-unreadable-function + (lambda (object escape) "hello"))) + (prin1-to-string (make-marker))) + @result{} "hello" +@end example +@end defvar + @defvar print-gensym If non-@code{nil}, this variable enables detection of uninterned symbols (@pxref{Creating Symbols}) in printing. When this is enabled, @@ -918,3 +980,84 @@ Letter, Number, Punctuation, Symbol and Private-use (@pxref{Character Properties}), as well as the control characters having their own escape syntax such as newline. @end defvar + +@node Output Overrides +@section Overriding Output Variables +@cindex overrides, in output functions +@cindex output variables, overriding + +The previous section (@pxref{Output Functions}) lists the numerous +variables that control how the Emacs Lisp printer formats data for +outputs. These are generally available for users to change, but +sometimes you want to output data in the default format, or override +the user settings in some other way. For instance, if you're storing +Emacs Lisp data in a file, you don't want that data to be shortened by +a @code{print-length} setting. + +The @code{prin1} and @code{prin1-to-string} functions therefore have +an optional @var{overrides} argument. This argument can either be +@code{t} (which means that all printing variables should be reset to +the default values), or a list of settings for some of the variables. +Each element in the list can be either @code{t} (which means ``reset +to defaults'', and will usually be the first element of the list), or +a pair whose @code{car} is a symbol that stands for an output variable +and whose @code{cdr} is the value for that variable. + +For instance, this prints using nothing but defaults: + +@lisp +(prin1 object nil t) +@end lisp + +This prints @var{object} using the current printing settings, but +overrides the value of @code{print-length} to be 5: + +@lisp +(prin1 object nil '((length . 5))) +@end lisp + +And finally, this prints @var{object} using only default settings, but +with @code{print-length} bound to 5: + +@lisp +(prin1 object nil '(t (length . 5))) +@end lisp + +Below is a list of symbols that can be used, and which variables they +map to: + +@table @code +@item length +This overrides @code{print-length}. +@item level +This overrides @code{print-level}. +@item circle +This overrides @code{print-circle}. +@item quoted +This overrides @code{print-quoted}. +@item escape-newlines +This overrides @code{print-escape-newlines}. +@item escape-control-characters +This overrides @code{print-escape-control-characters}. +@item escape-nonascii +This overrides @code{print-escape-nonascii}. +@item escape-multibyte +This overrides @code{print-escape-multibyte}. +@item charset-text-property +This overrides @code{print-charset-text-property}. +@item unreadeable-function +This overrides @code{print-unreadable-function}. +@item gensym +This overrides @code{print-gensym}. +@item continuous-numbering +This overrides @code{print-continuous-numbering}. +@item number-table +This overrides @code{print-number-table}. +@item float-format +This overrides @code{float-output-format}. +@item integers-as-characters +This overrides @code{print-integers-as-characters}. +@end table + +In the future, more overrides may be offered that do not map directly +to a variable, but can only be used via this parameter. diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 89120575f52..374381e5955 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -430,13 +430,16 @@ middle of a character representation. This function measures the string length in characters or bytes, and thus is generally inappropriate if you need to shorten strings for display purposes; use @code{truncate-string-to-width} or -@code{window-text-pixel-size} instead (@pxref{Size of Displayed -Text}). +@code{window-text-pixel-size} or @code{string-glyph-split} instead +(@pxref{Size of Displayed Text}). @end defun -@defun string-lines string &optional omit-nulls +@defun string-lines string &optional omit-nulls keep-newlines Split @var{string} into a list of strings on newline boundaries. If -@var{omit-nulls}, remove empty lines from the results. +the optional argument @var{omit-nulls} is non-@code{nil}, remove empty +lines from the results. If the optional argument @var{keep-newlines} +is non-@code{nil}, don't remove the trailing newlines from the result +strings. @end defun @defun string-pad string length &optional padding start @@ -557,6 +560,12 @@ Representations}. @code{string-equal} is another name for @code{string=}. @end defun +@defun string-equal-ignore-case string1 string2 +@code{string-equal-ignore-case} compares strings ignoring case +differences, like @code{char-equal} when @code{case-fold-search} is +@code{t}. +@end defun + @cindex locale-dependent string equivalence @defun string-collate-equalp string1 string2 &optional locale ignore-case This function returns @code{t} if @var{string1} and @var{string2} are diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index a951e9be8ae..ea1e086ebf1 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -23,15 +23,15 @@ otherwise. @end defun @menu -* Symbol Components:: Symbols have names, values, function definitions +* Symbol Components:: Symbols have names, values, function definitions and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Symbol Properties:: Each symbol has a property list +* Definitions:: A definition says how a symbol will be used. +* Creating Symbols:: How symbols are kept unique. +* Symbol Properties:: Each symbol has a property list for recording miscellaneous information. -* Shorthands:: Properly organize your symbol names but +* Shorthands:: Properly organize your symbol names but type less of them. - +* Symbols with Position:: Symbol variants containing integer positions @end menu @node Symbol Components @@ -432,8 +432,8 @@ symbol's property list cell (@pxref{Symbol Components}), in the form of a property list (@pxref{Property Lists}). @menu -* Symbol Plists:: Accessing symbol properties. -* Standard Properties:: Standard meanings of symbol properties. +* Symbol Plists:: Accessing symbol properties. +* Standard Properties:: Standard meanings of symbol properties. @end menu @node Symbol Plists @@ -613,7 +613,10 @@ file-local evaluation forms. @xref{File Local Variables}. @item safe-local-variable The value specifies a function for determining safe file-local values -for the named variable. @xref{File Local Variables}. +for the named variable. @xref{File Local Variables}. Since this +value is consulted when loading files, the function should be +efficient and should ideally not lead to loading any libraries to +determine the safeness (e.g., it should not be an autoloaded function). @item side-effect-free @cindex @code{side-effect-free} property @@ -751,3 +754,70 @@ those names. @item Symbol forms whose names start with @samp{#_} are not transformed. @end itemize + +@node Symbols with Position +@section Symbols with Position +@cindex symbol with position + +@cindex bare symbol +A @dfn{symbol with position} is a symbol, the @dfn{bare symbol}, +together with an unsigned integer called the @dfn{position}. These +objects are intended for use by the byte compiler, which records in +them the position of each symbol occurrence and uses those positions +in warning and error messages. + +The printed representation of a symbol with position uses the hash +notation outlined in @ref{Printed Representation}. It looks like +@samp{#<symbol foo at 12345>}. It has no read syntax. You can cause +just the bare symbol to be printed by binding the variable +@code{print-symbols-bare} to non-@code{nil} around the print +operation. The byte compiler does this before writing its output to +the compiled Lisp file. + +For most purposes, when the flag variable +@code{symbols-with-pos-enabled} is non-@code{nil}, symbols with +positions behave just as bare symbols do. For example, @samp{(eq +#<symbol foo at 12345> foo)} has a value @code{t} when that variable +is set (but @code{nil} when it isn't set). Most of the time in Emacs this +variable is @code{nil}, but the byte compiler binds it to @code{t} +when it runs. + +Typically, symbols with position are created by the byte compiler +calling the reader function @code{read-positioning-symbols} +(@pxref{Input Functions}). One can also be created with the function +@code{position-symbol}. + +@defvar symbols-with-pos-enabled +When this variable is non-@code{nil}, symbols with position behave +like the contained bare symbol. Emacs runs a little more slowly in +this case. +@end defvar + +@defvar print-symbols-bare +When bound to non-nil, the Lisp printer prints only the bare symbol of +a symbol with position, ignoring the position. +@end defvar + +@defun symbol-with-pos-p symbol. +This function returns @code{t} if @var{symbol} is a symbol with +position, @code{nil} otherwise. +@end defun + +@defun bare-symbol symbol +This function returns the bare symbol contained in @var{symbol}, or +@var{symbol} itself if it is already a bare symbol. For any other +type of object, it signals an error. +@end defun + +@defun symbol-with-pos-pos symbol +This function returns the position, a number, from a symbol with +position. For any other type of object, it signals an error. +@end defun + +@defun position-symbol sym pos +Make a new symbol with position. @var{sym} is either a bare symbol or +a symbol with position, and supplies the symbol part of the new +object. @var{pos} is either an integer which becomes the number part +of the new object, or a symbol with position whose position is used. +Emacs signals an error if either argument is invalid. +@end defun diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 72fb674aa5a..8b859042ad0 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -59,7 +59,9 @@ the character after point. * Decompression:: Dealing with compressed data. * Base 64:: Conversion to or from base 64 encoding. * Checksum/Hash:: Computing cryptographic hashes. +* Suspicious Text:: Determining whether a string is suspicious. * GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS. +* Database:: Interacting with an SQL database. * Parsing HTML/XML:: Parsing HTML and XML. * Parsing JSON:: Parsing and generating JSON values. * JSONRPC:: JSON Remote Procedure Call protocol @@ -241,10 +243,8 @@ using a function specified by the variable The default filter function consults the obsolete wrapper hook @code{filter-buffer-substring-functions} (see the documentation string of the macro @code{with-wrapper-hook} for the details about this -obsolete facility), and the obsolete variable -@code{buffer-substring-filters}. If both of these are @code{nil}, it -returns the unaltered text from the buffer, i.e., what -@code{buffer-substring} would return. +obsolete facility). If it is @code{nil}, it returns the unaltered +text from the buffer, i.e., what @code{buffer-substring} would return. If @var{delete} is non-@code{nil}, the function deletes the text between @var{start} and @var{end} after copying it, like @@ -280,22 +280,12 @@ the same as those of @code{filter-buffer-substring}. The first hook function is passed a @var{fun} that is equivalent to the default operation of @code{filter-buffer-substring}, i.e., it -returns the buffer-substring between @var{start} and @var{end} -(processed by any @code{buffer-substring-filters}) and optionally -deletes the original text from the buffer. In most cases, the hook -function will call @var{fun} once, and then do its own processing of -the result. The next hook function receives a @var{fun} equivalent to -this, and so on. The actual return value is the result of all the -hook functions acting in sequence. -@end defvar - -@defvar buffer-substring-filters -The value of this obsolete variable should be a list of functions -that accept a single string argument and return another string. -The default @code{filter-buffer-substring} function passes the buffer -substring to the first function in this list, and the return value of -each function is passed to the next function. The return value of the -last function is passed to @code{filter-buffer-substring-functions}. +returns the buffer-substring between @var{start} and @var{end} and +optionally deletes the original text from the buffer. In most cases, +the hook function will call @var{fun} once, and then do its own +processing of the result. The next hook function receives a @var{fun} +equivalent to this, and so on. The actual return value is the result +of all the hook functions acting in sequence. @end defvar @defun current-word &optional strict really-word @@ -599,6 +589,19 @@ This command indents to the left margin if that is not zero. The value returned is @code{nil}. @end deffn +@deffn Command ensure-empty-lines &optional number-of-empty-lines +This command can be used to ensure that you have a specific number of +empty lines before point. (An ``empty line'' is here defined as a +line with no characters on it---a line with space characters isn't an +empty line.) It defaults to ensuring that there's a single empty line +before point. + +If point isn't at the beginning of a line, a newline character is +inserted first. If there's more empty lines before point than +specified, the number of empty lines is reduced. Otherwise it's +increased to the specified number. +@end deffn + @defvar overwrite-mode This variable controls whether overwrite mode is in effect. The value should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, @@ -1019,6 +1022,9 @@ text in @var{string} according to the @code{yank-handler} text property, as well as the variables @code{yank-handled-properties} and @code{yank-excluded-properties} (see below), before inserting the result into the current buffer. + +@var{string} will be run through @code{yank-transform-functions} (see +below) before inserting. @end defun @defun insert-buffer-substring-as-yank buf &optional start end @@ -1093,6 +1099,23 @@ or specifying key bindings. It takes effect after @code{yank-handled-properties}. @end defopt +@defvar yank-transform-functions +This variable is a list of functions. Each function is called (in +order) with the string to be yanked as the argument, and should +return a (possibly transformed) string. This variable can be set +globally, but can also be used to create new commands that are +variations on @code{yank}. For instance, to create a command that +works like @code{yank}, but cleans up whitespace before inserting, you +could say something like: + +@lisp +(defun yank-with-clean-whitespace () + (interactive) + (let ((yank-transform-functions + '(string-clean-whitespace))) + (call-interactively #'yank))) +@end lisp +@end defvar @node Yank Commands @subsection Functions for Yanking @@ -1329,7 +1352,7 @@ that @kbd{C-y} should yank. @defopt kill-ring-max The value of this variable is the maximum length to which the kill ring can grow, before elements are thrown away at the end. The default -value for @code{kill-ring-max} is 60. +value for @code{kill-ring-max} is 120. @end defopt @node Undo @@ -1493,6 +1516,11 @@ continuing to undo. This function does not bind @code{undo-in-progress}. @end defun +@defmac with-undo-amalgamate body@dots{} +This macro removes all the undo boundaries inserted during the +execution of @var{body} so that it can be undone as a single step. +@end defmac + Some commands leave the region active after execution in such a way that it interferes with selective undo of that command. To make @code{undo} ignore the active region when invoked immediately after such a command, @@ -1633,6 +1661,47 @@ The variable @code{paragraph-separate} controls how to distinguish paragraphs. @xref{Standard Regexps}. @end deffn +@defun pixel-fill-region start end pixel-width +Most Emacs buffers use monospaced text, so all the filling functions +(like @code{fill-region}) work based on the number of characters and +@code{char-width}. However, Emacs can render other types of things, +like text that contains images and using proportional fonts, and the +@code{pixel-fill-region} exists to handle that. It fills the region +of text between @var{start} and @var{end} at pixel granularity, so +text using variable-pitch fonts or several different fonts looks +filled regardless of different character sizes. The argument +@var{pixel-width} specifies the maximum pixel width a line is allowed +to have after filling; it is the pixel-resolution equivalent of the +@code{fill-column} in @code{fill-region}. For instance, this Lisp +snippet will insert text using a proportional font, and then fill this +to be no wider than 300 pixels: + +@lisp +(insert (propertize + "This is a sentence that's ends here." + 'face 'variable-pitch)) +(pixel-fill-region (point) (point-max) 300) +@end lisp + +If @var{start} isn't at the start of a line, the horizontal position +of @var{start}, converted to pixel units, will be used as the +indentation prefix on subsequent lines. + +@findex pixel-fill-width +The @code{pixel-fill-width} helper function can be used to compute the +pixel width to use. If given no arguments, it'll return a value +slightly less than the width of the current window. The first +optional value, @var{columns}, specifies the number of columns using +the standard, monospaced fonts, e.g. @code{fill-column}. The second +optional value is the window to use. You'd typically use it like +this: + +@lisp +(pixel-fill-region + start end (pixel-fill-width fill-column)) +@end lisp +@end defun + @deffn Command fill-individual-paragraphs start end &optional justify citation-regexp This command fills each paragraph in the region according to its individual fill prefix. Thus, if the lines of a paragraph were indented @@ -2915,6 +2984,12 @@ character after position @var{pos} in @var{object} (a buffer or string). The argument @var{object} is optional and defaults to the current buffer. +If @var{position} is at the end of @var{object}, the value is +@code{nil}, but note that buffer narrowing does not affect the value. +That is, if @var{object} is a buffer or @code{nil}, and the buffer is +narrowed and @var{position} is at the end of the narrowed buffer, the +result may be non-@code{nil}. + If there is no @var{prop} property strictly speaking, but the character has a property category that is a symbol, then @code{get-text-property} returns the @var{prop} property of that symbol. @@ -2967,6 +3042,12 @@ properties take precedence over this variable. This function returns the entire property list of the character at @var{position} in the string or buffer @var{object}. If @var{object} is @code{nil}, it defaults to the current buffer. + +If @var{position} is at the end of @var{object}, the value is +@code{nil}, but note that buffer narrowing does not affect the value. +That is, if @var{object} is a buffer or @code{nil}, and the buffer is +narrowed and @var{position} is at the end of the narrowed buffer, the +result may be non-@code{nil}. @end defun @defvar default-text-properties @@ -3399,7 +3480,7 @@ This will give you a list of all those URLs. @end defun @defun text-property-search-backward prop &optional value predicate not-current -This is just like @code{text-property-search-backward}, but searches +This is just like @code{text-property-search-forward}, but searches backward instead. Point is placed at the beginning of the matched region instead of the end, though. @end defun @@ -3487,16 +3568,30 @@ special modes that implement their own highlighting. @item mouse-face @kindex mouse-face @r{(text property)} -This property is used instead of @code{face} when the mouse is on or -near the character. For this purpose, ``near'' means that all text -between the character and where the mouse is have the same -@code{mouse-face} property value. +This property is used instead of @code{face} when the mouse pointer +hovers over the text which has this property. When this happens, the +entire stretch of text that has the same @code{mouse-face} property +value, not just the character under the mouse, is highlighted. Emacs ignores all face attributes from the @code{mouse-face} property that alter the text size (e.g., @code{:height}, @code{:weight}, and @code{:slant}). Those attributes are always the same as for the unhighlighted text. +@item cursor-face +@kindex cursor-face @r{(text property)} +@findex cursor-face-highlight-mode +@vindex cursor-face-highlight-nonselected-window +This property is similar to @code{mouse-face}, but it is used when +point (not the mouse) is inside text that has this property. The +highlighting happens only if the mode +@code{cursor-face-highlight-mode} is enabled. When the variable +@code{cursor-face-highlight-nonselected-window} is non-@code{nil}, the +text with this face is highlighted even if the window is not selected, +similarly to what @code{highlight-nonselected-windows} does for the +region (@pxref{Mark,, The Mark and the Region, emacs, The GNU Emacs +Manual}). + @item fontified @kindex fontified @r{(text property)} This property says whether the text is ready for display. If @@ -3610,6 +3705,11 @@ edited even in read-only buffers. @xref{Read Only Buffers}. A non-@code{nil} @code{invisible} property can make a character invisible on the screen. @xref{Invisible Text}, for details. +@kindex inhibit-isearch @r{(text property)} +@item inhibit-isearch +A non-@code{nil} @code{inhibit-isearch} property will make isearch +skip the text. + @item intangible @kindex intangible @r{(text property)} If a group of consecutive characters have equal and non-@code{nil} @@ -3635,9 +3735,20 @@ property is obsolete; use the @code{cursor-intangible} property instead. @item cursor-intangible @kindex cursor-intangible @r{(text property)} @findex cursor-intangible-mode +@cindex rear-nonsticky, and cursor-intangible property When the minor mode @code{cursor-intangible-mode} is turned on, point is moved away from any position that has a non-@code{nil} @code{cursor-intangible} property, just before redisplay happens. +Note that ``stickiness'' of the property (@pxref{Sticky Properties}) +is taken into account when computing allowed cursor positions, so (for +instance) to insert a stretch of five @samp{x} characters into which +the cursor can't enter, you should do something like: + +@lisp +(insert + (propertize "xxxx" 'cursor-intangible t) + (propertize "x" 'cursor-intangible t 'rear-nonsticky t)) +@end lisp @vindex cursor-sensor-inhibit When the variable @code{cursor-sensor-inhibit} is non-@code{nil}, the @@ -3944,6 +4055,8 @@ of the kill ring. To insert with inheritance, use the special primitives described in this section. Self-inserting characters inherit properties because they work using these primitives. +@cindex front-sticky text property +@cindex rear-nonsticky text property When you do insertion with inheritance, @emph{which} properties are inherited, and from where, depends on which properties are @dfn{sticky}. Insertion after a character inherits those of its properties that are @@ -4176,7 +4289,7 @@ position. The action code is always @code{t}. For example, here is how Info mode handles @key{mouse-1}: @smallexample -(define-key Info-mode-map [follow-link] 'mouse-face) +(keymap-set Info-mode-map "<follow-link>" 'mouse-face) @end smallexample @item a function @@ -4189,9 +4302,9 @@ For example, here is how pcvs enables @kbd{mouse-1} to follow links on file names only: @smallexample -(define-key map [follow-link] - (lambda (pos) - (eq (get-char-property pos 'face) 'cvs-filename-face))) +(keymap-set map "<follow-link>" + (lambda (pos) + (eq (get-char-property pos 'face) 'cvs-filename-face))) @end smallexample @item anything else @@ -4723,9 +4836,8 @@ converting to and from this code. This function converts the region from @var{beg} to @var{end} into base 64 code. It returns the length of the encoded text. An error is signaled if a character in the region is multibyte, i.e., in a -multibyte buffer the region must contain only characters from the -charsets @code{ascii}, @code{eight-bit-control} and -@code{eight-bit-graphic}. +multibyte buffer the region must contain only ASCII characters or raw +bytes. Normally, this function inserts newline characters into the encoded text, to avoid overlong lines. However, if the optional argument @@ -4874,6 +4986,92 @@ It should be somewhat more efficient on larger buffers than @c according to what we find useful. @end defun +@node Suspicious Text +@section Suspicious Text +@cindex suspicious text +@cindex insecure text +@cindex security vulnerabilities in text + + Emacs can display text from many external sources, like email and Web +sites. Attackers may attempt to confuse the user reading this text by +using obfuscated @acronym{URL}s or email addresses, and tricking the +user into visiting a web page they didn't intend to visit, or sending +an email to the wrong address. + +This usually involves using characters from scripts that visually look +like @acronym{ASCII} characters (i.e., are homoglyphs), but there are +also other techniques used, like using bidirectional overrides, or +having an @acronym{HTML} link text that says one thing, while the +underlying @acronym{URL} points somewhere else. + +@cindex suspicious text strings +To help identify these @dfn{suspicious text strings}, Emacs provides a +library to do a number of checks on text. (See +@url{https://www.unicode.org/reports/tr39/, UTS #39: Unicode Security +Mechanisms} for the rationale behind the checks that are available and +more details about them.) Packages that present data that might be +suspicious should use this library to flag suspicious text on display. + +@vindex textsec-check +@defun textsec-suspicious-p object type +This function is the high-level interface function that packages +should use. It respects the @code{textsec-check} user option, which +allows the user to disable the checks. + +This function checks @var{object} (whose data type depends on +@var{type}) to see if it looks suspicious when interpreted as a thing +of @var{type}. The available types and the corresponding @var{object} +data types are: + +@table @code +@item domain +Check whether a domain (e.g., @samp{www.gnu.org} looks suspicious. +@var{object} should be a string, the domain name. + +@item url +Check whether an @acronym{URL} (e.g., @samp{http://gnu.org/foo/bar}) +looks suspicious. @var{object} should be a string, the @acronym{URL} +to check. + +@item link +Check whether an @acronym{HTML} link (e.g., @samp{<a +href='http://gnu.org'>fsf.org</a>} looks suspicious. In this case, +@var{object} should be a @code{cons} cell where the @code{car} is the +@acronym{URL} string, and the @code{cdr} is the link text. The link +is deemed suspicious if the link text contains a domain name, and that +domain name points to something other than the @acronym{URL}. + +@item email-address +Check whether an email address (e.g., @samp{foo@@example.org}) looks +suspicious. @var{object} should be a string. + +@item local-address +Check whether the local part of an email address (the bit before the +@samp{@@} sign) looks suspicious. @var{object} should be a string. + +@item name +Check whether a name (used in an email address header) looks +suspicious. @var{object} should be a string. + +@item email-address-header +Check whether a full RFC2822 email address header (e.g., +@samp{=?utf-8?Q?=C3=81?= <foo@@example.com>}) looks suspicious. +@var{object} should be a string. +@end table + +If @var{object} is suspicious, this function returns a string that +explains why it is suspicious. If @var{object} is not suspicious, the +function returns @code{nil}. +@end defun + +@vindex textsec-suspicious@r{ (face)} +If the text is suspicious, the application should mark the suspicious +text with the @code{textsec-suspicious} face, and make the explanation +returned by @code{textsec-suspicious-p} available to the user in some way +(for example, in a tooltip). The application might also prompt the +user for confirmation before taking any action on a suspicious string +(like sending an email to a suspicious email address). + @node GnuTLS Cryptography @section GnuTLS Cryptography @cindex MD5 checksum @@ -5066,6 +5264,201 @@ On success, it returns a list of a binary string (the output) and the IV used. @end defun +@node Database +@section Database +@cindex database access, SQLite + + Emacs can be compiled with built-in support for accessing SQLite +databases. This section describes the facilities available for +accessing SQLite databases from Lisp programs. + +@defun sqlite-available-p +The function returns non-@code{nil} if built-in SQLite support is +available in this Emacs session. +@end defun + +When SQLite support is available, the following functions can be used. + +@cindex database object +@defun sqlite-open &optional file +This function opens @var{file} as an SQLite database file. If +@var{file} doesn't exist, a new database will be created and stored in +that file. If @var{file} is omitted or @code{nil}, a new in-memory +database is created instead. + +The return value is a @dfn{database object} that can be used as the +argument to most of the subsequent functions described below. +@end defun + +@defun sqlitep object +This predicate returns non-@code{nil} if @var{object} is an SQLite +database object. The database object returned by the +@code{sqlite-open} function satisfies this predicate. +@end defun + +@defun sqlite-close db +Close the database @var{db}. It's usually not necessary to call this +function explicitly---the database will automatically be closed if +Emacs shuts down or the database object is garbage collected. +@end defun + +@defun sqlite-execute db statement &optional values +Execute the @acronym{SQL} @var{statement}. For instance: + +@lisp +(sqlite-execute db "insert into foo values ('bar', 2)") +@end lisp + +If the optional @var{values} parameter is present, it should be either +a list or a vector of values to bind while executing the statement. +For instance: + +@lisp +(sqlite-execute db "insert into foo values (?, ?)" '("bar" 2)) +@end lisp + +This has exactly the same effect as the previous example, but is more +efficient and safer (because it doesn't involve any string parsing or +interpolation). + +@code{sqlite-execute} returns the number of affected rows. For +instance, an @samp{insert} statement will return @samp{1}, whereas an +@samp{update} statement may return zero or a higher number. + +Strings in SQLite are, by default, stored as @code{utf-8}, and +selecting a text column will decode the string using that charset. +Selecting a blob column will return the raw data without any decoding +(i.e., it will return a unibyte string containing the bytes as stored +in the database). Inserting binary data into blob columns, however, +requires some care, as @code{sqlite-execute} will, by default, +interpret all strings as @code{utf-8}. + +So if you have, for instance, @acronym{GIF} data in a unibyte string +called @var{gif}, you have to mark it specially to let +@code{sqlite-execute} know this: + +@lisp +(put-text-property 0 1 'coding-system 'binary gif) +(sqlite-execute db "insert into foo values (?, ?)" (list gif 2)) +@end lisp + +@end defun + +@defun sqlite-select db query &optional values result-type +Select some data from @var{db} and return them. For instance: + +@lisp +(sqlite-select db "select * from foo where key = 2") + @result{} (("bar" 2)) +@end lisp + +As with the @code{sqlite-execute}, you can optionally pass in a list +or a vector of values that will be bound before executing the select: + +@lisp +(sqlite-select db "select * from foo where key = ?" [2]) + @result{} (("bar" 2)) +@end lisp + +This is usually more efficient and safer than the method used by the +previous example. + +By default, this function returns a list of matching rows, where each +row is a list of column values. If @var{return-type} is @code{full}, +the names of the columns (as a list of strings) will be returned as +the first element in the return value. + +@cindex statement object +If @var{return-type} is @code{set}, this function will return a +@dfn{statement object} instead. This object can be examined by using +the @code{sqlite-next}, @code{sqlite-columns} and @code{sqlite-more-p} +functions. If the result set is small, it's often more convenient to +just return the data directly, but if the result set is large (or if +you won't be using all the data from the set), using the @code{set} +method will allocate a lot less memory, and is therefore more +memory-efficient. +@end defun + +@defun sqlite-next statement +This function returns the next row in the result set @var{statement}, +typically an object returned by @code{sqlite-select}. + +@lisp +(sqlite-next stmt) + @result{} ("bar" 2) +@end lisp +@end defun + +@defun sqlite-columns statement +This function returns the column names of the result set +@var{statement}, typically an object returned by @code{sqlite-select}. + +@lisp +(sqlite-columns stmt) + @result{} ("name" "issue") +@end lisp +@end defun + +@defun sqlite-more-p statement +This predicate says whether there is more data to be fetched from the +result set @var{statement}, typically an object returned by +@code{sqlite-select}. +@end defun + +@defun sqlite-finalize statement +If @var{statement} is not going to be used any more, calling this +function will free the resources used by @var{statement}. This is +usually not necessary---when the @var{statement} object is +garbage-collected, Emacs will automatically free its resources. +@end defun + +@defun sqlite-transaction db +Start a transaction in @var{db}. When in a transaction, other readers +of the database won't access the results until the transaction has +been committed by @code{sqlite-commit}. +@end defun + +@defun sqlite-commit db +End a transaction in @var{db} and write the data out to its file. +@end defun + +@defun sqlite-rollback db +End a transaction in @var{db} and discard any changes that have been +made by the transaction. +@end defun + +@defmac with-sqlite-transaction db body@dots{} +Like @code{progn} (@pxref{Sequencing}), but executes @var{body} with a +transaction held, and commits the transaction at the end. +@end defmac + +@defun sqlite-pragma db pragma +Execute @var{pragma} in @var{db}. A @dfn{pragma} is usually a command +that affects the database overall, instead of any particular table. +For instance, to make SQLite automatically garbage collect data that's +no longer needed, you can say: + +@lisp +(sqlite-pragma db "auto_vacuum = FULL") +@end lisp + +This function returns non-@code{nil} on success and @code{nil} if the +pragma failed. Many pragmas can only be issued when the database is +brand new and empty. +@end defun + +@defun sqlite-load-extension db module +Load the named extension @var{module} into the database @var{db}. +Extensions are usually shared-library files; on GNU and Unix systems, +they have the @file{.so} file-name extension. +@end defun + +@findex sqlite-mode-open-file +If you wish to list the contents of an SQLite file, you can use the +@code{sqlite-mode-open-file} command. This will pop to a buffer using +@code{sqlite-mode}, which allows you to examine (and alter) the +contents of an SQLite database. + @node Parsing HTML/XML @section Parsing HTML and XML @cindex parsing html @@ -5080,12 +5473,15 @@ available in this Emacs session. When libxml2 support is available, the following functions can be used to parse HTML or XML text into Lisp object trees. -@defun libxml-parse-html-region start end &optional base-url discard-comments +@defun libxml-parse-html-region &optional start end base-url discard-comments This function parses the text between @var{start} and @var{end} as HTML, and returns a list representing the HTML @dfn{parse tree}. It attempts to handle real-world HTML by robustly coping with syntax mistakes. +If @var{start} or @var{end} are @code{nil}, they default to the values +from @code{point-min} and @code{point-max}, respectively. + The optional argument @var{base-url}, if non-@code{nil}, should be a string specifying the base URL for relative URLs occurring in links. @@ -5131,7 +5527,7 @@ buffer. The argument @var{dom} should be a list as generated by @end defun @cindex parsing xml -@defun libxml-parse-xml-region start end &optional base-url discard-comments +@defun libxml-parse-xml-region &optional start end base-url discard-comments This function is the same as @code{libxml-parse-html-region}, except that it parses the text as XML rather than HTML (so it is stricter about syntax). diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index eddbbfe8b90..3a1f6de12b2 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -252,6 +252,13 @@ themselves; Lisp programmers find this disconcerting. Please put a copyright notice and copying permission notice on the file if you distribute copies. @xref{Library Headers}. +@item +For variables holding (or functions returning) a file or directory name, +avoid using @code{path} in its name, preferring @code{file}, +@code{file-name}, or @code{directory} instead, since Emacs follows the +GNU convention to use the term @emph{path} only for search paths, +which are lists of directory names. + @end itemize @node Key Binding Conventions @@ -682,6 +689,18 @@ line. This looks nice in the source code, but looks bizarre when users view the documentation. Remember that the indentation before the starting double-quote is not part of the string! +@item +When documentation should display an ASCII apostrophe or grave accent, +use @samp{\\='} or @samp{\\=`} in the documentation string literal so +that the character is displayed as-is. + +@item +In documentation strings, do not quote expressions that are not Lisp symbols, +as these expressions can stand for themselves. For example, write +@samp{Return the list (NAME TYPE RANGE) ...}@: instead of +@samp{Return the list `(NAME TYPE RANGE)' ...}@: or +@samp{Return the list \\='(NAME TYPE RANGE) ...}. + @anchor{Docstring hyperlinks} @item @cindex curly quotes @@ -700,7 +719,11 @@ Note that when Emacs displays these doc strings, Emacs will usually display @samp{`} (grave accent) as @samp{‘} (left single quotation mark) and @samp{'} (apostrophe) as @samp{’} (right single quotation mark), if the display supports displaying these characters. -@xref{Keys in Documentation}. +@xref{Keys in Documentation}. (Some previous versions of this section +recommended using the non-@acronym{ASCII} single quotation marks +directly in doc strings, but this is now discouraged, since that leads +to broken help string displays on terminals that don't support +displaying those characters.) @cindex hyperlinks in documentation strings Help mode automatically creates a hyperlink when a documentation string diff --git a/doc/lispref/two-volume.make b/doc/lispref/two-volume.make index aaad040dc08..f401d4a1f2a 100644 --- a/doc/lispref/two-volume.make +++ b/doc/lispref/two-volume.make @@ -35,7 +35,7 @@ vol1.pdf: elisp1med-fns-ready elisp1med-aux-ready elisp1med-toc-ready $(tex1) # vol2.pdf: elisp2med-fns-ready elisp2med-aux-ready elisp2med-toc-ready - @echo "Final TeX run for volume 2..." + $(info Final TeX run for volume 2...) cp elisp2med-toc-ready elisp2-toc-ready.toc cp elisp2med-fns-ready vol2.fns cp elisp2med-aux-ready vol2.aux @@ -123,7 +123,7 @@ elisp1med-init: elisp1-fns-ready elisp1-aux-ready elisp1init-toc-ready $(texinfo mv vol1.toc elisp1med-toc # elisp2med-init: elisp2-fns-ready elisp2-aux-ready elisp2init-toc-ready $(texinfodir)/texinfo.tex - @echo "Final TeX run for volume 2..." + $(info Final TeX run for volume 2...) cp elisp2init-toc-ready elisp2-toc-ready.toc cp elisp2-fns-ready vol2.fns cp elisp2-aux-ready vol2.aux @@ -211,7 +211,7 @@ elisp1-init: elisp.texi touch $@ # elisp2-init: elisp.texi - @echo "Initial TeX run for volume 2..." + $(info Initial TeX run for volume 2...) rm -f vol2.aux vol2.toc $(tex2) texindex vol2.?? diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index b9f50ecc6ac..975e945b343 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -44,6 +44,7 @@ representing the variable. * Variables with Restricted Values:: Non-constant variables whose value can @emph{not} be an arbitrary Lisp object. * Generalized Variables:: Extending the concept of variables. +* Multisession Variables:: Variables that survive restarting Emacs. @end menu @node Global Variables @@ -363,7 +364,7 @@ where you are in Emacs. @cindex evaluation error @cindex infinite recursion This variable defines the limit on the total number of local variable -bindings and @code{unwind-protect} cleanups (see @ref{Cleanups,, +bindings and @code{unwind-protect} cleanups (@pxref{Cleanups,, Cleaning Up from Nonlocal Exits}) that are allowed before Emacs signals an error (with data @code{"Variable binding depth exceeds max-specpdl-size"}). @@ -373,7 +374,7 @@ that Lisp avoids infinite recursion on an ill-defined function. @code{max-lisp-eval-depth} provides another limit on depth of nesting. @xref{Definition of max-lisp-eval-depth,, Eval}. -The default value is 1600. Entry to the Lisp debugger increases the +The default value is 2500. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself has room to execute. @end defopt @@ -526,10 +527,11 @@ If @var{symbol} has a buffer-local binding in the current buffer, rather than the buffer-local binding. It sets the default value if the default value is void. @xref{Buffer-Local Variables}. -If @var{symbol} is already lexically bound (e.g., if the @code{defvar} -form occurs in a @code{let} form with lexical binding enabled), then -@code{defvar} sets the dynamic value. The lexical binding remains in -effect until its binding construct exits. @xref{Variable Scoping}. +If @var{symbol} is already let bound (e.g., if the @code{defvar} +form occurs in a @code{let} form), then @code{defvar} sets the toplevel +default value, like @code{set-default-toplevel-value}. +The let binding remains in effect until its binding construct exits. +@xref{Variable Scoping}. @cindex @code{eval-defun}, and @code{defvar} forms @cindex @code{eval-last-sexp}, and @code{defvar} forms @@ -686,7 +688,7 @@ entire computation of the value into the @code{defvar}, like this: @example (defvar my-mode-map (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) + (keymap-set map "C-c C-a" 'my-command) @dots{} map) @var{docstring}) @@ -702,25 +704,6 @@ important if the user has run hooks to alter part of the contents (such as, to rebind keys). Third, evaluating the @code{defvar} form with @kbd{C-M-x} will reinitialize the map completely. - Putting so much code in the @code{defvar} form has one disadvantage: -it puts the documentation string far away from the line which names the -variable. Here's a safe way to avoid that: - -@example -(defvar my-mode-map nil - @var{docstring}) -(unless my-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) - @dots{} - (setq my-mode-map map))) -@end example - -@noindent -This has all the same advantages as putting the initialization inside -the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on -each form, if you do want to reinitialize the variable. - @node Accessing Variables @section Accessing Variable Values @@ -879,6 +862,40 @@ error is signaled. @end example @end defun +@defmac setopt [symbol form]@dots{} +This is like @code{setq} (see above), but meant for user options. +This macro uses the Customize machinery to set the variable(s). In +particular, @code{setopt} will run the setter function associated with +the variable. For instance, if you have: + +@example +@group +(defcustom my-var 1 + "My var." + :type 'number + :set (lambda (var val) + (set-default var val) + (message "We set %s to %s" var val))) +@end group +@end example + +@noindent +then the following, in addition to setting @code{my-var} to @samp{2}, +will also issue a message: + +@example +(setopt my-var 2) +@end example + +@code{setopt} also checks whether the value is valid for the user +option. For instance, using @code{setopt} to set a user option +defined with a @code{number} type to a string will signal an error. + +The @code{setopt} macro can be used on regular, non-user option +variables, but is much less efficient than @code{setq}. The main use +case for this macro is setting user options in the user's init file. +@end defmac + @node Watching Variables @section Running a function when a variable is changed. @cindex variable watchpoints @@ -1695,12 +1712,14 @@ buffer-local variables interactively. @end deffn @cindex local variables, killed by major mode -@defun kill-all-local-variables +@defun kill-all-local-variables &optional kill-permanent This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as permanent and local -hook functions that have a non-@code{nil} @code{permanent-local-hook} -property (@pxref{Setting Hooks}). As a result, the buffer will see -the default values of most variables. +current buffer. As a result, the buffer will see the default values +of most variables. By default, for variables marked as permanent and +local hook functions that have a non-@code{nil} +@code{permanent-local-hook} property (@pxref{Setting Hooks}) won't be +killed, but if the optional @var{kill-permanent} argument is +non-@code{nil}, even these variables will be killed. This function also resets certain other information pertaining to the buffer: it sets the local keymap to @code{nil}, the syntax table to the @@ -2277,13 +2296,28 @@ list in @var{variables} is an alist of the form '((null-device . "/dev/null"))) @end group @end example + +@findex connection-local-get-profile-variables +If you want to append variable settings to an existing profile, you +could use the function @code{connection-local-get-profile-variables} +in order to retrieve the existing settings, like + +@example +@group +(connection-local-set-profile-variables + 'remote-bash + (append + (connection-local-get-profile-variables 'remote-bash) + '((shell-command-dont-erase-buffer . t)))) +@end group +@end example @end defun -@defvar connection-local-profile-alist +@deffn {User Option} connection-local-profile-alist This alist holds the connection profile symbols and the associated variable settings. It is updated by @code{connection-local-set-profile-variables}. -@end defvar +@end deffn @defun connection-local-set-profiles criteria &rest profiles This function assigns @var{profiles}, which are symbols, to all remote @@ -2337,11 +2371,11 @@ Therefore, the example above would be equivalent to defined by @code{connection-local-set-profile-variables}. @end defun -@defvar connection-local-criteria-alist +@deffn {User Option} connection-local-criteria-alist This alist contains connection criteria and their assigned profile names. The function @code{connection-local-set-profiles} updates this list. -@end defvar +@end deffn @defun hack-connection-local-variables criteria This function collects applicable connection-local variables @@ -2400,6 +2434,37 @@ are unwound. Example: @end example @end defmac +@defvar connection-local-default-application +The default application, a symbol, to be applied in +@code{with-connection-local-variables}. It defaults to @code{tramp}, +but in case you want to overwrite Tramp's settings temporarily, you +could let-bind it like + +@example +@group +(connection-local-set-profile-variables + 'my-remote-perl + '((perl-command-name . "/usr/local/bin/perl5") + (perl-command-switch . "-e %s"))) +@end group + +@group +(connection-local-set-profiles + '(:application 'my-app :protocol "ssh" :machine "remotehost") + 'my-remote-perl) +@end group + +@group +(let ((default-directory "/ssh:remotehost:/working/dir/") + (connection-local-default-application 'my-app)) + (with-connection-local-variables + do something useful)) +@end group +@end example + +This variable must not be changed globally. +@end defvar + @defvar enable-connection-local-variables If @code{nil}, connection-local variables are ignored. This variable shall be changed temporarily only in special modes. @@ -2614,17 +2679,46 @@ cdar nthcdr A call to any of the following Emacs-specific functions: @smallexample -alist-get process-get -frame-parameter process-sentinel -terminal-parameter window-buffer -keymap-parent window-display-table -match-data window-dedicated-p -overlay-get window-hscroll -overlay-start window-parameter -overlay-end window-point -process-buffer window-start -process-filter default-value +alist-get overlay-start +default-value overlay-get +face-background process-buffer +face-font process-filter +face-foreground process-get +face-stipple process-sentinel +face-underline-p terminal-parameter +file-modes window-buffer +frame-parameter window-dedicated-p +frame-parameters window-display-table +get-register window-hscroll +getenv window-parameter +keymap-parent window-point +match-data window-start +overlay-end @end smallexample + +@item +A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])}, +where @var{subplace} is itself a valid generalized variable whose +current value is a string, and where the value stored is also a +string. The new string is spliced into the specified part of the +destination string. For example: + +@example +(setq a (list "hello" "world")) + @result{} ("hello" "world") +(cadr a) + @result{} "world" +(substring (cadr a) 2 4) + @result{} "rl" +(setf (substring (cadr a) 2 4) "o") + @result{} "o" +(cadr a) + @result{} "wood" +a + @result{} ("hello" "wood") +@end example + +@c FIXME? Also 'eq'? (see gv.el) @end itemize @noindent @@ -2725,13 +2819,13 @@ implemented this way: (gv-define-expander substring (lambda (do place from &optional to) (gv-letplace (getter setter) place - (macroexp-let2* nil ((start from) (end to)) - (funcall do `(substring ,getter ,start ,end) + (macroexp-let2* (from to) + (funcall do `(substring ,getter ,from ,to) (lambda (v) - (macroexp-let2 nil v v + (macroexp-let2* (v) `(progn ,(funcall setter `(cl--set-substring - ,getter ,start ,end ,v)) + ,getter ,from ,to ,v)) ,v)))))))) @end example @end defmac @@ -2744,7 +2838,7 @@ of Common Lisp could be implemented this way: @example (defmacro incf (place &optional n) (gv-letplace (getter setter) place - (macroexp-let2 nil v (or n 1) + (macroexp-let2* ((v (or n 1))) (funcall setter `(+ ,v ,getter))))) @end example @@ -2757,6 +2851,16 @@ expression manipulating @var{place} via @var{getter} and @var{setter}. Consult the source file @file{gv.el} for more details. +@defun make-obsolete-generalized-variable obsolete-name current-name when +This function makes the byte compiler warn that the generalized +variable @var{obsolete-name} is obsolete. If @var{current-name} is a +symbol, then the warning message says to use @var{current-name} +instead of @var{obsolete-name}. If @var{current-name} is a string, +this is the message. @var{when} should be a string indicating when +the variable was first made obsolete (usually a version number +string). +@end defun + @cindex CL note---no @code{setf} functions @quotation @b{Common Lisp note:} Common Lisp defines another way to specify the @@ -2769,3 +2873,157 @@ form that has not already had an appropriate expansion defined. In Common Lisp, this is not an error since the function @code{(setf @var{func})} might be defined later. @end quotation + +@node Multisession Variables +@section Multisession Variables + +@cindex multisession variable + When you set a variable to a value and then close Emacs and restart +it, that value won't be automatically restored. Users usually set +normal variables in their startup files, or use Customize +(@pxref{Customization}) to set user options permanently, and various +packages have various files where they store the data (e.g., Gnus +stores this in @file{.newsrc.eld} and the URL library stores cookies +in @file{~/.emacs.d/url/cookies}). + +For things in between these two extremes (i.e., configuration which +goes in the startup file, and massive application state that goes into +separate files), Emacs provides a facility to replicate data between +sessions called @dfn{multisession variables}. (This facility may not +be available on all systems.) To give you an idea of how these are +meant to be used, here's a small example: + +@lisp +@group +(define-multisession-variable foo-var 0) +(defun my-adder (num) + (interactive "nAdd number: ") + (setf (multisession-value foo) + (+ (multisession-value foo) num)) + (message "The new number is: %s" (multisession-value foo))) +@end group +@end lisp + +@noindent +This defines the variable @code{foo-var} and binds it to a special +multisession object which is initialized with the value @samp{0} (if +the variable doesn't already exist from a previous session). The +@code{my-adder} command queries the user for a number, adds this to +the old (possibly saved value), and then saves the new value. + +This facility isn't meant to be used for huge data structures, but +should be performant for most values. + +@defmac define-multisession-variable name initial-value &optional doc &rest args +This macro defines @var{name} as a multisession variable, and gives it +the @var{initial-value} if this variable hasn't been assigned a value +earlier. @var{doc} is the doc string, and several keyword arguments can +be used in @var{args}: + +@table @code +@item :package @var{package-symbol} +This keyword says that a multisession variable belongs to the package +specified by @var{package-symbol}. The combination of +@var{package-symbol} and @var{name} has to be unique. If +@var{package-symbol} isn't given, this will default to the first +``segment'' of the @var{name} symbol's name, which is the part of its +name up to and excluding the first @samp{-}. For instance, if +@var{name} is @code{foo-var} and @var{package-symbol} isn't given, +@var{package-symbol} will default to @code{foo}. + +@cindex synchronized multisession variables +@item :synchronized @var{bool} +Multisession variables can be @dfn{synchronized} if @var{bool} is +non-@code{nil}. This means that if there're two concurrent Emacs +instances running, and the other Emacs changes the multisession +variable @code{foo-var}, the current Emacs instance will retrieve that +modified data when accessing the value. If @var{synchronized} is +@code{nil} or missing, this won't happen, and the values in all +Emacs sessions using the variable will be independent of each other. + +@item :storage @var{storage} +Use the specified @var{storage} method. This can be either +@code{sqlite} (in Emacs compiled with SQLite support) or @code{files}. +If not given, this defaults to the value of the +@code{multisession-storage} variable, described below. +@end table +@end defmac + +@defun multisession-value variable +This function returns the current value of @var{variable}. If this +variable hasn't been accessed before in this Emacs session, or if it's +changed externally, it will be read in from external storage. If not, +the current value in this session is returned as is. It is an error +to call this function for a @var{variable} that is not a multisession +variable. + +Values retrieved via @code{multisession-value} may or may not be +@code{eq} to each other, but they will always be @code{equal}. + +This is a generalized variable (@pxref{Generalized Variables}), so the +way to update such a variable is to say, for instance: + +@lisp +(setf (multisession-value foo-bar) 'zot) +@end lisp + +Only Emacs Lisp values that have a readable print syntax +(@pxref{Printed Representation}) can be saved this way. + +If the multisession variable is synchronized, setting it may update +the value first. For instance: + +@lisp +(cl-incf (multisession-value foo-bar)) +@end lisp + +This first checks whether the value has changed in a different +Emacs instance, retrieves that value, and then adds 1 to that value and +stores it. But note that this is done without locking, so if many +instances are updating the value at the same time, it's unpredictable +which instance ``wins''. +@end defun + +@defun multisession-delete object +This function deletes @var{object} and its value from its persistent +storage. +@end defun + +@c FIXME: this lacks the documentation of the form of the arguments. +@defun make-multisession +You can also make persistent values that aren't tied to a specific +variable, but are tied to an explicit package and key. + +@example +(setq foo (make-multisession :package "mail" + :key "friends")) +(setf (multisession-value foo) 'everybody) +@end example + +This supports the same keywords as +@code{define-multisession-variable}, but also supports a +@code{:initial-value} keyword, which specifies the default value. +@end defun + +@defopt multisession-storage +This variable controls how the multisession variables are stored. It +value defaults to @code{files}, which means that the values are stored +in a one-file-per-variable structure inside the directory specified by +@code{multisession-directory}. If this value is @code{sqlite} +instead, the values are stored in an SQLite database; this is only +available if Emacs was built with SQLite support. +@end defopt + +@defopt multisession-directory +The multisession variables are stored under this directory, which +defaults to @file{multisession/} subdirectory of the +@code{user-emacs-directory}, which is typically +@file{~/.emacs.d/multisession/}. +@end defopt + +@findex multisession-edit-mode +@deffn Command list-multisession-values +This command pops up a buffer listing all the multisession variables, +and enters a special mode @code{multisession-edit-mode} which allows +you to delete them and edit their values. +@end deffn diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 597e31fe85e..33d0150a939 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -829,14 +829,18 @@ This function returns the height, in lines, of the body of window @var{window}. If @var{window} is omitted or @code{nil}, it defaults to the selected window; otherwise it must be a live window. -If the optional argument @var{pixelwise} is non-@code{nil}, this -function returns the body height of @var{window} counted in pixels. +The optional argument @var{pixelwise} defines the units to use for the +height. If @code{nil}, return the body height of @var{window} in +characters, rounded down to the nearest integer, if necessary. This +means that if a line at the bottom of the text area is only partially +visible, that line is not counted. It also means that the height of a +window's body can never exceed its total height as returned by +@code{window-total-height}. -If @var{pixelwise} is @code{nil}, the return value is rounded down to -the nearest integer, if necessary. This means that if a line at the -bottom of the text area is only partially visible, that line is not -counted. It also means that the height of a window's body can never -exceed its total height as returned by @code{window-total-height}. +If @var{pixelwise} is @code{remap} and the default face is remapped +(@pxref{Face Remapping}), use the remapped face to determine the +character height. For any other non-@code{nil} value, return the +height in pixels. @end defun @cindex window body width @@ -857,14 +861,18 @@ This function returns the width, in columns, of the body of window @var{window}. If @var{window} is omitted or @code{nil}, it defaults to the selected window; otherwise it must be a live window. -If the optional argument @var{pixelwise} is non-@code{nil}, this -function returns the body width of @var{window} in units of pixels. +The optional argument @var{pixelwise} defines the units to use for the +width. If @code{nil}, return the body width of @var{window} in +characters, rounded down to the nearest integer, if necessary. This +means that if a column on the right of the text area is only partially +visible, that column is not counted. It also means that the width of +a window's body can never exceed its total width as returned by +@code{window-total-width}. -If @var{pixelwise} is @code{nil}, the return value is rounded down to -the nearest integer, if necessary. This means that if a column on the -right of the text area is only partially visible, that column is not -counted. It also means that the width of a window's body can never -exceed its total width as returned by @code{window-total-width}. +If @var{pixelwise} is @code{remap} and the default face is remapped +(@pxref{Face Remapping}), use the remapped face to determine the +character width. For any other non-@code{nil} value, return the width +in pixels. @end defun @cindex window body size @@ -1150,11 +1158,13 @@ frame to its buffer using the command @code{fit-frame-to-buffer}. This command adjusts the size of @var{frame} to display the contents of its buffer exactly. @var{frame} can be any live frame and defaults to the selected one. Fitting is done only if @var{frame}'s root window is -live. The arguments @var{max-height}, @var{min-height}, @var{max-width} -and @var{min-width} specify bounds on the new total size of -@var{frame}'s root window. @var{min-height} and @var{min-width} default -to the values of @code{window-min-height} and @code{window-min-width} -respectively. +live. + +The arguments @var{max-height}, @var{min-height}, @var{max-width} and +@var{min-width}, if non-@code{nil}, specify bounds on the new body size +of @var{frame}'s root window. A non-@code{nil} value specified by any +of these arguments overrides the corresponding value specified by +the option @code{fit-frame-to-buffer-sizes} described below. If the optional argument @var{only} is @code{vertically}, this function may resize the frame vertically only. If @var{only} is @@ -1179,10 +1189,10 @@ here can be overridden for a specific frame by that frame's @defopt fit-frame-to-buffer-sizes This option specifies size boundaries for @code{fit-frame-to-buffer}. -It specifies the total maximum and minimum lines and maximum and minimum -columns of the root window of any frame that shall be fit to its buffer. -If any of these values is non-@code{nil}, it overrides the corresponding -argument of @code{fit-frame-to-buffer}. +It specifies the maximum and minimum lines and maximum and minimum +columns of the root window's body of any frame that shall be fit to its +buffer. Any value this option specifies will be overridden by the +corresponding argument of @code{fit-frame-to-buffer}, if non-@code{nil}. @end defopt @deffn Command shrink-window-if-larger-than-buffer &optional window @@ -1462,20 +1472,36 @@ the new root window. For interactive use, Emacs provides two commands which always split the selected window. These call @code{split-window} internally. -@deffn Command split-window-right &optional size -This function splits the selected window into two side-by-side -windows, putting the selected window on the left. If @var{size} is -positive, the left window gets @var{size} columns; if @var{size} is +@deffn Command split-window-right &optional size window-to-split +This function splits the window @var{window-to-split} into two +side-by-side windows, putting @var{window-to-split} on the left. +@var{window-to-split} defaults to the selected window. If @var{size} +is positive, the left window gets @var{size} columns; if @var{size} is negative, the right window gets @minus{}@var{size} columns. @end deffn -@deffn Command split-window-below &optional size -This function splits the selected window into two windows, one above -the other, leaving the upper window selected. If @var{size} is -positive, the upper window gets @var{size} lines; if @var{size} is +@deffn Command split-window-below &optional size window-to-split +This function splits the window @var{window-to-split} into two +windows, one above the other, leaving the upper window selected. +@var{window-to-split} defaults to the selected window. If @var{size} +is positive, the upper window gets @var{size} lines; if @var{size} is negative, the lower window gets @minus{}@var{size} lines. @end deffn +@deffn Command split-root-window-below &optional size +This function splits the whole frame in two. The current window +configuration is retained on the top, and a new window is created +below, taking up the whole width of the frame. @var{size} is treated +as by @code{split-window-below}. +@end deffn + +@deffn Command split-root-window-right &optional size +This function splits the whole frame in two. The current window +configuration is retained on the left, and a new window is created on +the right, taking up the whole height of the frame. @var{size} is treated +as by @code{split-window-right}. +@end deffn + @defopt split-window-keep-point If the value of this variable is non-@code{nil} (the default), @code{split-window-below} behaves as described above. @@ -2596,13 +2622,11 @@ default value is an empty display action, i.e., @w{@code{(nil . nil)}}. @defopt display-buffer-alist The value of this option is an alist mapping conditions to display -actions. Each condition may be either a regular expression matching a -buffer name or a function that takes two arguments: a buffer name and -the @var{action} argument passed to @code{display-buffer}. If either -the name of the buffer passed to @code{display-buffer} matches a -regular expression in this alist, or the function specified by a -condition returns non-@code{nil}, then @code{display-buffer} uses the -corresponding display action to display the buffer. +actions. Each condition is passed to @code{buffer-match-p}, along +with the buffer name and the @var{action} argument passed to +@code{display-buffer}. If it returns a non-nil value, then +@code{display-buffer} uses the corresponding display action to display +the buffer. @end defopt @defopt display-buffer-base-action @@ -2838,6 +2862,11 @@ the function specified in @code{pop-up-frame-function} the newly created frame's parameters. @end defun +@defun display-buffer-full-frame buffer alist +This function displays the buffer on the current frame, deleting all +other windows so that it takes up the full frame. +@end defun + @defun display-buffer-in-child-frame buffer alist This function tries to display @var{buffer} in a child frame (@pxref{Child Frames}) of the selected frame, either reusing an @@ -2968,13 +2997,14 @@ follows: @code{nil} means consider only windows on the selected frame. (Actually, the last frame used that is not a minibuffer-only frame.) @item -@code{t} means consider windows on all frames. -@item @code{visible} means consider windows on all visible frames. @item 0 means consider windows on all visible or iconified frames. @item A frame means consider windows on that frame only. +@item +@code{t} means consider windows on all frames. (Note that this value +is rarely the right thing to use---it might also return a tooltip frame.) @end itemize Note that the meaning of @code{nil} differs slightly from that of the @@ -3038,6 +3068,11 @@ desired total height with respect to the total height of its frame's root window. @item +A cons cell whose @sc{car} is @code{body-lines} and whose @sc{cdr} is an +integer that specifies the height of the chosen window's body in frame +lines. + +@item If the value specifies a function, that function is called with one argument---the chosen window. The function is supposed to adjust the height of the window; its return value is ignored. Suitable functions @@ -3071,16 +3106,47 @@ desired total width with respect to the total width of the frame's root window. @item +A cons cell whose @sc{car} is @code{body-columns} and whose @sc{cdr} is +an integer that specifies the width of the chosen window's body in frame +columns. + +@item If the value specifies a function, that function is called with one argument---the chosen window. The function is supposed to adjust the width of the window; its return value is ignored. @end itemize -By convention, the width of the chosen window is adjusted only if the -window is part of a horizontal combination (@pxref{Windows and -Frames}) to avoid changing the width of other, unrelated windows. -Also, this entry should be processed under only certain conditions -which are specified right below this list. +@vindex window-size@r{, a buffer display action alist entry} +@item window-size +This entry is a combination of the two preceding ones and can be used to +adjust the chosen window's height @emph{and} width. Since windows can +be resized in one direction only without affecting other windows, +@code{window-size} is effective only to set up the size of a window +appearing alone on a frame. The value can be one of the following: + +@itemize @bullet +@item +@code{nil} means to leave the size of the chosen window alone. + +@item +A cons cell of two integers specifies the desired total width and height +of the chosen window in lines and columns. It's effect is to adjust the +size of the frame accordingly. + +@item +A cons cell whose @sc{car} equals @code{body-chars} and whose @sc{cdr} +is a cons cell of two integers---the desired body width and height of +the chosen window in frame columns and lines. It's effect is to adjust +the size of the frame accordingly. + +@item +If the value specifies a function, that function is called with one +argument---the chosen window. The function is supposed to adjust the +size of the window's frame; its return value is ignored. +@end itemize + +This entry should be processed under only certain conditions which are +specified right below this list. @vindex dedicated@r{, a buffer display action alist entry} @item dedicated @@ -3181,6 +3247,14 @@ the window was created earlier by @code{display-buffer} to show the buffer and never was used to show another buffer until it was reused by the current invocation of @code{display-buffer}. +If no @code{window-height}, @code{window-width} or @code{window-size} +entry was specified, the window may still be resized automatically when +the buffer is temporary and @code{temp-buffer-resize-mode} has been +enabled, @ref{Temporary Displays}. In that case, the @sc{cdr} of a +@code{window-height}, @code{window-width} or @code{window-size} entry +can be used to inhibit or override the default behavior of +@code{temp-buffer-resize-mode} for specific buffers or invocations of +@code{display-buffer}. @node Choosing Window Options @subsection Additional Options for Displaying Buffers @@ -3248,6 +3322,13 @@ window has at least that many columns. If the value is @code{nil}, that means not to split this way. @end defopt +@defopt display-buffer-avoid-small-windows +If non-@code{nil}, this should be a number. Windows that have fewer +lines than that will be avoided when choosing an existing window. The +value is interpreted in units of the frame's canonical line height, +like @code{window-total-height} does (@pxref{Window Sizes}). +@end defopt + @defopt even-window-sizes This variable, if non-@code{nil}, causes @code{display-buffer} to even window sizes whenever it reuses an existing window, and that window is @@ -3333,8 +3414,8 @@ functions it should try instead as, for example: @example @group -(customize-set-variable - 'display-buffer-base-action +(setopt + display-buffer-base-action '((display-buffer-reuse-window display-buffer-same-window display-buffer-in-previous-window display-buffer-use-some-window))) @@ -3348,8 +3429,8 @@ Instead of customizing this variable to @code{t}, customize @example @group -(customize-set-variable - 'display-buffer-base-action +(setopt + display-buffer-base-action '((display-buffer-reuse-window display-buffer-pop-up-frame) (reusable-frames . 0))) @end group @@ -3365,8 +3446,8 @@ specifying the action function @code{display-buffer-same-window}. @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist (cons '("\\*foo\\*" (display-buffer-same-window)) display-buffer-alist)) @end group @@ -3439,8 +3520,8 @@ another frame. Such a user might provide the following customization: @example @group -(customize-set-variable - 'display-buffer-base-action +(setopt + display-buffer-base-action '((display-buffer-reuse-window display-buffer-pop-up-frame) (reusable-frames . 0))) @end group @@ -3485,8 +3566,8 @@ In fact, this: @example @group -(customize-set-variable - 'display-buffer-base-action +(setopt + display-buffer-base-action '(display-buffer-pop-up-frame (reusable-frames . 0))) @end group @end example @@ -3542,8 +3623,8 @@ by customizing the option @code{display-buffer-alist} as follows: @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist '(("\\*foo\\*" (display-buffer-reuse-window display-buffer-pop-up-frame)))) @end group @@ -3565,8 +3646,8 @@ we would have to specify that separately, however: @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist '(("\\*foo\\*" (display-buffer-reuse-window display-buffer-pop-up-frame) (reusable-frames . visible)))) @@ -3672,8 +3753,8 @@ written that as @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist '(("\\*foo\\*" (display-buffer-reuse-window display-buffer-pop-up-frame) (inhibit-same-window . t) @@ -3816,8 +3897,8 @@ follows: @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist '(("\\*foo\\*" (display-buffer-below-selected display-buffer-at-bottom) (inhibit-same-window . t) @@ -3830,8 +3911,8 @@ To add a customization for a second buffer one would then write: @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist '(("\\*foo\\*" (display-buffer-below-selected display-buffer-at-bottom) (inhibit-same-window . t) @@ -4121,6 +4202,13 @@ ignore this option, for example, when there is only one buffer left these functions can switch to. @end defopt +@defopt switch-to-prev-buffer-skip-regexp +This user option should be either a regular expression or a list of +regular expressions. Buffers whose names match one of those regular +expressions will be ignored by @code{switch-to-prev-buffer} and +@code{switch-to-next-buffer} (except when there's no other buffer to +switch to). +@end defopt @node Dedicated Windows @section Dedicated Windows @@ -5456,7 +5544,7 @@ pixels, rather than in units of the normal line height. @end example @end defun -@defun set-window-vscroll window lines &optional pixels-p +@defun set-window-vscroll window lines &optional pixels-p preserve-vscroll-p This function sets @var{window}'s vertical scroll position to @var{lines}. If @var{window} is @code{nil}, the selected window is used. The argument @var{lines} should be zero or positive; if not, it @@ -5478,6 +5566,12 @@ The return value is the result of this rounding. If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of pixels. In this case, the return value is @var{lines}. + +Normally, the vscroll does not take effect on windows that aren't the +@code{minibuffer-scroll-window} or the selected window when the +mini-window is resized (@pxref{Minibuffer Windows}). This ``frozen'' +behavior is disabled when the @var{preserve-vscroll-p} parameter is +non-@code{nil}, which means to set the vscroll as usual. @end defun @defvar auto-window-vscroll @@ -6071,11 +6165,10 @@ configuration on the current frame. This function returns @code{t} if @var{object} is a window configuration. @end defun -@defun compare-window-configurations config1 config2 -This function compares two window configurations as regards the -structure of windows, but ignores the values of point and the -saved scrolling positions---it can return @code{t} even if those -aspects differ. +@defun window-configuration-equal-p config1 config2 +This function says whether two window configurations have the same +window layout, but ignores the values of point and the saved scrolling +positions---it can return @code{t} even if those aspects differ. @end defun @defun window-configuration-frame config |