diff options
Diffstat (limited to 'doc/lispref')
28 files changed, 2310 insertions, 496 deletions
diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 0d13408e3f8..a4ae68af5b2 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -451,11 +451,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 @@ -1187,7 +1187,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. @@ -1326,12 +1328,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 @@ -1849,6 +1848,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 @@ -1885,6 +1937,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 futher 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 @@ -1912,22 +2058,117 @@ 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. + +@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}) @@ -1980,7 +2221,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: @@ -2081,7 +2322,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 @@ -2186,21 +2427,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 @@ -2420,25 +2646,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 @@ -2630,10 +2845,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 +behaviour 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 @@ -2866,7 +3085,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 Ask user a multiple choice question. @var{prompt} should be a string that will be displayed as the prompt. @@ -2881,6 +3100,10 @@ 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. + The return value is the matching value from @var{choices}. @lisp @@ -2951,7 +3174,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. @@ -2962,12 +3185,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 @@ -3724,6 +3947,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 2b6ec849d28..3670225dc49 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 92cd67c1260..2f1666ba771 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1283,6 +1283,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{} @@ -1317,6 +1326,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..54059d7b6ed 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -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 @@ -737,7 +741,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/display.texi b/doc/lispref/display.texi index 8a138588d31..95e00e140da 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -561,6 +561,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 +612,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 +1364,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 @@ -1983,7 +2018,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 +2096,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 @@ -2110,6 +2156,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 +2227,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 @@ -2372,8 +2471,10 @@ 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}.) + + The @code{default} face must specify all attributes. Some of these attributes are meaningful only on certain kinds of displays. If your display cannot handle a certain attribute, the @@ -2394,8 +2495,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 +2565,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 @@ -2710,8 +2815,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}, @@ -3223,6 +3329,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,10 +3464,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. @@ -3363,6 +3479,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 @@ -4814,9 +4952,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 @@ -4824,6 +4960,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, @@ -5099,6 +5279,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}: @@ -5299,13 +5497,13 @@ 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}. Furthermore, if you build Emacs with ImageMagick (@code{libMagickWand}) support, Emacs can display any image format @@ -6309,6 +6507,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 @@ -6460,7 +6661,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 @@ -6487,7 +6688,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 @@ -6563,6 +6766,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: @@ -6734,7 +6942,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 @@ -6747,7 +6958,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 @@ -6755,6 +6976,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 @@ -6765,7 +6997,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 @@ -6828,6 +7065,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 @@ -7021,7 +7382,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 @@ -7496,16 +7857,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 @@ -7914,7 +8273,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). +@vindex 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: @@ -7994,6 +8360,16 @@ 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 @@ -8071,6 +8447,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 @@ -8117,13 +8497,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 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 ed57802bed3..eff9621628e 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1267,7 +1267,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..426bb6d0176 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. @@ -839,6 +848,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 +1133,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 +1231,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/files.texi b/doc/lispref/files.texi index 08677f789a5..6e59e87d286 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1314,6 +1314,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 @@ -2083,6 +2097,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 +2244,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 @@ -3278,8 +3308,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}, @@ -3338,7 +3368,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}, diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index fa033add0db..bae8eb3c703 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}. @@ -679,7 +685,7 @@ indicate that position for the various builds: @itemize @w{} @item (1) non-toolkit and terminal frames -@item (2) Lucid, Motif and MS-Windows frames +@item (2) Lucid, Motif, MS-Windows, and Haiku frames @item (3) GTK+ and NS frames @end itemize @@ -1728,7 +1734,9 @@ 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 +@code{fullboth}, or @code{maximized}.@footnote{On Haiku, setting +@code{fullscreen} to @code{fullwidth} or @code{fullheight} 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 @@ -2160,6 +2168,11 @@ 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 sticky +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 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 +2203,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 +2367,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 +2438,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 +3275,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 @@ -3726,6 +3759,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 @@ -3925,6 +3965,47 @@ 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 diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 06d50311799..207919ea645 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -669,6 +669,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 +985,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 +1010,7 @@ string. @group (mapconcat (lambda (x) (format "%c" (1+ x))) - "HAL-8000" - "") + "HAL-8000") @result{} "IBM.9111" @end group @end example @@ -2138,8 +2153,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 +2310,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 diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index fb0d3c203c8..10a12940a15 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -333,6 +333,13 @@ 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}. + @item ` (grave accent) stands for a left quote. This generates a left single quotation mark, an apostrophe, or a grave @@ -644,7 +651,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/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/keymaps.texi b/doc/lispref/keymaps.texi index bda9301ffc1..9d3dc8fe420 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,103 @@ 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. + +@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. + +@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 +464,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 +517,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}. @@ -610,16 +715,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 +787,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 +803,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 +821,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 +894,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 +930,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 @@ -1025,7 +1098,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 +1186,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") +(keymap-lookup (current-global-map) "C-x C-f") @result{} find-file @end group @group -(lookup-key (current-global-map) (kbd "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 +1208,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 +1223,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 +1238,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 +1259,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 +1289,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 +1350,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. + +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}. -@defun define-key keymap key binding +@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 +1414,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 +1432,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 +1442,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 +1455,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 +1481,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 +1587,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, and with a nil @var{def}, 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 +1780,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 +1795,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 +1808,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 @@ -1670,7 +1940,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 @@ -1700,55 +1970,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 @@ -1759,20 +2008,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. @@ -1783,50 +2032,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 @@ -2064,7 +2295,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. @@ -2227,6 +2458,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; @@ -2675,9 +2912,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 @@ -2812,9 +3049,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 @@ -2828,7 +3065,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 @@ -2840,7 +3077,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/loading.texi b/doc/lispref/loading.texi index 18c22142fee..68cd74c7d16 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -291,29 +291,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 +339,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 +366,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 +398,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 @@ -482,7 +501,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 @@ -552,7 +571,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 @@ -1048,13 +1067,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 +1091,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 +1122,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 +1187,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/modes.texi b/doc/lispref/modes.texi index bc078d60e15..c29936d5caa 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 artefacts 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,11 +1355,9 @@ 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) +(defvar-keymap text-mode-map + "C-M-i" #'ispell-complete-word + @dots{}) "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.") @@ -1411,13 +1430,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 +1443,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 @@ -1961,8 +1974,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 diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index b8e2dc5ab95..07caaa2a07a 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -1535,6 +1535,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 @@ -1860,6 +1861,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 diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index b1c19e384be..9cb9bc75d04 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -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 @@ -947,6 +950,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. @@ -1349,7 +1355,7 @@ 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 @code{(@var{high} @var{low} @var{micro})} or @code{(@var{high} @@ -1504,10 +1510,7 @@ 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 +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 @@ -1721,7 +1724,8 @@ 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 @@ -2187,7 +2191,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 @@ -3238,6 +3248,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/processes.texi b/doc/lispref/processes.texi index 3fa6c844ae9..ed07c1cbf70 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -966,6 +966,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 @@ -1413,11 +1422,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 @@ -2371,8 +2382,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 diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 86f418442d5..c9828f9c868 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -2045,7 +2045,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 +2070,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 +2094,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 +2212,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 +2854,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/streams.texi b/doc/lispref/streams.texi index c6b3397ae11..8f8562cadc8 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -327,6 +327,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 +367,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) @@ -872,6 +890,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, diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 6a6b756fbe5..d31807ad2aa 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -430,8 +430,8 @@ 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 diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index a951e9be8ae..9e44348b671 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 @@ -751,3 +751,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 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 958da2f3609..7897adeb053 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 @@ -599,6 +601,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}, @@ -1329,7 +1344,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 +1508,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 +1653,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 @@ -3603,6 +3664,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} @@ -3628,9 +3694,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 @@ -3937,6 +4014,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 @@ -4169,7 +4248,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 @@ -4182,9 +4261,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 @@ -4716,9 +4795,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 @@ -4867,6 +4945,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 @@ -5059,6 +5223,177 @@ 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. +@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 + @node Parsing HTML/XML @section Parsing HTML and XML @cindex parsing html diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index e15ed0cb7cd..061a5d672ec 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 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 07979b0d91e..d991ae9e277 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"}). @@ -686,7 +687,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 +703,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 +861,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 +1711,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 @@ -2279,11 +2297,11 @@ list in @var{variables} is an alist of the form @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 +2355,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 @@ -2769,3 +2787,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 wher 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 e070e84c67b..43f222d57ff 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -3038,6 +3038,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 +3076,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 +3217,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 @@ -3333,8 +3377,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 +3392,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 +3409,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 +3483,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 +3529,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 +3586,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 +3609,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 +3716,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 +3860,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 +3874,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) |