diff options
Diffstat (limited to 'doc/lispref')
35 files changed, 2331 insertions, 326 deletions
diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index 7aadee7adea..5bf6e99d587 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -125,6 +125,7 @@ srcs = \ $(srcdir)/symbols.texi \ $(srcdir)/syntax.texi \ $(srcdir)/text.texi \ + $(srcdir)/threads.texi \ $(srcdir)/tips.texi \ $(srcdir)/variables.texi \ $(srcdir)/windows.texi \ diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi index b9e6466c871..35a18651488 100644 --- a/doc/lispref/backups.texi +++ b/doc/lispref/backups.texi @@ -41,6 +41,11 @@ You can alternatively request numbered backups; then each new backup file gets a new name. You can delete old numbered backups when you don't want them any more, or Emacs can delete them automatically. + For performance, the operating system may not write the backup +file's contents to secondary storage immediately, or may alias the +backup data with the original until one or the other is later +modified. @xref{Files and Storage}. + @menu * Making Backups:: How Emacs makes backup files, and when. * Rename or Copy:: Two alternatives: renaming the old file or copying it. diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 740d7cfd8a1..e4ef4d5db6e 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -669,8 +669,9 @@ reason. This function is used to ask a user how to proceed after an attempt to modify an buffer visiting file @var{filename} when the file is newer than the buffer text. Emacs detects this because the modification -time of the file on disk is newer than the last save-time of the -buffer. This means some other program has probably altered the file. +time of the file on disk is newer than the last save-time and its contents +have changed. +This means some other program has probably altered the file. @kindex file-supersession Depending on the user's answer, the function may return normally, in diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 6e83659f635..c4de5299ce9 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -2618,6 +2618,31 @@ 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 +Ask user a multiple choice question. @var{prompt} should be a string +that will be displayed as the prompt. + +@var{choices} is an alist where the first element in each entry is a +character to be entered, the second element is a short name for the +entry to be displayed while prompting (if there's room, it might be +shortened), and the third, optional entry is a longer explanation that +will be displayed in a help buffer if the user requests more help. + +The return value is the matching value from @var{choices}. + +@lisp +(read-multiple-choice + "Continue connecting?" + '((?a "always" "Accept this certificate this session and for all future sessions.") + (?s "session only" "Accept this certificate this session only.") + (?n "no" "Refuse to use this certificate, and close the connection."))) +@end lisp + +The @code{read-multiple-choice-face} face is used to highlight the +matching characters in the name string on graphical terminals. + +@end defun + @node Event Mod @subsection Modifying and Translating Input Events @cindex modifiers of events @@ -2892,6 +2917,12 @@ like this: @end example @end defmac +@defvar while-no-input-ignore-events +This variable allow setting which special events @code{while-no-input} +should ignore. It is a list of symbols. + +@end defvar + @defun discard-input @cindex flushing input @cindex discarding input diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 371934377a8..8fb663d2aee 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -69,6 +69,7 @@ debugger recursively. @xref{Recursive Editing}. * Error Debugging:: Entering the debugger when an error happens. * Infinite Loops:: Stopping and debugging a program that doesn't exit. * Function Debugging:: Entering it when a certain function is called. +* Variable Debugging:: Entering it when a variable is modified. * Explicit Debug:: Entering it at a certain point in the program. * Using Debugger:: What the debugger does; what you see while in it. * Debugger Commands:: Commands used while in the debugger. @@ -290,6 +291,36 @@ Calling @code{cancel-debug-on-entry} does nothing to a function which is not currently set up to break on entry. @end deffn +@node Variable Debugging +@subsection Entering the debugger when a variable is modified +@cindex variable write debugging +@cindex debugging changes to variables + +Sometimes a problem with a function is due to a wrong setting of a +variable. Setting up the debugger to trigger whenever the variable is +changed is a quick way to find the origin of the setting. + +@deffn Command debug-on-variable-change variable +This function arranges for the debugger to be called whenever +@var{variable} is modified. + +It is implemented using the watchpoint mechanism, so it inherits the +same characteristics and limitations: all aliases of @var{variable} +will be watched together, only dynamic variables can be watched, and +changes to the objects referenced by variables are not detected. For +details, see @ref{Watching Variables}. +@end deffn + +@deffn Command cancel-debug-on-variable-change &optional variable +This function undoes the effect of @code{debug-on-variable-change} on +@var{variable}. When called interactively, it prompts for +@var{variable} in the minibuffer. If @var{variable} is omitted or +@code{nil}, it cancels break-on-change for all variables. Calling +@code{cancel-debug-on-variable-change} does nothing to a variable +which is not currently set up to break on change. +@end deffn + + @node Explicit Debug @subsection Explicit Entry to the Debugger @cindex debugger, explicit entry @@ -630,6 +661,37 @@ forms are elided. @end smallexample @end deffn +@defvar debugger-stack-frame-as-list +If this variable is non-@code{nil}, every stack frame of the backtrace +is displayed as a list. This aims at improving the backtrace +readability at the cost of special forms no longer being visually +different from regular function calls. + +With @code{debugger-stack-frame-as-list} non-@code{nil}, the above +example would look as follows: + +@smallexample +@group +----------- Buffer: backtrace-output ------------ + (backtrace) + (list ...computing arguments...) +@end group + (progn ...) + (eval (progn (1+ var) (list (quote testing) (backtrace)))) + (setq ...) + (save-excursion ...) + (let ...) + (with-output-to-temp-buffer ...) + (eval (with-output-to-temp-buffer ...)) + (eval-last-sexp-1 nil) +@group + (eval-last-sexp nil) + (call-interactively eval-last-sexp) +----------- Buffer: backtrace-output ------------ +@end group +@end smallexample +@end defvar + @defvar debug-on-next-call @cindex @code{eval}, and debugging @cindex @code{apply}, and debugging @@ -665,7 +727,7 @@ invocation. This variable is obsolete and will be removed in future versions. @end defvar -@defun backtrace-frame frame-number +@defun backtrace-frame frame-number &optional base The function @code{backtrace-frame} is intended for use in Lisp debuggers. It returns information about what computation is happening in the stack frame @var{frame-number} levels down. @@ -682,10 +744,31 @@ In the return value, @var{function} is whatever was supplied as the case of a macro call. If the function has a @code{&rest} argument, that is represented as the tail of the list @var{arg-values}. +If @var{base} is specified, @var{frame-number} counts relative to +the topmost frame whose @var{function} is @var{base}. + If @var{frame-number} is out of range, @code{backtrace-frame} returns @code{nil}. @end defun +@defun mapbacktrace function &optional base +The function @code{mapbacktrace} calls @var{function} once for each +frame in the backtrace, starting at the first frame whose function is +@var{base} (or from the top if @var{base} is omitted or @code{nil}). + +@var{function} is called with four arguments: @var{evald}, @var{func}, +@var{args}, and @var{flags}. + +If a frame has not evaluated its arguments yet or is a special form, +@var{evald} is @code{nil} and @var{args} is a list of forms. + +If a frame has evaluated its arguments and called its function +already, @var{evald} is @code{t} and @var{args} is a list of values. +@var{flags} is a plist of properties of the current frame: currently, +the only supported property is @code{:debug-on-exit}, which is +@code{t} if the stack frame's @code{debug-on-exit} flag is set. +@end defun + @include edebug.texi @node Syntax Errors diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index fbdc574c658..945a701fcb2 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -2101,7 +2101,7 @@ is equivalent to a Lisp symbol with the same name.}. Named faces are defined using the @code{defface} macro (@pxref{Defining Faces}). Emacs comes with several standard named faces (@pxref{Basic Faces}). - Many parts of Emacs required named faces, and do not accept + Many parts of Emacs require named faces, and do not accept anonymous faces. These include the functions documented in @ref{Attribute Functions}, and the variable @code{font-lock-keywords} (@pxref{Search-based Fontification}). Unless otherwise stated, we @@ -4779,8 +4779,8 @@ displayed (@pxref{Display Feature Testing}). * Image Descriptors:: How to specify an image for use in @code{:display}. * XBM Images:: Special features for XBM format. * XPM Images:: Special features for XPM format. -* PostScript Images:: Special features for PostScript format. * ImageMagick Images:: Special features available through ImageMagick. +* SVG Images:: Creating and manipulating SVG images. * Other Image Types:: Various other formats are supported. * Defining Images:: Convenient ways to define an image for later use. * Showing Images:: Convenient ways to display an image once it is defined. @@ -4803,12 +4803,12 @@ 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}), PostScript (@code{gs}), JPEG (@code{libjpeg}), TIFF +@code{libungif}), JPEG (@code{libjpeg}), TIFF (@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}). 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{postscript}, +@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{jpeg}, @code{tiff}, @code{png}, and @code{svg}. Furthermore, if you build Emacs with ImageMagick @@ -5121,39 +5121,12 @@ the name of a color as it appears in the image file, and @var{color} specifies the actual color to use for displaying that name. @end table -@node PostScript Images -@subsection PostScript Images -@cindex postscript images - - To use PostScript for an image, specify image type @code{postscript}. -This works only if you have Ghostscript installed. You must always use -these three properties: - -@table @code -@item :pt-width @var{width} -The value, @var{width}, specifies the width of the image measured in -points (1/72 inch). @var{width} must be an integer. - -@item :pt-height @var{height} -The value, @var{height}, specifies the height of the image in points -(1/72 inch). @var{height} must be an integer. - -@item :bounding-box @var{box} -The value, @var{box}, must be a list or vector of four integers, which -specifying the bounding box of the PostScript image, analogous to the -@samp{BoundingBox} comment found in PostScript files. - -@example -%%BoundingBox: 22 171 567 738 -@end example -@end table - @node ImageMagick Images @subsection ImageMagick Images @cindex ImageMagick images @cindex images, support for more formats - If you build Emacs with ImageMagick support, you can use the + If your Emacs build has ImageMagick support, you can use the ImageMagick library to load many image formats (@pxref{File Conveniences,,, emacs, The GNU Emacs Manual}). The image type symbol for images loaded via ImageMagick is @code{imagemagick}, regardless of @@ -5224,6 +5197,16 @@ and if @code{:height} is set it will have precedence over wish. @code{:max-width} and @code{:max-height} will always preserve the aspect ratio. +@item :scale @var{scale} +This should be a number, where values higher than 1 means to increase +the size, and lower means to decrease the size. For instance, a value +of 0.25 will make the image a quarter size of what it originally was. +If the scaling makes the image larger than specified by +@code{:max-width} or @code{:max-height}, the resulting size will not +exceed those two values. If both @code{:scale} and +@code{:height}/@code{:width} are specified, the height/width will be +adjusted by the specified scaling factor. + @item :format @var{type} The value, @var{type}, should be a symbol specifying the type of the image data, as found in @code{image-format-suffixes}. This is used @@ -5238,6 +5221,163 @@ Specifies a rotation angle in degrees. @xref{Multi-Frame Images}. @end table +@node SVG Images +@subsection SVG Images +@cindex SVG images + +SVG (Scalable Vector Graphics) is an XML format for specifying images. +If your Emacs build has with SVG support, you can create and manipulate +these images with the following commands. + +@defun svg-create width height &rest args +Create a new, empty SVG image with the specified dimensions. +@var{args} is an argument plist with you can specify following: + +@table @code +@item :stroke-width +The default width (in pixels) of any lines created. + +@item :stroke +The default stroke color on any lines created. +@end table + +This function returns an SVG structure, and all the following commands +work on that structure. +@end defun + +@defun svg-gradient svg id type stops +Create a gradient in @var{svg} with identifier @var{id}. @var{type} +specifies the gradient type, and can be either @code{linear} or +@code{radial}. @var{stops} is a list of percentage/color pairs. + +The following will create a linear gradient that goes from red at the +start, to green 25% of the way, to blue at the end: + +@lisp +(svg-gradient svg "gradient1" 'linear + '((0 . "red") (25 . "green") (100 . "blue"))) +@end lisp + +The gradient created (and inserted into the SVG object) can later be +used by all functions that create shapes. +@end defun + +All the following functions take an optional list of keyword +parameters that alter the various attributes from their default +values. Valid attributes include: + +@table @code +@item :stroke-width +The width (in pixels) of lines drawn, and outlines around solid +shapes. + +@item :stroke-color +The color of lines drawn, and outlines around solid shapes. + +@item :fill-color +The color used for solid shapes. + +@item :id +The identified of the shape. + +@item :gradient +If given, this should be the identifier of a previously defined +gradient object. +@end table + +@defun svg-rectangle svg x y width height &rest args +Add a rectangle to @var{svg} where the upper left corner is at +position @var{x}/@var{y} and is of size @var{width}/@var{height}. + +@lisp +(svg-rectangle svg 100 100 500 500 :gradient "gradient1") +@end lisp +@end defun + +@defun svg-circle svg x y radius &rest args +Add a circle to @var{svg} where the center is at @var{x}/@var{y} +and the radius is @var{radius}. +@end defun + +@defun svg-ellipse svg x y x-radius y-radius &rest args +Add a circle to @var{svg} where the center is at @var{x}/@var{y} and +the horizontal radius is @var{x-radius} and the vertical radius is +@var{y-radius}. +@end defun + +@defun svg-line svg x1 y1 x2 y2 &rest args +Add a line to @var{svg} that starts at @var{x1}/@var{y1} and extends +to @var{x2}/@var{y2}. +@end defun + +@defun svg-polyline svg points &rest args +Add a multiple segment line to @var{svg} that goes through +@var{points}, which is a list of X/Y position pairs. + +@lisp +(svg-polyline svg '((200 . 100) (500 . 450) (80 . 100)) + :stroke-color "green") +@end lisp +@end defun + +@defun svg-polygon svg points &rest args +Add a polygon to @var{svg} where @var{points} is a list of X/Y pairs +that describe the outer circumference of the polygon. + +@lisp +(svg-polygon svg '((100 . 100) (200 . 150) (150 . 90)) + :stroke-color "blue" :fill-color "red"") +@end lisp +@end defun + +@defun svg-text svg text &rest args +Add a text to @var{svg}. + +@lisp +(svg-text + svg "This is a text" + :font-size "40" + :font-weight "bold" + :stroke "black" + :fill "white" + :font-family "impact" + :letter-spacing "4pt" + :x 300 + :y 400 + :stroke-width 1) +@end lisp +@end defun + +@defun svg-embed svg image image-type datap &rest args +Add an embedded (raster) image to @var{svg}. If @var{datap} is +@code{nil}, @var{IMAGE} should be a file name; if not, it should be a +binary string containing the image data. @var{image-type} should be a +@acronym{MIME} image type, for instance @samp{"image/jpeg"}. + +@lisp +(svg-embed svg "~/rms.jpg" "image/jpeg" nil + :width "100px" :height "100px" + :x "50px" :y "75px") +@end lisp +@end defun + +@defun svg-remove svg id +Remove the element with identifier @code{id} from the @code{svg}. +@end defun + +Finally, the @code{svg-image} takes an SVG object as its parameter and +returns an image object suitable for use in functions like +@code{insert-image}. Here's a complete example that creates and +inserts an image with a circle: + +@lisp +(let ((svg (svg-create 400 400 :stroke-width 10))) + (svg-gradient svg "gradient1" 'linear '((0 . "red") (100 . "blue"))) + (svg-circle svg 200 200 100 :gradient "gradient1" :stroke-color "green") + (insert-image (svg-image svg))) +@end lisp + + @node Other Image Types @subsection Other Image Types @cindex PBM @@ -5274,9 +5414,6 @@ Image type @code{jpeg}. @item PNG Image type @code{png}. -@item SVG -Image type @code{svg}. - @item TIFF Image type @code{tiff}. Supports the @code{:index} property. @xref{Multi-Frame Images}. @@ -5340,6 +5477,12 @@ If none of the alternatives will work, then @var{symbol} is defined as @code{nil}. @end defmac +@defun image-property image property +Return the value of @var{property} in @var{image}. Properties can be +set by using @code{setf}. Setting a property to @code{nil} will +remove the property from the image. +@end defun + @defun find-image specs This function provides a convenient way to find an image satisfying one of a list of image specifications @var{specs}. @@ -5410,6 +5553,13 @@ Here is an example of using @code{image-load-path-for-library}: @end example @end defun +@vindex image-scaling-factor +Images are automatically scaled when created based on the +@code{image-scaling-factor} variable. The value is either a floating +point number (where numbers higher than 1 means to increase the size +and lower means to shrink the size), or the symbol @code{auto}, which +will compute a scaling factor based on the font pixel size. + @node Showing Images @subsection Showing Images @cindex show image @@ -5519,6 +5669,26 @@ cache, it can always be displayed, even if the value of @code{max-image-size} is subsequently changed (@pxref{Image Cache}). @end defvar +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: + +@table @kbd +@item + +Increase the image size (@code{image-increase-size}). A prefix value +of @samp{4} means to increase the size by 40%. The default is 20%. + +@item - +Decrease the image size (@code{image-increase-size}). A prefix value +of @samp{4} means to decrease the size by 40%. The default is 20%. + +@item r +Rotate the image by 90 degrees (@code{image-rotate}). + +@item o +Save the image to a file (@code{image-save}). +@end table + @node Multi-Frame Images @subsection Multi-Frame Images @cindex multi-frame images @@ -6969,7 +7139,7 @@ Emacs is displaying the frame on a character-based terminal. @defvar initial-window-system This variable holds the value of @code{window-system} used for the first frame created by Emacs during startup. (When Emacs is invoked -with the @option{--daemon} option, it does not create any initial +as a daemon, it does not create any initial frames, so @code{initial-window-system} is @code{nil}, except on MS-Windows, where it is still @code{w32}. @xref{Initial Options, daemon,, emacs, The GNU Emacs Manual}.) diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 47fe02a4a57..65ccb646909 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -384,6 +384,11 @@ now, it returns from the function and then stops. In other words, this command does not exit the currently executing function unless you are positioned after the last sexp. +Normally, the @kbd{h}, @kbd{f}, and @kbd{o} commands display ``Break'' +and pause for @code{edebug-sit-for-seconds} before showing the result +of the form just evaluated. You can avoid this pause by setting +@code{edebug-sit-on-break} to @code{nil}. @xref{Edebug Options}. + The @kbd{i} command steps into the function or macro called by the list form after point, and stops at its first stop point. Note that the form need not be the one about to be evaluated. But if the form is a @@ -1543,6 +1548,14 @@ Use the command @kbd{M-x edebug-all-forms} to toggle the value of this option. @xref{Instrumenting}. @end defopt +@defopt edebug-eval-macro-args +When this is non-@code{nil}, all macro arguments will be instrumented +in the generated code. For any macro, an @code{edebug-form-spec} +overrides this option. So to specify exceptions for macros that have +some arguments evaluated and some not, use @code{def-edebug-spec} to +specify an @code{edebug-form-spec}. +@end defopt + @defopt edebug-save-windows If this is non-@code{nil}, Edebug saves and restores the window configuration. That takes some time, so if your program does not care @@ -1601,6 +1614,21 @@ debugged. @xref{Edebug Execution Modes}. @end defopt +@defopt edebug-print-length +If non-@code{nil}, the default value of @code{print-length} for +printing results in Edebug. @xref{Output Variables}. +@end defopt + +@defopt edebug-print-level +If non-@code{nil}, the default value of @code{print-level} for +printing results in Edebug. @xref{Output Variables}. +@end defopt + +@defopt edebug-print-circle +If non-@code{nil}, the default value of @code{print-circle} for +printing results in Edebug. @xref{Output Variables}. +@end defopt + @defopt edebug-unwrap-results If non-@code{nil}, Edebug tries to remove any of its own instrumentation when showing the results of expressions. This is @@ -1647,3 +1675,14 @@ If non-@code{nil}, an expression to test for at every stop point. If the result is non-@code{nil}, then break. Errors are ignored. @xref{Global Break Condition}. @end defopt + +@defopt edebug-sit-for-seconds +Number of seconds to pause when a breakpoint is reached and the execution +mode is trace or continue. @xref{Edebug Execution Modes}. +@end defopt + +@defopt edebug-sit-on-break +Whether or not to pause for @code{edebug-sit-for-seconds} on reaching +a breakpoint. Set to @code{nil} to prevent the pause, non-@code{nil} +to allow it. +@end defopt diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 3297e5308ae..494e8fcb6c3 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -219,6 +219,7 @@ To view this manual in other formats, click * Syntax Tables:: The syntax table controls word and list parsing. * Abbrevs:: How Abbrev mode works, and its data structures. +* Threads:: Concurrency in Emacs Lisp. * Processes:: Running and communicating with subprocesses. * Display:: Features for controlling the screen display. * System Interface:: Getting the user id, system type, environment @@ -348,6 +349,9 @@ Editing Types * Window Configuration Type:: Recording the way a frame is subdivided. * Frame Configuration Type:: Recording the status of all frames. * Process Type:: A subprocess of Emacs running on the underlying OS. +* Thread Type:: A thread of Emacs Lisp execution. +* Mutex Type:: An exclusive lock for thread synchronization. +* Condition Variable Type:: Condition variable for thread synchronization. * Stream Type:: Receive or send characters. * Keymap Type:: What function a keystroke invokes. * Overlay Type:: How an overlay is represented. @@ -498,11 +502,13 @@ Variables * Accessing Variables:: Examining values of variables whose names are known only at run time. * Setting Variables:: Storing new values in variables. +* Watching Variables:: Running a function when a variable is changed. * Variable Scoping:: How Lisp chooses among local and global values. * Buffer-Local Variables:: Variable values in effect only in one buffer. * File Local Variables:: Handling local variable lists in files. * Directory Local Variables:: Local variables common to all files in a directory. +* Connection Local Variables:: Local variables common for remote connections. * Variable Aliases:: Variables that are aliases for other variables. * Variables with Restricted Values:: Non-constant variables whose value can @emph{not} be an arbitrary Lisp object. @@ -641,6 +647,7 @@ The Lisp Debugger * Error Debugging:: Entering the debugger when an error happens. * Infinite Loops:: Stopping and debugging a program that doesn't exit. * Function Debugging:: Entering it when a certain function is called. +* Variable Debugging:: Entering it when a variable is modified. * Explicit Debug:: Entering it at a certain point in the program. * Using Debugger:: What the debugger does; what you see while in it. * Debugger Commands:: Commands used while in the debugger. @@ -1038,6 +1045,8 @@ Windows a specific window. * Quitting Windows:: How to restore the state prior to displaying a buffer. +* Side Windows:: Special windows on a frame's sides. +* Atomic Windows:: Preserving parts of the window layout. * Window Point:: Each window has its own location of point. * Window Start and End:: Buffer positions indicating which text is on-screen in a window. @@ -1051,6 +1060,14 @@ Windows redisplay going past a certain point, or window configuration changes. +Side Windows + +* Displaying Buffers in Side Windows:: An action function for displaying + buffers in side windows. +* Side Window Options and Functions:: Further tuning of side windows. +* Frame Layouts with Side Windows:: Setting up frame layouts with side + windows. + Frames * Creating Frames:: Creating additional frames. @@ -1309,6 +1326,12 @@ Abbrevs and Abbrev Expansion * Abbrev Table Properties:: How to read and set abbrev table properties. Which properties have which effect. +Threads + +* Basic Thread Functions:: Basic thread functions. +* Mutexes:: Mutexes allow exclusive access to data. +* Condition Variables:: Inter-thread events. + Processes * Subprocess Creation:: Functions that start subprocesses. @@ -1449,7 +1472,6 @@ Images * Image Descriptors:: How to specify an image for use in @code{:display}. * XBM Images:: Special features for XBM format. * XPM Images:: Special features for XPM format. -* PostScript Images:: Special features for PostScript format. * ImageMagick Images:: Special features available through ImageMagick. * Other Image Types:: Various other formats are supported. * Defining Images:: Convenient ways to define an image for later use. @@ -1615,6 +1637,7 @@ Object Internals @include searching.texi @include syntax.texi @include abbrevs.texi +@include threads.texi @include processes.texi @include display.texi diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index 03aea4ef445..4a0e38c782f 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -107,6 +107,11 @@ the error-strings are not very relevant. However, these error symbols do have @code{error-message} properties, and if no data is provided, the @code{error-message} property @emph{is} used. @xref{Files}. +@item file-missing +This is a subcategory of @code{file-error}. It occurs when an +operation attempts to act on a file that is missing. @xref{Changing +Files}. + @c jka-compr.el @item compression-error This is a subcategory of @code{file-error}, which results from diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 85c80d76f73..906cd562612 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -41,6 +41,7 @@ to locale @code{system-messages-locale}, and decoded using coding system simultaneous editing by two people. * Information about Files:: Testing existence, accessibility, size of files. * Changing Files:: Renaming files, changing permissions, etc. +* Files and Storage:: Surviving power and media failures * File Names:: Decomposing and expanding file names. * Contents of Directories:: Getting a list of the files in a directory. * Create/Delete Dirs:: Creating and Deleting Directories. @@ -660,6 +661,15 @@ feature is useful for programs that use files for internal purposes, files that the user does not need to know about. @end deffn +@defvar write-region-inhibit-fsync +If this variable's value is @code{nil}, @code{write-region} uses the +@code{fsync} system call after writing a file. Although this slows +Emacs down, it lessens the risk of data loss after power failure. If +the value is @code{t}, Emacs does not use @code{fsync}. The default +value is @code{nil} when Emacs is interactive, and @code{t} when Emacs +runs in batch mode. @xref{Files and Storage}. +@end defvar + @defmac with-temp-file file body@dots{} @anchor{Definition of with-temp-file} The @code{with-temp-file} macro evaluates the @var{body} forms with a @@ -1130,6 +1140,25 @@ appropriate manner. If @var{file1} or @var{file2} does not exist, the return value is unspecified. @end defun +@defun file-name-case-insensitive-p filename +Sometimes file names or their parts need to be compared as strings, in +which case it's important to know whether the underlying filesystem is +case-insensitive. This function returns @code{t} if file +@var{filename} is on a case-insensitive filesystem. It always returns +@code{t} on MS-DOS and MS-Windows. On Cygwin and Mac OS X, +filesystems may or may not be case-insensitive, and the function tries +to determine case-sensitivity by a runtime test. If the test is +inconclusive, the function returns @code{t} on Cygwin and @code{nil} +on Mac OS X. + +Currently this function always returns @code{nil} on platforms other +than MS-DOS, MS-Windows, Cygwin, and Mac OS X. It does not detect +case-insensitivity of mounted filesystems, such as Samba shares or +NFS-mounted Windows volumes. On remote hosts, it assumes @code{t} for +the @samp{smb} method. For all other connection methods, runtime +tests are performed. +@end defun + @defun file-in-directory-p file dir This function returns @code{t} if @var{file} is a file in directory @var{dir}, or in a subdirectory of @var{dir}. It also returns @@ -1210,73 +1239,83 @@ the default, but we plan to change that, so you should specify a non-@code{nil} value for @var{id-format} if you use the returned @acronym{UID} or @acronym{GID}. +Accessor functions are provided to access the elements in this list. +The accessors are mentioned along with the descriptions of the +elements below. + The elements of the list, in order, are: @enumerate 0 @item @code{t} for a directory, a string for a symbolic link (the name -linked to), or @code{nil} for a text file. +linked to), or @code{nil} for a text file +(@code{file-attribute-type}). @c Wordy so as to prevent an overfull hbox. --rjc 15mar92 @item -The number of names the file has. Alternate names, also known as hard -links, can be created by using the @code{add-name-to-file} function -(@pxref{Changing Files}). +The number of names the file has (@code{file-attribute-link-number}). +Alternate names, also known as hard links, can be created by using the +@code{add-name-to-file} function (@pxref{Changing Files}). @item -The file's @acronym{UID}, normally as a string. However, if it does -not correspond to a named user, the value is a number. +The file's @acronym{UID}, normally as a string +(@code{file-attribute-user-id}). However, if it does not correspond +to a named user, the value is a number. @item -The file's @acronym{GID}, likewise. +The file's @acronym{GID}, likewise (@code{file-attribute-group-id}). @item -The time of last access, as a list of four integers @code{(@var{sec-high} -@var{sec-low} @var{microsec} @var{picosec})}. (This is similar to the -value of @code{current-time}; see @ref{Time of Day}.) Note that on -some FAT-based filesystems, only the date of last access is recorded, -so this time will always hold the midnight of the day of last access. +The time of last access, as a list of four integers +@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})} +(@code{file-attribute-access-time}). (This is similar to the value of +@code{current-time}; see @ref{Time of Day}.) Note that on some +FAT-based filesystems, only the date of last access is recorded, so +this time will always hold the midnight of the day of last access. @cindex modification time of file @item -The time of last modification as a list of four integers (as above). -This is the last time when the file's contents were modified. +The time of last modification as a list of four integers (as above) +(@code{file-attribute-modification-time}). This is the last time when +the file's contents were modified. @item -The time of last status change as a list of four integers (as above). -This is the time of the last change to the file's access mode bits, -its owner and group, and other information recorded in the filesystem -for the file, beyond the file's contents. +The time of last status change as a list of four integers (as above) +(@code{file-attribute-status-change-time}). This is the time of the +last change to the file's access mode bits, its owner and group, and +other information recorded in the filesystem for the file, beyond the +file's contents. @item -The size of the file in bytes. This is floating point if the size is -too large to fit in a Lisp integer. +The size of the file in bytes (@code{file-attribute-size}). This is +floating point if the size is too large to fit in a Lisp integer. @item -The file's modes, as a string of ten letters or dashes, -as in @samp{ls -l}. +The file's modes, as a string of ten letters or dashes, as in +@samp{ls -l} (@code{file-attribute-modes}). @item An unspecified value, present for backward compatibility. @item -The file's inode number. If possible, this is an integer. If the -inode number is too large to be represented as an integer in Emacs -Lisp but dividing it by @math{2^{16}} yields a representable integer, -then the value has the +The file's inode number (@code{file-attribute-inode-number}). If +possible, this is an integer. If the inode number is too large to be +represented as an integer in Emacs Lisp but dividing it by +@math{2^{16}} yields a representable integer, then the value has the form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16 -bits. If the inode number is too wide for even that, the value is of the form -@code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds -the high bits, @var{middle} the middle 24 bits, and @var{low} the low -16 bits. +bits. If the inode number is too wide for even that, the value is of +the form @code{(@var{high} @var{middle} . @var{low})}, where +@code{high} holds the high bits, @var{middle} the middle 24 bits, and +@var{low} the low 16 bits. @item -The filesystem number of the device that the file is on. Depending on -the magnitude of the value, this can be either an integer or a cons -cell, in the same manner as the inode number. This element and the -file's inode number together give enough information to distinguish -any two files on the system---no two files can have the same values -for both of these numbers. +The filesystem number of the device that the file is on +@code{file-attribute-device-number}). Depending on the magnitude of +the value, this can be either an integer or a cons cell, in the same +manner as the inode number. This element and the file's inode number +together give enough information to distinguish any two files on the +system---no two files can have the same values for both of these +numbers. @end enumerate For example, here are the file attributes for @file{files.texi}: @@ -1496,10 +1535,15 @@ in @code{exec-path}, and tries all the file-name extensions in @cindex setting modes of files The functions in this section rename, copy, delete, link, and set -the modes (permissions) of files. They all signal a @code{file-error} -error if they fail to perform their function, reporting the -system-dependent error message that describes the reason for the -failure. +the modes (permissions) of files. Typically, they signal a +@code{file-error} error if they fail to perform their function, +reporting the system-dependent error message that describes the reason +for the failure. If they fail because a file is missing, they signal +a @code{file-missing} error instead. + + For performance, the operating system may cache or alias changes +made by these functions instead of writing them immediately to +secondary storage. @xref{Files and Storage}. In the functions that have an argument @var{newname}, if a file by the name of @var{newname} already exists, the actions taken depend on the @@ -1799,6 +1843,28 @@ The function returns @code{t} if it successfully sets the ACL of @var{filename}, @code{nil} otherwise. @end defun +@node Files and Storage +@section Files and Secondary Storage +@cindex secondary storage + +After Emacs changes a file, there are two reasons the changes might +not survive later failures of power or media, both having to do with +efficiency. First, the operating system might alias written data with +data already stored elsewhere on secondary storage until one file or +the other is later modified; this will lose both files if the only +copy on secondary storage is lost due to media failure. Second, the +operating system might not write data to secondary storage +immediately, which will lose the data if power is lost. + +@findex write-region +Although both sorts of failures can largely be avoided by a suitably +configured file system, such systems are typically more expensive or +less efficient. In more-typical systems, to survive media failure you +can copy the file to a different device, and to survive a power +failure you can use the @code{write-region} function with the +@code{write-region-inhibit-fsync} variable set to @code{nil}. +@xref{Writing to Files}. + @node File Names @section File Names @cindex file names @@ -2336,6 +2402,47 @@ through the immediately preceding @samp{/}). @end defun + Sometimes, it is not desired to expand file names. In such cases, +the file name can be quoted to suppress the expansion, and to handle +the file name literally. Quoting happens by prefixing the file name +with @samp{/:}. + +@defmac file-name-quote name +This macro adds the quotation prefix @samp{/:} to the file @var{name}. +For a local file @var{name}, it prefixes @var{name} with @samp{/:}. +If @var{name} is a remote file name, the local part of @var{name} is +quoted. If @var{name} is already a quoted file name, @var{name} is +returned unchanged. + +@example +@group +(substitute-in-file-name (file-name-quote "bar/~/foo")) + @result{} "/:bar/~/foo" +@end group + +@group +(substitute-in-file-name (file-name-quote "/ssh:host:bar/~/foo")) + @result{} "/ssh:host:/:bar/~/foo" +@end group +@end example + +The macro cannot be used to suppress file name handlers from magic +file names (@pxref{Magic File Names}). +@end defmac + +@defmac file-name-unquote name +This macro removes the quotation prefix @samp{/:} from the file +@var{name}, if any. If @var{name} is a remote file name, the local +part of @var{name} is unquoted. +@end defmac + +@defmac file-name-quoted-p name +This macro returns non-@code{nil}, when @var{name} is quoted with the +prefix @samp{/:}. If @var{name} is a remote file name, the local part +of @var{name} is checked. +@end defmac + + @node Unique File Names @subsection Generating Unique File Names @cindex unique file names @@ -2446,6 +2553,43 @@ condition, between the @code{make-temp-name} call and the creation of the file, which in some cases may cause a security hole. @end defun +Sometimes, it is necessary to create a temporary file on a remote host +or a mounted directory. The following two functions support this. + +@defun make-nearby-temp-file prefix &optional dir-flag suffix +This function is similar to @code{make-temp-file}, but it creates a +temporary file as close as possible to @code{default-directory}. If +@var{prefix} is a relative file name, and @code{default-directory} is +a remote file name or located on a mounted file systems, the temporary +file is created in the directory returned by the function +@code{temporary-file-directory}. Otherwise, the function +@code{make-temp-file} is used. @var{prefix}, @var{dir-flag} and +@var{suffix} have the same meaning as in @code{make-temp-file}. + +@example +@group +(let ((default-directory "/ssh:remotehost:")) + (make-nearby-temp-file "foo")) + @result{} "/ssh:remotehost:/tmp/foo232J6v" +@end group +@end example +@end defun + +@defun temporary-file-directory +The directory for writing temporary files via +@code{make-nearby-temp-file}. In case of a remote +@code{default-directory}, this is a directory for temporary files on +that remote host. If such a directory does not exist, or +@code{default-directory} ought to be located on a mounted file system +(see @code{mounted-file-systems}), the function returns +@code{default-directory}. For a non-remote and non-mounted +@code{default-directory}, the value of the variable +@code{temporary-file-directory} is returned. +@end defun + +In order to extract the local part of the path name from a temporary +file, @code{file-local-name} could be used. + @node File Name Completion @subsection File Name Completion @cindex file name completion subroutines @@ -2781,6 +2925,9 @@ This command deletes the directory named @var{dirname}. The function must use @code{delete-directory} for them. If @var{recursive} is @code{nil}, and the directory contains any files, @code{delete-directory} signals an error. +If recursive is non-@code{nil}, there is no error merely because the +directory or its files are deleted by some other process before +@code{delete-directory} gets to them. @code{delete-directory} only follows symbolic links at the level of parent directories. @@ -2890,6 +3037,7 @@ first, before handlers for jobs such as remote file access. @code{file-local-copy}, @code{file-modes}, @code{file-name-all-completions}, @code{file-name-as-directory}, +@code{file-name-case-insensitive-p}, @code{file-name-completion}, @code{file-name-directory}, @code{file-name-nondirectory}, @@ -2900,8 +3048,7 @@ first, before handlers for jobs such as remote file access. @code{file-readable-p}, @code{file-regular-p}, @code{file-remote-p}, @code{file-selinux-context}, @code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, -@code{find-backup-file-name}, -@c Not sure why it was here: @code{find-file-noselect},@* +@code{find-backup-file-name},@* @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents},@* @@ -2909,6 +3056,7 @@ first, before handlers for jobs such as remote file access. @code{make-auto-save-file-name}, @code{make-directory}, @code{make-directory-internal}, +@code{make-nearby-temp-file}, @code{make-symbolic-link},@* @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @@ -2916,6 +3064,7 @@ first, before handlers for jobs such as remote file access. @code{set-visited-file-modtime}, @code{shell-command}, @code{start-file-process}, @code{substitute-in-file-name},@* +@code{temporary-file-directory}, @code{unhandled-file-name-directory}, @code{vc-registered}, @code{verify-visited-file-modtime},@* @@ -2944,6 +3093,7 @@ first, before handlers for jobs such as remote file access. @code{file-local-copy}, @code{file-modes}, @code{file-name-all-completions}, @code{file-name-as-directory}, +@code{file-name-case-insensitive-p}, @code{file-name-completion}, @code{file-name-directory}, @code{file-name-nondirec@discretionary{}{}{}tory}, @@ -2955,7 +3105,6 @@ first, before handlers for jobs such as remote file access. @code{file-remote-p}, @code{file-selinux-context}, @code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name}, -@c Not sure why it was here: @code{find-file-noselect}, @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents}, @@ -3119,6 +3268,13 @@ non-magic directory to serve as its current directory, and this function is a good way to come up with one. @end defun +@defun file-local-name filename +This function returns the local part of file @var{filename}. For a +remote @var{filename}, it returns a file name which could be used +directly as argument of a remote process. If @var{filename} is local, +this function returns the file name. +@end defun + @defopt remote-file-name-inhibit-cache The attributes of remote files can be cached for better performance. If they are changed outside of Emacs's control, the cached values become @@ -3244,7 +3400,9 @@ end position. One responsibility of @var{from-fn} is to make sure that the beginning of the file no longer matches @var{regexp}. Otherwise it is likely to -get called again. +get called again. Also, @var{from-fn} must not involve buffers or +files other than the one being decoded, otherwise the internal buffer +used for formatting might be overwritten. @item to-fn A shell command or function to encode data in this format---that is, to @@ -3275,6 +3433,10 @@ file, it intermixes the specified annotations at the corresponding positions. All this takes place without modifying the buffer. @end itemize +@var{to-fn} must not involve buffers or files other than the one being +encoded, otherwise the internal buffer used for formatting might be +overwritten. + @item modify A flag, @code{t} if the encoding function modifies the buffer, and @code{nil} if it works by returning a list of annotations. diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index ec344c726ce..dc1c524653d 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1539,6 +1539,13 @@ prevent hanging with those window managers. If non-@code{nil}, the frame is visible on all virtual desktops on systems with virtual desktops. +@vindex inhibit-double-buffering, a frame parameter +@item inhibit-double-buffering +If non-@code{nil}, the frame is drawn to the screen without double buffering. +Emacs normally attempts to use double buffering, where available, to +reduce flicker. Set this property if you experience display bugs or +pine for that retro, flicker-y feeling. + @ignore @vindex parent-id, a frame parameter @item parent-id @@ -1904,10 +1911,11 @@ to it. @deffn Command delete-frame &optional frame force @vindex delete-frame-functions -This function deletes the frame @var{frame}. Unless @var{frame} is a -tooltip, it first runs the hook @code{delete-frame-functions} (each -function gets one argument, @var{frame}). By default, @var{frame} is -the selected frame. +This function deletes the frame @var{frame}. The argument @var{frame} +must specify a live frame (see below) and defaults to the selected +frame. Unless @var{frame} specifies a tooltip, this function first runs +the hook @code{delete-frame-functions} (each function getting one +argument, @var{frame}). A frame cannot be deleted as long as its minibuffer serves as surrogate minibuffer for another frame (@pxref{Minibuffers and Frames}). @@ -1916,9 +1924,9 @@ but if @var{force} is non-@code{nil}, then you are allowed to do so. @end deffn @defun frame-live-p frame -The function @code{frame-live-p} returns non-@code{nil} if the frame -@var{frame} has not been deleted. The possible non-@code{nil} return -values are like those of @code{framep}. @xref{Frames}. +This function returns non-@code{nil} if the frame @var{frame} has not +been deleted. The possible non-@code{nil} return values are like those +of @code{framep}. @xref{Frames}. @end defun Some window managers provide a command to delete a window. These work @@ -1927,6 +1935,15 @@ When Emacs gets one of these commands, it generates a @code{delete-frame} event, whose normal definition is a command that calls the function @code{delete-frame}. @xref{Misc Events}. +@deffn Command delete-other-frames &optional frame +This command deletes all frames on @var{frame}'s terminal, except +@var{frame}. If @var{frame} uses another frame's minibuffer, that +minibuffer frame is left untouched. The argument @var{frame} must +specify a live frame and defaults to the selected frame. Internally, +this command works by calling @code{delete-frame} with @var{force} +@code{nil} for all frames that shall be deleted. +@end deffn + @node Finding All Frames @section Finding All Frames @cindex frames, scanning all @@ -1946,11 +1963,11 @@ visible, even though only the selected one is actually displayed. @end defun @defun next-frame &optional frame minibuf -This function lets you cycle conveniently through all the frames on -the current display from an arbitrary starting point. It returns the -next frame after @var{frame} in the cycle. If @var{frame} is -omitted or @code{nil}, it defaults to the selected frame (@pxref{Input -Focus}). +This function lets you cycle conveniently through all the frames on a +specific terminal from an arbitrary starting point. It returns the +frame following @var{frame}, in the list of all live frames, on +@var{frame}'s terminal. The argument @var{frame} must specify a live +frame and defaults to the selected frame. The second argument, @var{minibuf}, says which frames to consider: @@ -2200,6 +2217,12 @@ window manager. This happens below the level at which Emacs can exert any control, but Emacs does provide events that you can use to keep track of such changes. @xref{Misc Events}. +@defun x-double-buffered-p &optional frame +This function returns non-@code{nil} if @var{frame} is currently +being rendered with double buffering. @var{frame} defaults to the +selected frame. +@end defun + @node Raising and Lowering @section Raising and Lowering Frames diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index bc04beeebca..8dff1a70f75 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -143,6 +143,37 @@ function, i.e., can be passed to @code{funcall}. Note that and returns @code{nil} for special forms. @end defun + It is also possible to find out how many arguments an arbitrary +function expects: + +@defun func-arity function +This function provides information about the argument list of the +specified @var{function}. The returned value is a cons cell of the +form @w{@code{(@var{min} . @var{max})}}, where @var{min} is the +minimum number of arguments, and @var{max} is either the maximum +number of arguments, or the symbol @code{many} for functions with +@code{&rest} arguments, or the symbol @code{unevalled} if +@var{function} is a special form. + +Note that this function might return inaccurate results in some +situations, such as the following: + +@itemize @minus +@item +Functions defined using @code{apply-partially} (@pxref{Calling +Functions, apply-partially}). + +@item +Functions that are advised using @code{advice-add} (@pxref{Advising +Named Functions}). + +@item +Functions that determine the argument list dynamically, as part of +their code. +@end itemize + +@end defun + @noindent Unlike @code{functionp}, the next three functions do @emph{not} treat a symbol as its function definition. @@ -176,12 +207,9 @@ function. For example: @end defun @defun subr-arity subr -This function provides information about the argument list of a -primitive, @var{subr}. The returned value is a pair -@code{(@var{min} . @var{max})}. @var{min} is the minimum number of -args. @var{max} is the maximum number or the symbol @code{many}, for a -function with @code{&rest} arguments, or the symbol @code{unevalled} if -@var{subr} is a special form. +This works like @code{func-arity}, but only for built-in functions and +without symbol indirection. It signals an error for non-built-in +functions. We recommend to use @code{func-arity} instead. @end defun @node Lambda Expressions @@ -2145,44 +2173,48 @@ Byte-compiling a file often produces warnings about functions that the compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this indicates a real problem, but usually the functions in question are defined in other files which would be loaded if that code is run. For -example, byte-compiling @file{fortran.el} used to warn: +example, byte-compiling @file{simple.el} used to warn: @example -In end of data: -fortran.el:2152:1:Warning: the function ‘gud-find-c-expr’ is not - known to be defined. +simple.el:8727:1:Warning: the function ‘shell-mode’ is not known to be + defined. @end example -In fact, @code{gud-find-c-expr} is only used in the function that -Fortran mode uses for the local value of -@code{gud-find-expr-function}, which is a callback from GUD; if it is -called, the GUD functions will be loaded. When you know that such a -warning does not indicate a real problem, it is good to suppress the -warning. That makes new warnings which might mean real problems more -visible. You do that with @code{declare-function}. +In fact, @code{shell-mode} is used only in a function that executes +@code{(require 'shell)} before calling @code{shell-mode}, so +@code{shell-mode} will be defined properly at run-time. When you know +that such a warning does not indicate a real problem, it is good to +suppress the warning. That makes new warnings which might mean real +problems more visible. You do that with @code{declare-function}. All you need to do is add a @code{declare-function} statement before the first use of the function in question: @example -(declare-function gud-find-c-expr "gud.el" nil) +(declare-function shell-mode "shell" ()) @end example -This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the +This says that @code{shell-mode} is defined in @file{shell.el} (the @samp{.el} can be omitted). The compiler takes for granted that that file really defines the function, and does not check. The optional third argument specifies the argument list of -@code{gud-find-c-expr}. In this case, it takes no arguments +@code{shell-mode}. In this case, it takes no arguments (@code{nil} is different from not specifying a value). In other cases, this might be something like @code{(file &optional overwrite)}. You don't have to specify the argument list, but if you do the byte compiler can check that the calls match the declaration. @defmac declare-function function file &optional arglist fileonly -Tell the byte compiler to assume that @var{function} is defined, with -arguments @var{arglist}, and that the definition should come from the -file @var{file}. @var{fileonly} non-@code{nil} means only check that +Tell the byte compiler to assume that @var{function} is defined in the +file @var{file}. The optional third argument @var{arglist} is either +@code{t}, meaning the argument list is unspecified, or a list of +formal parameters in the same style as @code{defun}. An omitted +@var{arglist} defaults to @code{t}, not @code{nil}; this is atypical +behavior for omitted arguments, and it means that to supply a fourth +but not third argument one must specify @code{t} for the third-argument +placeholder instead of the usual @code{nil}. The optional fourth +argument @var{fileonly} non-@code{nil} means check only that @var{file} exists, not that it actually defines @var{function}. @end defmac diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index 8389c214707..4607bb0a0d1 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -268,18 +268,43 @@ under the property @code{hash-table-test}; the property value's form is @code{(@var{test-fn} @var{hash-fn})}. @end defun -@defun sxhash obj +@defun sxhash-equal obj This function returns a hash code for Lisp object @var{obj}. This is an integer which reflects the contents of @var{obj} and the other Lisp objects it points to. -If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash -@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer. +If two objects @var{obj1} and @var{obj2} are @code{equal}, then +@code{(sxhash-equal @var{obj1})} and @code{(sxhash-equal @var{obj2})} +are the same integer. -If the two objects are not equal, the values returned by @code{sxhash} -are usually different, but not always; once in a rare while, by luck, -you will encounter two distinct-looking objects that give the same -result from @code{sxhash}. +If the two objects are not @code{equal}, the values returned by +@code{sxhash-equal} are usually different, but not always; once in a +rare while, by luck, you will encounter two distinct-looking objects +that give the same result from @code{sxhash-equal}. + +@b{Common Lisp note:} In Common Lisp a similar function is called +@code{sxhash}. Emacs provides this name as a compatibility alias for +@code{sxhash-equal}. +@end defun + +@defun sxhash-eq obj +This function returns a hash code for Lisp object @var{obj}. Its +result reflects identity of @var{obj}, but not its contents. + +If two objects @var{obj1} and @var{obj2} are @code{eq}, then +@code{(xhash @var{obj1})} and @code{(xhash @var{obj2})} are the same +integer. +@end defun + +@defun sxhash-eql obj +This function returns a hash code for Lisp object @var{obj} suitable +for @code{eql} comparison. I.e. it reflects identity of @var{obj} +except for the case where the object is a float number, in which case +hash code is generated for the value. + +If two objects @var{obj1} and @var{obj2} are @code{eql}, then +@code{(xhash @var{obj1})} and @code{(xhash @var{obj2})} are the same +integer. @end defun This example creates a hash table whose keys are strings that are @@ -289,7 +314,7 @@ compared case-insensitively. (defun case-fold-string= (a b) (eq t (compare-strings a nil nil b nil nil t))) (defun case-fold-string-hash (a) - (sxhash (upcase a))) + (sxhash-equal (upcase a))) (define-hash-table-test 'case-fold 'case-fold-string= 'case-fold-string-hash) @@ -302,7 +327,7 @@ predefined test value @code{equal}. The keys can be any Lisp object, and equal-looking objects are considered the same key. @example -(define-hash-table-test 'contents-hash 'equal 'sxhash) +(define-hash-table-test 'contents-hash 'equal 'sxhash-equal) (make-hash-table :test 'contents-hash) @end example diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index b945e438f55..1bb2c7c4d08 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -332,15 +332,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 ‘ -@itemx ` -(left single quotation mark and grave accent) both stand for a left quote. +@item ` +(grave accent) stands for a left quote. This generates a left single quotation mark, an apostrophe, or a grave accent depending on the value of @code{text-quoting-style}. -@item ’ -@itemx ' -(right single quotation mark and apostrophe) both stand for a right quote. +@item ' +(apostrophe) stands for a right quote. This generates a right single quotation mark or an apostrophe depending on the value of @code{text-quoting-style}. @@ -361,7 +359,8 @@ should use for single quotes in the wording of help and messages. If the variable's value is @code{curve}, the style is @t{‘like this’} with curved single quotes. If the value is @code{straight}, the style is @t{'like this'} with straight -apostrophes. If the value is @code{grave}, the style is @t{`like +apostrophes. If the value is @code{grave}, +quotes are not translated and the style is @t{`like this'} with grave accent and apostrophe, the standard style before Emacs version 25. The default value @code{nil} acts like @code{curve} if curved single quotes are displayable, and diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 41064df5a28..fedef3d7f46 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -66,6 +66,16 @@ into the dumped Emacs. If you port Emacs to a new operating system, and are not able to implement dumping, then Emacs must load @file{loadup.el} each time it starts. +@cindex build details +@cindex deterministic build +@cindex @option{--disable-build-details} option to @command{configure} + By default the dumped @file{emacs} executable records details such +as the build time and host name. Use the +@option{--disable-build-details} option of @command{configure} to +suppress these details, so that building and installing Emacs twice +from the same sources is more likely to result in identical copies of +Emacs. + @cindex @file{site-load.el} You can specify additional files to preload by writing a library named @file{site-load.el} that loads them. You may need to rebuild Emacs diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 0f42d4d8a7f..2f84aeee39e 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -494,7 +494,8 @@ giving a prefix argument makes @var{here} non-@code{nil}. @defvar emacs-build-time The value of this variable indicates the time at which Emacs was built. It is a list of four integers, like the value of -@code{current-time} (@pxref{Time of Day}). +@code{current-time} (@pxref{Time of Day}), or is @code{nil} +if the information is not available. @example @group diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 2641ad0b6aa..29f2c422cb2 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -350,7 +350,21 @@ lots of bindings; for just a few, the sparse keymap is better. @end defun @defun copy-keymap keymap -This function returns a copy of @var{keymap}. Any keymaps that +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 +changes, you should use map inheritance rather than copying. +I.e., something like: + +@example +@group +(let ((map (make-sparse-keymap))) + (set-keymap-parent map <theirmap>) + (define-key map ...) + ...) +@end group +@end example + +When performing @code{copy-keymap}, any keymaps that appear directly as bindings in @var{keymap} are also copied recursively, and so on to any number of levels. However, recursive copying does not take place when the definition of a character is a symbol whose function diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 1468603e508..44ce719bc1f 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -161,8 +161,8 @@ load was done for the sake of @code{autoload}, any function definitions made during the loading are undone. @kindex file-error -If @code{load} can't find the file to load, then normally it signals the -error @code{file-error} (with @samp{Cannot open load file +If @code{load} can't find the file to load, then normally it signals a +@code{file-error} (with @samp{Cannot open load file @var{filename}}). But if @var{missing-ok} is non-@code{nil}, then @code{load} just returns @code{nil}. diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 1fa2536db4e..8d5347556e4 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -170,6 +170,23 @@ non-@code{nil}, then the string that is returned includes whatever text properties were present in the minibuffer. Otherwise all the text properties are stripped when the value is returned. +@vindex minibuffer-prompt-properties +The text properties in @code{minibuffer-prompt-properties} are applied +to the prompt. By default, this property list defines a face to use +for the prompt. This face, if present, is applied to the end of the +face list and merged before display. + +If the user wants to completely control the look of the prompt, the +most convenient way to do that is to specify the @code{default} face +at the end of all face lists. For instance: + +@lisp +(read-from-minibuffer + (concat + (propertize "Bold" 'face '(bold default)) + (propertize " and normal: " 'face '(default)))) +@end lisp + If the argument @var{inherit-input-method} is non-@code{nil}, then the minibuffer inherits the current input method (@pxref{Input Methods}) and the setting of @code{enable-multibyte-characters} (@pxref{Text diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 7bbb5e6f583..3d3122a68ea 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -445,7 +445,8 @@ other packages would interfere with them. Each major mode should have a normal @dfn{mode hook} named @code{@var{modename}-mode-hook}. The very last thing the major mode command should do is to call @code{run-mode-hooks}. This runs the normal -hook @code{change-major-mode-after-body-hook}, the mode hook, +hook @code{change-major-mode-after-body-hook}, the mode hook, the +function @code{hack-local-variables} (when the buffer is visiting a file), and then the normal hook @code{after-change-major-mode-hook}. @xref{Mode Hooks}. @@ -525,11 +526,12 @@ the buffer based on information in the file name or in the file itself. It also processes local variables specified in the file text. @deffn Command normal-mode &optional find-file -This function establishes the proper major mode and buffer-local variable -bindings for the current buffer. First it calls @code{set-auto-mode} -(see below), then it runs @code{hack-local-variables} to parse, and -bind or evaluate as appropriate, the file's local variables -(@pxref{File Local Variables}). +This function establishes the proper major mode and buffer-local +variable bindings for the current buffer. It calls +@code{set-auto-mode} (see below). As of Emacs 26.1, it no longer +runs @code{hack-local-variables}, this now being done in +@code{run-mode-hooks} at the initialization of major modes +(@pxref{Mode Hooks}). If the @var{find-file} argument to @code{normal-mode} is non-@code{nil}, @code{normal-mode} assumes that the @code{find-file} function is calling @@ -543,9 +545,9 @@ If you run @code{normal-mode} interactively, the argument @var{find-file} is normally @code{nil}. In this case, @code{normal-mode} unconditionally processes any file local variables. -The function calls @code{set-auto-mode} to choose a major mode. If this -does not specify a mode, the buffer stays in the major mode determined -by the default value of @code{major-mode} (see below). +The function calls @code{set-auto-mode} to choose and set a major +mode. If this does not specify a mode, the buffer stays in the major +mode determined by the default value of @code{major-mode} (see below). @cindex file mode specification error @code{normal-mode} uses @code{condition-case} around the call to the @@ -555,16 +557,17 @@ mode specification error}, followed by the original error message. @defun set-auto-mode &optional keep-mode-if-same @cindex visited file mode - This function selects the major mode that is appropriate for the -current buffer. It bases its decision (in order of precedence) on the -@w{@samp{-*-}} line, on any @samp{mode:} local variable near the end of -a file, on the @w{@samp{#!}} line (using @code{interpreter-mode-alist}), -on the text at the beginning of the buffer (using -@code{magic-mode-alist}), and finally on the visited file name (using -@code{auto-mode-alist}). @xref{Choosing Modes, , How Major Modes are -Chosen, emacs, The GNU Emacs Manual}. If @code{enable-local-variables} -is @code{nil}, @code{set-auto-mode} does not check the @w{@samp{-*-}} -line, or near the end of the file, for any mode tag. + This function selects and sets the major mode that is appropriate +for the current buffer. It bases its decision (in order of +precedence) on the @w{@samp{-*-}} line, on any @samp{mode:} local +variable near the end of a file, on the @w{@samp{#!}} line (using +@code{interpreter-mode-alist}), on the text at the beginning of the +buffer (using @code{magic-mode-alist}), and finally on the visited +file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How +Major Modes are Chosen, emacs, The GNU Emacs Manual}. If +@code{enable-local-variables} is @code{nil}, @code{set-auto-mode} does +not check the @w{@samp{-*-}} line, or near the end of the file, for +any mode tag. @vindex inhibit-local-variables-regexps There are some file types where it is not appropriate to scan the file @@ -749,7 +752,8 @@ The new mode has its own abbrev table, kept in the variable @item The new mode has its own mode hook, @code{@var{variant}-hook}. It runs this hook, after running the hooks of its ancestor modes, with -@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}. +@code{run-mode-hooks}, as the last thing it does, apart from running +any @code{:after-hook} form it may have. @xref{Mode Hooks}. @end itemize In addition, you can specify how to override other aspects of @@ -773,8 +777,9 @@ about the mode's hook, followed by the mode's keymap, at the end of this documentation string. If you omit @var{docstring}, @code{define-derived-mode} generates a documentation string. -The @var{keyword-args} are pairs of keywords and values. The values -are evaluated. The following keywords are currently supported: +The @var{keyword-args} are pairs of keywords and values. The values, +except for @code{:after-hook}'s, are evaluated. The following +keywords are currently supported: @table @code @item :syntax-table @@ -797,6 +802,15 @@ If this is specified, the value should be the customization group for this mode. (Not all major modes have one.) The command @code{customize-mode} uses this. @code{define-derived-mode} does @emph{not} automatically define the specified customization group. + +@item :after-hook +This optional keyword specifies a single Lisp form to evaluate as the +final act of the mode function, after the mode hooks have been run. +It should not be quoted. Since the form might be evaluated after the +mode function has terminated, it should not access any element of the +mode function's local state. An @code{:after-hook} form is useful for +setting up aspects of the mode which depend on the user's settings, +which in turn may have been changed in a mode hook. @end table Here is a hypothetical example: @@ -906,11 +920,15 @@ use the following functions to handle these conventions automatically. @defun run-mode-hooks &rest hookvars Major modes should run their mode hook using this function. It is similar to @code{run-hooks} (@pxref{Hooks}), but it also runs -@code{change-major-mode-after-body-hook} and -@code{after-change-major-mode-hook}. +@code{change-major-mode-after-body-hook}, @code{hack-local-variables} +(when the buffer is visiting a file) (@pxref{File Local Variables}), +and @code{after-change-major-mode-hook}. The last thing it does is to +evaluate any @code{:after-hook} forms declared by parent modes +(@pxref{Derived Modes}). When this function is called during the execution of a -@code{delay-mode-hooks} form, it does not run the hooks immediately. +@code{delay-mode-hooks} form, it does not run the hooks or +@code{hack-local-variables} or evaluate the forms immediately. Instead, it arranges for the next call to @code{run-mode-hooks} to run them. @end defun diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index e4581b3d68e..9f805c2c1d9 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -420,6 +420,18 @@ codepoint can have. @end example @end defun +@defun char-from-name string &optional ignore-case +This function returns the character whose Unicode name is @var{string}. +If @var{ignore-case} is non-@code{nil}, case is ignored in @var{string}. +This function returns @code{nil} if @var{string} does not name a character. + +@example +;; U+03A3 +(= (char-from-name "GREEK CAPITAL LETTER SIGMA") #x03A3) + @result{} t +@end example +@end defun + @defun get-byte &optional pos string This function returns the byte at character position @var{pos} in the current buffer. If the current buffer is unibyte, this is literally @@ -622,18 +634,21 @@ This function returns the value of @var{char}'s @var{propname} property. @result{} Nd @end group @group -;; U+2084 SUBSCRIPT FOUR -(get-char-code-property ?\u2084 'digit-value) +;; U+2084 +(get-char-code-property ?\N@{SUBSCRIPT FOUR@} + 'digit-value) @result{} 4 @end group @group -;; U+2155 VULGAR FRACTION ONE FIFTH -(get-char-code-property ?\u2155 'numeric-value) +;; U+2155 +(get-char-code-property ?\N@{VULGAR FRACTION ONE FIFTH@} + 'numeric-value) @result{} 0.2 @end group @group -;; U+2163 ROMAN NUMERAL FOUR -(get-char-code-property ?\u2163 'numeric-value) +;; U+2163 +(get-char-code-property ?\N@{ROMAN NUMERAL FOUR@} + 'numeric-value) @result{} 4 @end group @group diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 324593068d5..5e608bcc093 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -353,25 +353,32 @@ following text.) control characters, Emacs provides several types of escape syntax that you can use to specify non-@acronym{ASCII} text characters. +@enumerate +@item @cindex @samp{\} in character constant @cindex backslash in character constants @cindex unicode character escape - Firstly, you can specify characters by their Unicode values. -@code{?\u@var{nnnn}} represents a character with Unicode code point -@samp{U+@var{nnnn}}, where @var{nnnn} is (by convention) a hexadecimal -number with exactly four digits. The backslash indicates that the -subsequent characters form an escape sequence, and the @samp{u} -specifies a Unicode escape sequence. - - There is a slightly different syntax for specifying Unicode -characters with code points higher than @code{U+@var{ffff}}: -@code{?\U00@var{nnnnnn}} represents the character with code point -@samp{U+@var{nnnnnn}}, where @var{nnnnnn} is a six-digit hexadecimal -number. The Unicode Standard only defines code points up to -@samp{U+@var{10ffff}}, so if you specify a code point higher than -that, Emacs signals an error. - - Secondly, you can specify characters by their hexadecimal character +You can specify characters by their Unicode names, if any. +@code{?\N@{@var{NAME}@}} represents the Unicode character named +@var{NAME}. Thus, @samp{?\N@{LATIN SMALL LETTER A WITH GRAVE@}} is +equivalent to @code{?à } and denotes the Unicode character U+00E0. To +simplify entering multi-line strings, you can replace spaces in the +names by non-empty sequences of whitespace (e.g., newlines). + +@item +You can specify characters by their Unicode values. +@code{?\N@{U+@var{X}@}} represents a character with Unicode code point +@var{X}, where @var{X} is a hexadecimal number. Also, +@code{?\u@var{xxxx}} and @code{?\U@var{xxxxxxxx}} represent code +points @var{xxxx} and @var{xxxxxxxx}, respectively, where each @var{x} +is a single hexadecimal digit. For example, @code{?\N@{U+E0@}}, +@code{?\u00e0} and @code{?\U000000E0} are all equivalent to @code{?à } +and to @samp{?\N@{LATIN SMALL LETTER A WITH GRAVE@}}. The Unicode +Standard defines code points only up to @samp{U+@var{10ffff}}, so if +you specify a code point higher than that, Emacs signals an error. + +@item +You can specify characters by their hexadecimal character codes. A hexadecimal escape sequence consists of a backslash, @samp{x}, and the hexadecimal character code. Thus, @samp{?\x41} is the character @kbd{A}, @samp{?\x1} is the character @kbd{C-a}, and @@ -379,14 +386,17 @@ the character @kbd{A}, @samp{?\x1} is the character @kbd{C-a}, and You can use any number of hex digits, so you can represent any character code in this way. +@item @cindex octal character code - Thirdly, you can specify characters by their character code in +You can specify characters by their character code in octal. An octal escape sequence consists of a backslash followed by up to three octal digits; thus, @samp{?\101} for the character @kbd{A}, @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the character @kbd{C-b}. Only characters up to octal code 777 can be specified this way. +@end enumerate + These escape sequences may also be used in strings. @xref{Non-ASCII in Strings}. @@ -1400,6 +1410,9 @@ editing. * Window Configuration Type:: Recording the way a frame is subdivided. * Frame Configuration Type:: Recording the status of all frames. * Process Type:: A subprocess of Emacs running on the underlying OS. +* Thread Type:: A thread of Emacs Lisp execution. +* Mutex Type:: An exclusive lock for thread synchronization. +* Condition Variable Type:: Condition variable for thread synchronization. * Stream Type:: Receive or send characters. * Keymap Type:: What function a keystroke invokes. * Overlay Type:: How an overlay is represented. @@ -1615,6 +1628,63 @@ giving the name of the process: return information about, send input or signals to, and receive output from processes. +@node Thread Type +@subsection Thread Type + + A @dfn{thread} in Emacs represents a separate thread of Emacs Lisp +execution. It runs its own Lisp program, has its own current buffer, +and can have subprocesses locked to it, i.e.@: subprocesses whose +output only this thread can accept. @xref{Threads}. + + Thread objects have no read syntax. They print in hash notation, +giving the name of the thread (if it has been given a name) or its +address in core: + +@example +@group +(all-threads) + @result{} (#<thread 0176fc40>) +@end group +@end example + +@node Mutex Type +@subsection Mutex Type + + A @dfn{mutex} is an exclusive lock that threads can own and disown, +in order to synchronize between them. @xref{Mutexes}. + + Mutex objects have no read syntax. They print in hash notation, +giving the name of the mutex (if it has been given a name) or its +address in core: + +@example +@group +(make-mutex "my-mutex") + @result{} #<mutex my-mutex> +(make-mutex) + @result{} #<mutex 01c7e4e0> +@end group +@end example + +@node Condition Variable Type +@subsection Condition Variable Type + + A @dfn{condition variable} is a device for a more complex thread +synchronization than the one supported by a mutex. A thread can wait +on a condition variable, to be woken up when some other thread +notifies the condition. + + Condition variable objects have no read syntax. They print in hash +notation, giving the name of the condition variable (if it has been +given a name) or its address in core: + +@example +@group +(make-condition-variable (make-mutex)) + @result{} #<condvar 01c45ae8> +@end group +@end example + @node Stream Type @subsection Stream Type @@ -1820,6 +1890,9 @@ with references to further information. @item commandp @xref{Interactive Call, commandp}. +@item condition-variable-p +@xref{Condition Variables, condition-variable-p}. + @item consp @xref{List-related Predicates, consp}. @@ -1865,6 +1938,9 @@ with references to further information. @item markerp @xref{Predicates on Markers, markerp}. +@item mutexp +@xref{Mutexes, mutexp}. + @item wholenump @xref{Predicates on Numbers, wholenump}. @@ -1898,6 +1974,9 @@ with references to further information. @item syntax-table-p @xref{Syntax Tables, syntax-table-p}. +@item threadp +@xref{Basic Thread Functions, threadp}. + @item vectorp @xref{Vectors, vectorp}. @@ -1915,6 +1994,15 @@ with references to further information. @item string-or-null-p @xref{Predicates for Strings, string-or-null-p}. + +@item threadp +@xref{Basic Thread Functions, threadp}. + +@item mutexp +@xref{Mutexes, mutexp}. + +@item condition-variable-p +@xref{Condition Variables, condition-variable-p}. @end table The most general way to check the type of an object is to call the @@ -1928,11 +2016,12 @@ types. In most cases, it is more convenient to use type predicates than This function returns a symbol naming the primitive type of @var{object}. The value is one of the symbols @code{bool-vector}, @code{buffer}, @code{char-table}, @code{compiled-function}, -@code{cons}, @code{finalizer}, @code{float}, @code{font-entity}, -@code{font-object}, @code{font-spec}, @code{frame}, @code{hash-table}, -@code{integer}, @code{marker}, @code{overlay}, @code{process}, -@code{string}, @code{subr}, @code{symbol}, @code{vector}, -@code{window}, or @code{window-configuration}. +@code{condition-variable}, @code{cons}, @code{finalizer}, +@code{float}, @code{font-entity}, @code{font-object}, +@code{font-spec}, @code{frame}, @code{hash-table}, @code{integer}, +@code{marker}, @code{mutex}, @code{overlay}, @code{process}, +@code{string}, @code{subr}, @code{symbol}, @code{thread}, +@code{vector}, @code{window}, or @code{window-configuration}. @example (type-of 1) diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 9fa27113d04..1a45eac04e3 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -112,8 +112,8 @@ compiled into the Emacs executable when it was built. It runs the normal hook @code{before-init-hook}. @item -If appropriate, it creates a graphical frame. This is not done if the -options @samp{--batch} or @samp{--daemon} were specified. +If appropriate, it creates a graphical frame. This is not done in +batch (noninteractive) or daemon mode. @item It initializes the initial frame's faces, and sets up the menu bar @@ -256,10 +256,10 @@ options were specified. @c last few bits of command-line-1 are not done in batch mode. @item -If the option @code{--daemon} was specified, it calls -@code{server-start}, and on Posix systems also detaches from the -controlling terminal. @xref{Emacs Server,,, emacs, The GNU Emacs -Manual}. +If a daemon was requested, it calls @code{server-start}. +(On Posix systems, if a background daemon was requested, it then +detaches from the controlling terminal.) @xref{Emacs +Server,,, emacs, The GNU Emacs Manual}. @item If started by the X session manager, it calls @@ -337,7 +337,10 @@ Do not display a splash screen. Run without an interactive terminal. @xref{Batch Mode}. @item --daemon -Do not initialize any display; just start a server in the background. +@itemx --old-daemon +@itemx --new-daemon +Do not initialize any display; just start a server. +(An ``old-style'' daemon automatically runs in the background.) @item --no-init-file @itemx -q @@ -904,9 +907,6 @@ A GNU (glibc-based) system with a FreeBSD kernel. @item hpux Hewlett-Packard HPUX operating system. -@item irix -Silicon Graphics Irix system. - @item nacl Google Native Client (@acronym{NaCl}) sandboxing system. @@ -1333,7 +1333,13 @@ omitted or @code{nil}, the conversion uses Emacs's default time zone. If it is @code{t}, the conversion uses Universal Time. If it is @code{wall}, the conversion uses the system wall clock time. If it is a string, the conversion uses the time zone rule equivalent to setting -@env{TZ} to that string. +@env{TZ} to that string. If it is an integer @var{offset}, the +conversion uses a fixed time zone with the given offset and a numeric +abbreviation on POSIX-compatible platforms and an unspecified abbreviation +on MS-Windows. If it is a list (@var{offset} @var{abbr}), where +@var{offset} is an integer number of seconds east of Universal Time +and @var{abbr} is a string, the conversion uses a fixed time zone with +the given offset and abbreviation. @defun current-time-zone &optional time zone @cindex time zone, current @@ -1431,10 +1437,6 @@ yourself before you call @code{encode-time}. The optional argument @var{zone} defaults to the current time zone rule. @xref{Time Zone Rules}. -In addition to the usual time zone rule values, it can also be a list -(as you would get from @code{current-time-zone}) or an integer (as -from @code{decode-time}), applied without any further alteration for -daylight saving time. If you pass more than seven arguments to @code{encode-time}, the first six are used as @var{seconds} through @var{year}, the last argument is @@ -1530,6 +1532,8 @@ fewer digits, use @samp{%3N} for milliseconds, @samp{%6N} for microseconds, etc. Any excess digits are discarded, without rounding. @item %p This stands for @samp{AM} or @samp{PM}, as appropriate. +@item %q +This stands for the calendar quarter (1--4). @item %r This is a synonym for @samp{%I:%M:%S %p}. @item %R @@ -1889,6 +1893,12 @@ one of these functions; the arrival of the specified time will not cause anything special to happen. @end defun +@findex timer-list +The @code{timer-list} command lists all the currently active timers. +There's only one command available in the buffer displayed: @kbd{c} +(@code{timer-list-cancel}) that will cancel the timer on the line +under point. + @node Idle Timers @section Idle Timers @cindex idle timers @@ -2265,14 +2275,16 @@ The variable is always local to the current terminal, and cannot be buffer-local. @xref{Multiple Terminals}. @end defvar -You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables: +You can specify which keysyms Emacs should use for the Control, Meta, +Alt, Hyper, and Super modifiers by setting these variables: -@defvar x-alt-keysym +@defvar x-ctrl-keysym +@defvarx x-alt-keysym @defvarx x-meta-keysym @defvarx x-hyper-keysym @defvarx x-super-keysym -The name of the keysym that should stand for the Alt modifier -(respectively, for Meta, Hyper, and Super). For example, here is +The name of the keysym that should stand for the Control modifier +(respectively, for Alt, Meta, Hyper, and Super). For example, here is how to swap the Meta and Alt modifiers within Emacs: @lisp (setq x-alt-keysym 'meta) diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index b6133dc7e2d..a56ab5ef307 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -593,10 +593,12 @@ any buffer, whether or not it is currently displayed in some window. @deffn Command move-to-window-line count This function moves point with respect to the text currently displayed in the selected window. It moves point to the beginning of the screen -line @var{count} screen lines from the top of the window. If -@var{count} is negative, that specifies a position -@w{@minus{}@var{count}} lines from the bottom (or the last line of the -buffer, if the buffer ends above the specified screen position). +line @var{count} screen lines from the top of the window; zero means +the topmost line. If @var{count} is negative, that specifies a +position @w{@minus{}@var{count}} lines from the bottom (or the last +line of the buffer, if the buffer ends above the specified screen +position); thus, @var{count} of -1 specifies the last fully visible +screen line of the window. If @var{count} is @code{nil}, then point moves to the beginning of the line in the middle of the window. If the absolute value of @var{count} @@ -607,8 +609,8 @@ location onto the screen. In an interactive call, @var{count} is the numeric prefix argument. -The value returned is the window line number point has moved to, with -the top line in the window numbered 0. +The value returned is the screen line number point has moved to, +relative to the top line of the window. @end deffn @vindex move-to-window-group-line-function diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 950dc9c6d49..064934cc662 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -512,20 +512,17 @@ inputinput@point{} @end smallexample For example, the @code{shell-command-on-region} command uses -@code{call-process-region} in a manner similar to this: +@code{call-shell-region} in a manner similar to this: @smallexample @group -(call-process-region +(call-shell-region start end - shell-file-name ; @r{name of program} + command ; @r{shell command} nil ; @r{do not delete region} - buffer ; @r{send output to @code{buffer}} - nil ; @r{no redisplay during output} - "-c" command) ; @r{arguments for the shell} + buffer) ; @r{send output to @code{buffer}} @end group @end smallexample -@c It actually uses shell-command-switch, but no need to mention that here. @end defun @defun call-process-shell-command command &optional infile destination display @@ -545,6 +542,15 @@ convention allowed passing any number of additional arguments after supported, but strongly discouraged. @end defun +@defun call-shell-region start end command &optional delete destination +This function sends the text from @var{start} to @var{end} as +standard input to an inferior shell running @var{command}. This function +is similar than @code{call-process-region}, with process being a shell. +The arguments @code{delete}, @code{destination} and the return value +are like in @code{call-process-region}. +Note that this function doesn't accept additional arguments. +@end defun + @defun shell-command-to-string command This function executes @var{command} (a string) as a shell command, then returns the command's output as a string. @@ -1394,6 +1400,7 @@ Emacs tries to read it. * Filter Functions:: Filter functions accept output from the process. * Decoding Output:: Filters can get unibyte or multibyte strings. * Accepting Output:: How to wait until process output arrives. +* Processes and Threads:: How processes and threads interact. @end menu @node Process Buffers @@ -1785,6 +1792,35 @@ got output from @var{process}, or from any process if @var{process} is arrived. @end defun +@node Processes and Threads +@subsection Processes and Threads +@cindex processes, threads + + Because threads were a relatively late addition to Emacs Lisp, and +due to the way dynamic binding was sometimes used in conjunction with +@code{accept-process-output}, by default a process is locked to the +thread that created it. When a process is locked to a thread, output +from the process can only be accepted by that thread. + + A Lisp program can specify to which thread a process is to be +locked, or instruct Emacs to unlock a process, in which case its +output can be processed by any thread. Only a single thread will wait +for output from a given process at one time---once one thread begins +waiting for output, the process is temporarily locked until +@code{accept-process-output} or @code{sit-for} returns. + + If the thread exits, all the processes locked to it are unlocked. + +@defun process-thread process +Return the thread to which @var{process} is locked. If @var{process} +is unlocked, return @code{nil}. +@end defun + +@defun set-process-thread process thread +Set the locking thread of @var{process} to @var{thread}. @var{thread} +may be @code{nil}, in which case the process is unlocked. +@end defun + @node Sentinels @section Sentinels: Detecting Process Status Changes @cindex process sentinel @@ -1964,6 +2000,13 @@ shell process to avoid querying: @end smallexample @end defun +@defopt confirm-kill-processes +If this user option is set to @code{t} (the default), then Emacs asks +for confirmation before killing processes on exit. If it is +@code{nil}, Emacs kills processes without confirmation, i.e., the +query flag of all processes is ignored. +@end defopt + @node System Processes @section Accessing Other Processes @cindex system processes @@ -2288,7 +2331,8 @@ associated with any buffer. The arguments @var{host} and @var{service} specify where to connect to; @var{host} is the host name (a string), and @var{service} is the name of -a defined network service (a string) or a port number (an integer). +a defined network service (a string) or a port number (an integer like +@code{80} or an integer string like @code{"80"}). The remaining arguments @var{parameters} are keyword/argument pairs that are mainly relevant to encrypted connections: @@ -2512,8 +2556,9 @@ connecting to that address will be accepted. @item :service @var{service} @var{service} specifies a port number to connect to; or, for a server, -the port number to listen on. It should be a service name that -translates to a port number, or an integer specifying the port number +the port number to listen on. It should be a service name like +@samp{"http"} that translates to a port number, or an integer like @samp{80} +or an integer string like @samp{"80"} that specifies the port number directly. For a server, it can also be @code{t}, which means to let the system select an unused port number. @@ -2525,6 +2570,12 @@ automatically for the given @var{host} and @var{service}. ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6, respectively. +@item :use-external-socket @var{use-external-socket} +If @var{use-external-socket} is non-@code{nil} use any sockets passed +to Emacs on invocation instead of allocating one. This is used by the +Emacs server code to allow on-demand socket activation. If Emacs +wasn't passed a socket, this option is silently ignored. + @item :local @var{local-address} For a server process, @var{local-address} is the address to listen on. It overrides @var{family}, @var{host} and @var{service}, so you @@ -2575,8 +2626,33 @@ without waiting for the connection to complete. When the connection succeeds or fails, Emacs will call the sentinel function, with a second argument matching @code{"open"} (if successful) or @code{"failed"}. The default is to block, so that -@code{make-network-process} does not return until the connection -has succeeded or failed. +@code{make-network-process} does not return until the connection has +succeeded or failed. + +If you're setting up an asynchronous TLS connection, you have to also +provide the @code{:tls-parameters} parameter (see below). + +Depending on the capabilities of Emacs, how asynchronous +@code{:nowait} is may vary. The three elements that may (or may not) +be done asynchronously are domain name resolution, socket setup, and +(for TLS connections) TLS negotiation. + +Many functions that interact with process objects, (for instance, +@code{process-datagram-address}) rely on them at least having a socket +before they can return a useful value. These functions will block +until the socket has achieved the desired status. The recommended way +of interacting with asynchronous sockets is to place a sentinel on the +process, and not try to interact with it before it has changed status +to @samp{"run"}. That way, none of these functions will block. + +@item :tls-parameters +When opening a TLS connection, this should be where the first element +is the TLS type (which should either be @code{gnutls-x509pki} or +@code{gnutls-anon}, and the remaining elements should form a keyword +list acceptable for @code{gnutls-boot}. (This keyword list can be +obtained from the @code{gnutls-boot-parameters} function.) The TLS +connection will then be negotiated after completing the connection to +the host. @item :stop @var{stopped} If @var{stopped} is non-@code{nil}, start the network connection or diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 579460f3227..4b97aae8cac 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -1838,6 +1838,14 @@ Answer this question and all subsequent questions in the series with @item backup Move back to the previous place that a question was asked about. +@item undo +Undo last replacement and move back to the place where that +replacement was performed. + +@item undo-all +Undo all replacements and move back to the place where the first +replacement was performed. + @item edit Enter a recursive edit to deal with this question---instead of any other action that would normally be taken. diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 920399586c5..421308665db 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -576,6 +576,21 @@ element of @var{sequence}. The returned value is a list. @end example @end defun +@defun seq-map-indexed function sequence + This function returns the result of applying @var{function} to each +element of @var{sequence} and its index within @var{seq}. The +returned value is a list. + +@example +@group +(seq-map-indexed (lambda (elt idx) + (list idx elt)) + '(a b c)) +@result{} ((0 a) (b 1) (c 2)) +@end group +@end example +@end defun + @defun seq-mapn function &rest sequences This function returns the result of applying @var{function} to each element of @var{sequences}. The arity (@pxref{What Is a Function, @@ -748,6 +763,18 @@ according to @var{function}, a function of two arguments that returns non-@code{nil} if the first argument should sort before the second. @end defun +@defun seq-sort-by function predicate sequence + This function is similar to @code{seq-sort}, but the elements of +@var{sequence} are transformed by applying @var{function} on them +before being sorted. @var{function} is a function of one argument. + +@example +(seq-sort-by #'seq-length #'> ["a" "ab" "abc"]) +@result{} ["abc" "ab" "a"] +@end example +@end defun + + @defun seq-contains sequence elt &optional function This function returns the first element in @var{sequence} that is equal to @var{elt}. If the optional argument @var{function} is non-@code{nil}, @@ -1010,6 +1037,26 @@ followed by a variable name to be bound to the rest of @end example @end defmac +@defun seq-random-elt sequence + This function returns an element of @var{sequence} taken at random. + +@example +@group +(seq-random-elt [1 2 3 4]) +@result{} 3 +(seq-random-elt [1 2 3 4]) +@result{} 2 +(seq-random-elt [1 2 3 4]) +@result{} 4 +(seq-random-elt [1 2 3 4]) +@result{} 2 +(seq-random-elt [1 2 3 4]) +@result{} 1 +@end group +@end example + + If @var{sequence} is empty, this function signals an error. +@end defun @node Arrays @section Arrays diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi index 41bc71e6aea..757e0e831be 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -639,7 +639,7 @@ spacing between calls. This function outputs a newline to @var{stream}. The name stands for ``terminate print''. If @var{ensure} is non-@code{nil} no newline is printed if @var{stream} is already at the beginning of a line. Note in this -case @var{stream} can not be a function and an error is signalled if +case @var{stream} can not be a function and an error is signaled if it is. This function returns @code{t} if a newline is printed. @end defun diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 3c764da4e2b..ff108511f23 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -620,6 +620,14 @@ If your system does not support a locale environment, this function behaves like @code{string-lessp}. @end defun +@defun string-version-lessp string1 string2 +This function compares strings lexicographically, except it treats +sequences of numerical characters as if they comprised a base-ten +number, and then compares the numbers. So @samp{foo2.png} is +``smaller'' than @samp{foo12.png} according to this predicate, even if +@samp{12} is lexicographically ``smaller'' than @samp{2}. +@end defun + @defun string-prefix-p string1 string2 &optional ignore-case This function returns non-@code{nil} if @var{string1} is a prefix of @var{string2}; i.e., if @var{string2} starts with @var{string1}. If @@ -813,16 +821,16 @@ arguments @var{objects} are the computed values to be formatted. The characters in @var{string}, other than the format specifications, are copied directly into the output, including their text properties, -if any. +if any. Any text properties of the format specifications are copied +to the produced string representations of the argument @var{objects}. @end defun @defun format-message string &rest objects @cindex curved quotes @cindex curly quotes This function acts like @code{format}, except it also converts any -curved single quotes in @var{string} as per the value of -@code{text-quoting-style}, and treats grave accent (@t{`}) and -apostrophe (@t{'}) as if they were curved single quotes. +grave accents (@t{`}) and apostrophes (@t{'}) in @var{string} as per the +value of @code{text-quoting-style}. A format that quotes with grave accents and apostrophes @t{`like this'} typically generates curved quotes @t{‘like this’}. In diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index 19782d0fbde..f81c1643c21 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -331,10 +331,10 @@ alternative ``c'' comment style. For a two-character comment delimiter, @samp{c} on either character makes it of style ``c''. @item -@samp{n} on a comment delimiter character specifies -that this kind of comment can be nested. For a two-character -comment delimiter, @samp{n} on either character makes it -nestable. +@samp{n} on a comment delimiter character specifies that this kind of +comment can be nested. Inside such a comment, only comments of the +same style will be recognized. For a two-character comment delimiter, +@samp{n} on either character makes it nestable. @cindex comment style Emacs supports several comment styles simultaneously in any one syntax @@ -791,10 +791,10 @@ Hooks}). @subsection Parser State @cindex parser state - A @dfn{parser state} is a list of ten elements describing the state -of the syntactic parser, after it parses the text between a specified -starting point and a specified end point in the buffer. Parsing -functions such as @code{syntax-ppss} + A @dfn{parser state} is a list of (currently) eleven elements +describing the state of the syntactic parser, after it parses the text +between a specified starting point and a specified end point in the +buffer. Parsing functions such as @code{syntax-ppss} @ifnottex (@pxref{Position Parse}) @end ifnottex @@ -851,15 +851,20 @@ position where the string began. When outside of strings and comments, this element is @code{nil}. @item -Internal data for continuing the parsing. The meaning of this -data is subject to change; it is used if you pass this list -as the @var{state} argument to another call. +The list of the positions of the currently open parentheses, starting +with the outermost. + +@item +When the last buffer position scanned was the (potential) first +character of a two character construct (comment delimiter or +escaped/char-quoted character pair), the @var{syntax-code} +(@pxref{Syntax Table Internals}) of that position. Otherwise +@code{nil}. @end enumerate Elements 1, 2, and 6 are ignored in a state which you pass as an -argument to continue parsing, and elements 8 and 9 are used only in -trivial cases. Those elements are mainly used internally by the -parser code. +argument to continue parsing. Elements 9 and 10 are mainly used +internally by the parser code. One additional piece of useful information is available from a parser state using this function: @@ -898,10 +903,11 @@ The depth starts at 0, or at whatever is given in @var{state}. If the fourth argument @var{stop-before} is non-@code{nil}, parsing stops when it comes to any character that starts a sexp. If -@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the -start of a comment. If @var{stop-comment} is the symbol -@code{syntax-table}, parsing stops after the start of a comment or a -string, or the end of a comment or a string, whichever comes first. +@var{stop-comment} is non-@code{nil}, parsing stops after the start of +an unnested comment. If @var{stop-comment} is the symbol +@code{syntax-table}, parsing stops after the start of an unnested +comment or a string, or after the end of an unnested comment or a +string, whichever comes first. If @var{state} is @code{nil}, @var{start} is assumed to be at the top level of parenthesis structure, such as the beginning of a function diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index b6635ddb0a0..0da34d14f24 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -2364,6 +2364,83 @@ already indented, it calls @code{completion-at-point} to complete the text at point (@pxref{Completion in Buffers}). @end defopt +@cindex literate programming +@cindex multi-mode indentation + Some major modes need to support embedded regions of text whose +syntax belongs to a different major mode. Examples include +@dfn{literate programming} source files that combine documentation and +snippets of source code, Yacc/Bison programs that include snippets of +plain C code, etc. To correctly indent the embedded chunks, the major +mode needs to delegate the indentation to another mode's indentation +engine (e.g., call @code{c-indent-defun} for C code or +@code{python-indent-line} for Python), while providing it with some +context to guide the indentation. The following facilities support +such multi-mode indentation. + +@defvar prog-indentation-context +This variable, when non-@code{nil}, holds the indentation context for +the sub-mode's indentation engine provided by the superior major mode. +The value should be a list of the form @code{(@var{first-column} +@w{(@var{start} . @var{end})} @code{prev-chunk})}. The members of the +list have the following meaning: + +@table @var +@item first-column +The column to be used for top-level constructs. This replaces the +default value of the top-level column used by the sub-mode, usually +zero. +@item start +@itemx end +The region of the code chunk to be indented by the sub-mode. The +value of @var{end} can be @code{nil}, which stands for the value of +@code{point-max}. +@item prev-chunk +If this is non-@code{nil}, it should provide the sub-mode's +indentation engine with a virtual context of the code chunk. Valid +values include: + +@itemize @minus +@item +A string whose contents is the text the sub-mode's indentation engine +should consider to precede the code chunk. The sub-mode's indentation +engine can add text properties to that string, to be reused in +repeated calls with the same string, thus using it as a cache. An +example where this is useful is code chunks that need to be indented +as function bodies, but lack the function's preamble---the string +could then include that missing preamble. +@item +A function. It is expected to be called with the start position of +the current chunk, and should return a cons cell +@w{@code{(@var{prev-start} . @var{prev-end})}} that specifies the +region of the previous code chunk, or @code{nil} if there is no previous +chunk. This is useful in literate-programming sources, where code is +split into chunks, and correct indentation needs to access previous +chunks. +@end itemize +@end table +@end defvar + +The following convenience functions should be used by major mode's +indentation engine in support of invocations as sub-modes of another +major mode. + +@defun prog-first-column +Call this function instead of using a literal value (usually, zero) of +the column number for indenting top-level program constructs. The +function's value is the column number to use for top-level constructs. +When no superior mode is in effect, this function returns zero. +@end defun + +@defun prog-widen +Call this function instead of @code{widen} to remove any restrictions +imposed by the mode's indentation engine and restore the restrictions +recorded in @code{prog-indentation-context}. This prevents the +indentation engine of a sub-mode from inadvertently operating on text +outside of the chunk it was supposed to indent, and preserves the +restriction imposed by the superior mode. When no superior mode is in +effect, this function just calls @code{widen}. +@end defun + @node Region Indent @subsection Indenting an Entire Region @@ -4396,6 +4473,20 @@ using the specified or chosen coding system. However, if coding instead. @end defun +@defun buffer-hash &optional buffer-or-name +Return a hash of @var{buffer-or-name}. If @code{nil}, this defaults +to the current buffer. As opposed to @code{secure-hash}, this +function computes the hash based on the internal representation of the +buffer, disregarding any coding systems. It's therefore only useful +when comparing two buffers running in the same Emacs, and is not +guaranteed to return the same hash between different Emacs versions. +It should be somewhat more efficient on larger buffers than +@code{secure-hash} is, and should not allocate more memory. +@c Note that we do not document what hashing function we're using, or +@c even whether it's a cryptographic hash, since that may change +@c according to what we find useful. +@end defun + @node Parsing HTML/XML @section Parsing HTML and XML @cindex parsing html @@ -4527,6 +4618,9 @@ to be inserted between the textual elements. @item dom-parent @var{dom} @var{node} Return the parent of @var{node} in @var{dom}. + +@item dom-remove @var{dom} @var{node} +Remove @var{node} from @var{dom}. @end table The following are functions for altering the @acronym{DOM}. diff --git a/doc/lispref/threads.texi b/doc/lispref/threads.texi new file mode 100644 index 00000000000..de1c27bf186 --- /dev/null +++ b/doc/lispref/threads.texi @@ -0,0 +1,253 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 2012-2016 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@node Threads +@chapter Threads +@cindex threads +@cindex concurrency + + Emacs Lisp provides a limited form of concurrency, called +@dfn{threads}. All the threads in a given instance of Emacs share the +same memory. Concurrency in Emacs Lisp is ``mostly cooperative'', +meaning that Emacs will only switch execution between threads at +well-defined times. However, the Emacs thread support has been +designed in a way to later allow more fine-grained concurrency, and +correct programs should not rely on cooperative threading. + + Currently, thread switching will occur upon explicit request via +@code{thread-yield}, when waiting for keyboard input or for process +output (e.g., during @code{accept-process-output}), or during blocking +operations relating to threads, such as mutex locking or +@code{thread-join}. + + Emacs Lisp provides primitives to create and control threads, and +also to create and control mutexes and condition variables, useful for +thread synchronization. + + While global variables are shared among all Emacs Lisp threads, +local variables are not---a dynamic @code{let} binding is local. Each +thread also has its own current buffer (@pxref{Current Buffer}) and +its own match data (@pxref{Match Data}). + + Note that @code{let} bindings are treated specially by the Emacs +Lisp implementation. There is no way to duplicate this unwinding and +rewinding behavior other than by using @code{let}. For example, a +manual implementation of @code{let} written using +@code{unwind-protect} cannot arrange for variable values to be +thread-specific. + + In the case of lexical bindings (@pxref{Variable Scoping}), a +closure is an object like any other in Emacs Lisp, and bindings in a +closure are shared by any threads invoking the closure. + +@menu +* Basic Thread Functions:: Basic thread functions. +* Mutexes:: Mutexes allow exclusive access to data. +* Condition Variables:: Inter-thread events. +@end menu + +@node Basic Thread Functions +@section Basic Thread Functions + + Threads can be created and waited for. A thread cannot be exited +directly, but the current thread can be exited implicitly, and other +threads can be signaled. + +@defun make-thread function &optional name +Create a new thread of execution which invokes @var{function}. When +@var{function} returns, the thread exits. + +The new thread is created with no local variable bindings in effect. +The new thread's current buffer is inherited from the current thread. + +@var{name} can be supplied to give a name to the thread. The name is +used for debugging and informational purposes only; it has no meaning +to Emacs. If @var{name} is provided, it must be a string. + +This function returns the new thread. +@end defun + +@defun threadp object +This function returns @code{t} if @var{object} represents an Emacs +thread, @code{nil} otherwise. +@end defun + +@defun thread-join thread +Block until @var{thread} exits, or until the current thread is +signaled. If @var{thread} has already exited, this returns +immediately. +@end defun + +@defun thread-signal thread error-symbol data +Like @code{signal} (@pxref{Signaling Errors}), but the signal is +delivered in the thread @var{thread}. If @var{thread} is the current +thread, then this just calls @code{signal} immediately. Otherwise, +@var{thread} will receive the signal as soon as it becomes current. +If @var{thread} was blocked by a call to @code{mutex-lock}, +@code{condition-wait}, or @code{thread-join}; @code{thread-signal} +will unblock it. +@end defun + +@defun thread-yield +Yield execution to the next runnable thread. +@end defun + +@defun thread-name thread +Return the name of @var{thread}, as specified to @code{make-thread}. +@end defun + +@defun thread-alive-p thread +Return @code{t} if @var{thread} is alive, or @code{nil} if it is not. +A thread is alive as long as its function is still executing. +@end defun + +@defun thread--blocker thread +Return the object that @var{thread} is waiting on. This function is +primarily intended for debugging, and is given a ``double hyphen'' +name to indicate that. + +If @var{thread} is blocked in @code{thread-join}, this returns the +thread for which it is waiting. + +If @var{thread} is blocked in @code{mutex-lock}, this returns the mutex. + +If @var{thread} is blocked in @code{condition-wait}, this returns the +condition variable. + +Otherwise, this returns @code{nil}. +@end defun + +@defun current-thread +Return the current thread. +@end defun + +@defun all-threads +Return a list of all the live thread objects. A new list is returned +by each invocation. +@end defun + +@node Mutexes +@section Mutexes + + A @dfn{mutex} is an exclusive lock. At any moment, zero or one +threads may own a mutex. If a thread attempts to acquire a mutex, and +the mutex is already owned by some other thread, then the acquiring +thread will block until the mutex becomes available. + + Emacs Lisp mutexes are of a type called @dfn{recursive}, which means +that a thread can re-acquire a mutex it owns any number of times. A +mutex keeps a count of how many times it has been acquired, and each +acquisition of a mutex must be paired with a release. The last +release by a thread of a mutex reverts it to the unowned state, +potentially allowing another thread to acquire the mutex. + +@defun mutexp object +This function returns @code{t} if @var{object} represents an Emacs +mutex, @code{nil} otherwise. +@end defun + +@defun make-mutex &optional name +Create a new mutex and return it. If @var{name} is specified, it is a +name given to the mutex. It must be a string. The name is for +debugging purposes only; it has no meaning to Emacs. +@end defun + +@defun mutex-name mutex +Return the name of @var{mutex}, as specified to @code{make-mutex}. +@end defun + +@defun mutex-lock mutex +This will block until this thread acquires @var{mutex}, or until this +thread is signaled using @code{thread-signal}. If @var{mutex} is +already owned by this thread, this simply returns. +@end defun + +@defun mutex-unlock mutex +Release @var{mutex}. If @var{mutex} is not owned by this thread, this +will signal an error. +@end defun + +@defmac with-mutex mutex body@dots{} +This macro is the simplest and safest way to evaluate forms while +holding a mutex. It acquires @var{mutex}, invokes @var{body}, and +then releases @var{mutex}. It returns the result of @var{body}. +@end defmac + +@node Condition Variables +@section Condition Variables + + A @dfn{condition variable} is a way for a thread to block until some +event occurs. A thread can wait on a condition variable, to be woken +up when some other thread notifies the condition. + + A condition variable is associated with a mutex and, conceptually, +with some condition. For proper operation, the mutex must be +acquired, and then a waiting thread must loop, testing the condition +and waiting on the condition variable. For example: + +@example +(with-mutex mutex + (while (not global-variable) + (condition-wait cond-var))) +@end example + + The mutex ensures atomicity, and the loop is for robustness---there +may be spurious notifications. + + Similarly, the mutex must be held before notifying the condition. +The typical, and best, approach is to acquire the mutex, make the +changes associated with this condition, and then notify it: + +@example +(with-mutex mutex + (setq global-variable (some-computation)) + (condition-notify cond-var)) +@end example + +@defun make-condition-variable mutex &optional name +Make a new condition variable associated with @var{mutex}. If +@var{name} is specified, it is a name given to the condition variable. +It must be a string. The name is for debugging purposes only; it has +no meaning to Emacs. +@end defun + +@defun condition-variable-p object +This function returns @code{t} if @var{object} represents a condition +variable, @code{nil} otherwise. +@end defun + +@defun condition-wait cond +Wait for another thread to notify @var{cond}, a condition variable. +This function will block until the condition is notified, or until a +signal is delivered to this thread using @code{thread-signal}. + +It is an error to call @code{condition-wait} without holding the +condition's associated mutex. + +@code{condition-wait} releases the associated mutex while waiting. +This allows other threads to acquire the mutex in order to notify the +condition. +@end defun + +@defun condition-notify cond &optional all +Notify @var{cond}. The mutex with @var{cond} must be held before +calling this. Ordinarily a single waiting thread is woken by +@code{condition-notify}; but if @var{all} is not @code{nil}, then all +threads waiting on @var{cond} are notified. + +@code{condition-notify} releases the associated mutex while waiting. +This allows other threads to acquire the mutex in order to wait on the +condition. +@c why bother? +@end defun + +@defun condition-name cond +Return the name of @var{cond}, as passed to +@code{make-condition-variable}. +@end defun + +@defun condition-mutex cond +Return the mutex associated with @var{cond}. Note that the associated +mutex cannot be changed. +@end defun diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 1ba9ad9701f..b45e68d0d56 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -679,8 +679,7 @@ which quotes symbols with grave accent @t{`} and apostrophe @t{'}: @t{`like-this'} rather than @t{‘like-this’}. This older convention was designed for now-obsolete displays in which grave accent and apostrophe were mirror images. - -Documentation using either convention is converted to the user's +Documentation using this convention is converted to the user's preferred format when it is copied into a help buffer. @xref{Keys in Documentation}. diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 887643196cc..4936f7a921a 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -34,10 +34,12 @@ representing the variable. * Accessing Variables:: Examining values of variables whose names are known only at run time. * Setting Variables:: Storing new values in variables. +* Watching Variables:: Running a function when a variable is changed. * Variable Scoping:: How Lisp chooses among local and global values. * Buffer-Local Variables:: Variable values in effect only in one buffer. * File Local Variables:: Handling local variable lists in files. * Directory Local Variables:: Local variables common to all files in a directory. +* Connection Local Variables:: Local variables common for remote connections. * Variable Aliases:: Variables that are aliases for other variables. * Variables with Restricted Values:: Non-constant variables whose value can @emph{not} be an arbitrary Lisp object. @@ -777,6 +779,66 @@ error is signaled. @end example @end defun +@node Watching Variables +@section Running a function when a variable is changed. +@cindex variable watchpoints +@cindex watchpoints for Lisp variables + +It is sometimes useful to take some action when a variable changes its +value. The watchpoint facility provides the means to do so. Some +possible uses for this feature include keeping display in sync with +variable settings, and invoking the debugger to track down unexpected +changes to variables (@pxref{Variable Debugging}). + +The following functions may be used to manipulate and query the watch +functions for a variable. + +@defun add-variable-watcher symbol watch-function +This function arranges for @var{watch-function} to be called whenever +@var{symbol} is modified. Modifications through aliases +(@pxref{Variable Aliases}) will have the same effect. + +@var{watch-function} will be called with 4 arguments: (@var{symbol} +@var{newval} @var{operation} @var{where}). + +@var{symbol} is the variable being changed. +@var{newval} is the value it will be changed to. +@var{operation} is a symbol representing the kind of change, one of: +`set', `let', `unlet', `makunbound', and `defvaralias'. +@var{where} is a buffer if the buffer-local value of the variable is +being changed, nil otherwise. +@end defun + +@defun remove-variable-watch symbol watch-function +This function removes @var{watch-function} from @var{symbol}'s list of +watchers. +@end defun + +@defun get-variable-watchers symbol +This function returns the list of @var{symbol}'s active watcher +functions. +@end defun + +@subsection Limitations + +There are a couple of ways in which a variable could be modified (or at +least appear to be modified) without triggering a watchpoint. + +Since watchpoints are attached to symbols, modification to the +objects contained within variables (e.g., by a list modification +function @pxref{Modifying Lists}) is not caught by this mechanism. + +Additionally, C code can modify the value of variables directly, +bypassing the watchpoint mechanism. + +A minor limitation of this feature, again because it targets symbols, +is that only variables of dynamic scope may be watched. This poses +little difficulty, since modifications to lexical variables can be +discovered easily by inspecting the code within the scope of the +variable (unlike dynamic variables, which can be modified by any code +at all, @pxref{Variable Scoping}). + + @node Variable Scoping @section Scoping Rules for Variable Bindings @cindex scoping rule @@ -1666,7 +1728,7 @@ any form of file-local variable. For examples of why you might want to use this, @pxref{Auto Major Mode}. @end defvar -@defun hack-local-variables &optional mode-only +@defun hack-local-variables &optional handle-mode This function parses, and binds or evaluates as appropriate, any local variables specified by the contents of the current buffer. The variable @code{enable-local-variables} has its effect here. However, this @@ -1683,11 +1745,15 @@ is non-@code{nil}; it always calls the other hook. This function ignores a @samp{mode} element if it specifies the same major mode as the buffer already has. -If the optional argument @var{mode-only} is non-@code{nil}, then all -this function does is return a symbol specifying the major mode, -if the @w{@samp{-*-}} line or the local variables list specifies one, -and @code{nil} otherwise. It does not set the mode nor any other -file-local variable. +If the optional argument @var{handle-mode} is @code{t}, then all this +function does is return a symbol specifying the major mode, if the +@w{@samp{-*-}} line or the local variables list specifies one, and +@code{nil} otherwise. It does not set the mode or any other +file-local variable. If @var{handle-mode} has any value other than +@code{nil} or @code{t}, any settings of @samp{mode} in the +@w{@samp{-*-}} line or the local variables list are ignored, and the +other settings are applied. If @var{handle-mode} is @code{nil}, all +the file local variables are set. @end defun @defvar file-local-variables-alist @@ -1909,6 +1975,170 @@ may be useful for modes that want to ignore directory-locals while still respecting file-local variables (@pxref{File Local Variables}). @end defvar +@node Connection Local Variables +@section Connection Local Variables +@cindex connection local variables + + Connection-local variables provide a general mechanism for +different variable settings in buffers with a remote default +directory. They are bound and set depending on the remote connection +a buffer is dedicated to. Per default, they are set in all process +buffers for a remote connection, but they could be applied also in +other buffers with a remote directory. + +@defun connection-local-set-class-variables class variables +This function defines a set of variable settings for the named +@var{class}, which is a symbol. You can later assign the class to one +or more remote connections, and Emacs will apply those variable +settings to all process buffers for those connections. The list in +@var{variables} is an alist of the form @code{(@var{name} +. @var{value})}. Example: + +@example +@group +(connection-local-set-class-variables + 'remote-bash + '((shell-file-name . "/bin/bash") + (shell-command-switch . "-c") + (shell-interactive-switch . "-i") + (shell-login-switch . "-l"))) +@end group + +@group +(connection-local-set-class-variables + 'remote-ksh + '((shell-file-name . "/bin/ksh") + (shell-command-switch . "-c") + (shell-interactive-switch . "-i") + (shell-login-switch . "-l"))) +@end group + +@group +(connection-local-set-class-variables + 'remote-null-device + '((null-device . "/dev/null"))) +@end group +@end example +@end defun + +@defvar connection-local-class-alist +This alist holds the class symbols and the associated variable +settings. It is updated by @code{connection-local-set-class-variables}. +@end defvar + +@defun connection-local-set-classes criteria &rest classes +This function assigns @var{classes}, which are symbols, to all remote +connections identified by @var{criteria}. @var{criteria} is either a +regular expression identifying a remote server, or a function with one +argument @var{identification}, which must return non-nil when a remote +server shall apply @var{classes} variables, or @code{nil}. + +If @var{criteria} is a regexp, is must match the result of +@code{(file-remote-p default-directory)} of a buffer in order to apply +the variables setting. Example: + +@example +@group +(connection-local-set-classes + "^/ssh:" 'remote-bash 'remote-null-device) +@end group + +@group +(connection-local-set-classes + "^/sudo:" 'remote-ksh 'remote-null-device) +@end group +@end example + + If @var{criteria} is nil, it applies for all remote connections. +Therefore, the example above would be equivalent to + +@example +(connection-local-set-classes "^/ssh:" 'remote-bash) +(connection-local-set-classes "^/sudo:" 'remote-ksh) +(connection-local-set-classes nil 'remote-null-device) +@end example + + If @var{criteria} is a lambda function it must accept one parameter, +the identification. The example above could be rewritten as + +@example +@group +(connection-local-set-classes + (lambda (identification) + (string-equal (file-remote-p identification 'method) "ssh")) + 'remote-bash) +@end group + +@group +(connection-local-set-classes + (lambda (identification) + (string-equal (file-remote-p identification 'method) "sudo")) + 'remote-ksh) +@end group + +@group +(connection-local-set-classes + (lambda (identification) t) + 'remote-null-device) +@end group +@end example + + Thereafter, all the variable settings specified for @var{classes} +will be applied to any buffer with a matching remote directory, when +activated by @code{hack-connection-local-variables-apply}. Any class +of @var{classes} must have been already defined by +@code{connection-local-set-class-variables}. +@end defun + +@defvar connection-local-criteria-alist +This alist contains remote server identifications and their assigned +class names. The function @code{connection-local-set-classes} updates +this list. +@end defvar + +@defun hack-connection-local-variables +This function collects applicable connection-local variables in +@code{connection-local-variables-alist} that is local to the buffer, +without applying them. Whether a connection-local variable is +applicable is specified by the remote identifier of a buffer, +evaluated by @code{(file-remote-p default-directory)}. +@end defun + +@defun hack-connection-local-variables-apply +This function looks for connection-local variables, and immediately +applies them in the current buffer. It is called per default for +every process-buffer related to a remote connection. For other remote +buffers, it could be called by any mode. +@end defun + +@defmac with-connection-local-classes classes &rest body +All connection-local variables, which are specified by a class in +@var{classes}, are applied. An implicit binding of the classes to the +remote connection is enabled. + +After that, @var{body} is executed, and the connection-local variables +are unwound. Example: + +@example +@group +(connection-local-set-class-variables + 'remote-perl + '((perl-command-name . "/usr/local/bin/perl") + (perl-command-switch . "-e %s"))) +@end group + +@group +(with-connection-local-classes '(remote-perl) + do something useful) +@end group +@end example +@end defmac + +@defvar enable-connection-local-variables +If @code{nil}, connection-local variables are ignored. This variable +shall be changed temporarily only in special modes. +@end defvar + @node Variable Aliases @section Variable Aliases @cindex variable aliases diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 042e0cc35b6..4dc671c41f3 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -33,6 +33,8 @@ is displayed in windows. a specific window. * Quitting Windows:: How to restore the state prior to displaying a buffer. +* Side Windows:: Special windows on a frame's sides. +* Atomic Windows:: Preserving parts of the window layout. * Window Point:: Each window has its own location of point. * Window Start and End:: Buffer positions indicating which text is on-screen in a window. @@ -545,6 +547,12 @@ its pixel height is the pixel height of the screen areas spanned by its children. @end defun +@defun window-pixel-height-before-size-change &optional Lisp_Object &optional window +This function returns the height of window @var{window} in pixels at the +time @code{window-size-change-functions} was run for the last time on +@var{window}'s frame (@pxref{Window Hooks}). +@end defun + @cindex window pixel width @cindex pixel width of a window @cindex total pixel width of a window @@ -559,6 +567,12 @@ If @var{window} is an internal window, its pixel width is the width of the screen areas spanned by its children. @end defun +@defun window-pixel-width-before-size-change &optional Lisp_Object &optional window +This function returns the width of window @var{window} in pixels at the +time @code{window-size-change-functions} was run for the last time on +@var{window}'s frame (@pxref{Window Hooks}). +@end defun + @cindex full-width window @cindex full-height window The following functions can be used to determine whether a given @@ -1263,9 +1277,12 @@ Configurations}). @deffn Command delete-window &optional window This function removes @var{window} from display and returns @code{nil}. If @var{window} is omitted or @code{nil}, it defaults to -the selected window. If deleting the window would leave no more -windows in the window tree (e.g., if it is the only live window in the -frame), an error is signaled. +the selected window. + +If deleting the window would leave no more windows in the window tree +(e.g., if it is the only live window in the frame) or all remaining +windows on @var{window}'s frame are side windows (@pxref{Side Windows}), +an error is signaled. By default, the space taken up by @var{window} is given to one of its adjacent sibling windows, if any. However, if the variable @@ -1273,33 +1290,34 @@ adjacent sibling windows, if any. However, if the variable proportionally distributed among any remaining windows in the same window combination. @xref{Recombining Windows}. -The behavior of this function may be altered by the window parameters -of @var{window}, so long as the variable -@code{ignore-window-parameters} is @code{nil}. If the value of -the @code{delete-window} window parameter is @code{t}, this function -ignores all other window parameters. Otherwise, if the value of the -@code{delete-window} window parameter is a function, that function is -called with the argument @var{window}, in lieu of the usual action of -@code{delete-window}. Otherwise, this function obeys the -@code{window-atom} or @code{window-side} window parameter, if any. -@xref{Window Parameters}. +The behavior of this function may be altered by the window parameters of +@var{window}, so long as the variable @code{ignore-window-parameters} is +@code{nil}. If the value of the @code{delete-window} window parameter +is @code{t}, this function ignores all other window parameters. +Otherwise, if the value of the @code{delete-window} window parameter is +a function, that function is called with the argument @var{window}, in +lieu of the usual action of @code{delete-window}. @xref{Window +Parameters}. @end deffn @deffn Command delete-other-windows &optional window -This function makes @var{window} fill its frame, by deleting other -windows as necessary. If @var{window} is omitted or @code{nil}, it -defaults to the selected window. The return value is @code{nil}. - -The behavior of this function may be altered by the window parameters -of @var{window}, so long as the variable -@code{ignore-window-parameters} is @code{nil}. If the value of -the @code{delete-other-windows} window parameter is @code{t}, this -function ignores all other window parameters. Otherwise, if the value -of the @code{delete-other-windows} window parameter is a function, -that function is called with the argument @var{window}, in lieu of the -usual action of @code{delete-other-windows}. Otherwise, this function -obeys the @code{window-atom} or @code{window-side} window parameter, -if any. @xref{Window Parameters}. +This function makes @var{window} fill its frame, deleting other windows +as necessary. If @var{window} is omitted or @code{nil}, it defaults to +the selected window. An error is signaled if @var{window} is a side +window (@pxref{Side Windows}). The return value is @code{nil}. + +The behavior of this function may be altered by the window parameters of +@var{window}, so long as the variable @code{ignore-window-parameters} is +@code{nil}. If the value of the @code{delete-other-windows} window +parameter is @code{t}, this function ignores all other window +parameters. Otherwise, if the value of the @code{delete-other-windows} +window parameter is a function, that function is called with the +argument @var{window}, in lieu of the usual action of +@code{delete-other-windows}. @xref{Window Parameters}. + +Also, if @code{ignore-window-parameters} is @code{nil}, this function +does not delete any window whose @code{no-delete-other-window} parameter +is non-@code{nil}. @end deffn @deffn Command delete-windows-on &optional buffer-or-name frame @@ -2159,8 +2177,9 @@ This option does not affect non-interactive calls of @code{switch-to-buffer}. @end defopt -By default, @code{switch-to-buffer} shows the buffer at its position of -@code{point}. This behavior can be tuned using the following option. +By default, @code{switch-to-buffer} tries to preserve +@code{window-point}. This behavior can be tuned using the following +option. @defopt switch-to-buffer-preserve-window-point If this variable is @code{nil}, @code{switch-to-buffer} displays the @@ -2220,15 +2239,15 @@ This function makes @var{buffer-or-name} the current buffer and displays it in some window, preferably not the window currently selected. It then selects the displaying window. If that window is on a different graphical frame, that frame is given input focus if -possible (@pxref{Input Focus}). The return value is the buffer that -was switched to. +possible (@pxref{Input Focus}). If @var{buffer-or-name} is @code{nil}, it defaults to the buffer returned by @code{other-buffer} (@pxref{Buffer List}). If @var{buffer-or-name} is a string that is not the name of any existing buffer, this function creates a new buffer with that name; the new buffer's major mode is determined by the variable @code{major-mode} -(@pxref{Major Modes}). +(@pxref{Major Modes}). In any case, that buffer is made current and +returned, even when no suitable window was found to display it. If @var{action} is non-@code{nil}, it should be a display action to pass to @code{display-buffer} (@pxref{Choosing Window}). @@ -2403,6 +2422,23 @@ visible and, unless @var{alist} contains an @code{inhibit-switch-frame} entry (@pxref{Choosing Window Options}), raises that frame if necessary. @end defun +@defun display-buffer-reuse-mode-window buffer alist +This function tries to display @var{buffer} by finding a window +that is displaying a buffer in a given mode. + +If @var{alist} contains a @code{mode} entry, its value is a major mode +(a symbol) or a list of major modes. If @var{alist} contains no +@code{mode} entry, the current major mode of @var{buffer} is used. A +window is a candidate if it displays a buffer that derives from one of +the given modes. + +The behavior is also controlled by entries for +@code{inhibit-same-window}, @code{reusable-frames} and +@code{inhibit-switch-frame} as is done in the function +@code{display-buffer-reuse-window}. + +@end defun + @defun display-buffer-pop-up-frame buffer alist This function creates a new frame, and displays the buffer in that frame's window. It actually performs the frame creation by calling @@ -2494,10 +2530,17 @@ parameter; @pxref{Buffer Parameters}). @defun display-buffer-below-selected buffer alist This function tries to display @var{buffer} in a window below the -selected window. This means to either split the selected window or use -the window below the selected one. If it does create a new window, it -will also adjust its size provided @var{alist} contains a suitable +selected window. If there is a window below the selected one and that +window already displays @var{buffer}, it reuses that window. + +If there is no such window, this function tries to create a new window +by splitting the selected one and display @var{buffer} there. It will +also adjust that window's size provided @var{alist} contains a suitable @code{window-height} or @code{window-width} entry, see above. + +If splitting the selected window fails and there is a non-dedicated +window below the selected one showing some other buffer, it uses that +window for showing @var{buffer}. @end defun @defun display-buffer-in-previous-window buffer alist @@ -2537,7 +2580,12 @@ assumed that when the caller specifies a non-@code{nil} from @code{display-buffer} in this case. @end defun -To illustrate the use of action functions, consider the following +If the @var{alist} argument of any of these functions contains a +@code{window-parameters} entry, @code{display-buffer} assigns the +elements of the associated value as window parameters of the chosen +window. + + To illustrate the use of action functions, consider the following example. @example @@ -3031,6 +3079,428 @@ other frame on the same terminal. @end defopt +@node Side Windows +@section Side Windows +@cindex side windows +@cindex main window +@cindex main window of a frame + +Side windows are special windows positioned at any of the four sides of +a frame's root window (@pxref{Windows and Frames}). In practice, this +means that the area of the frame's root window is subdivided into a main +window and a number of side windows surrounding that main window. The +main window is either a ``normal'' live window or specifies the area +containing all the normal windows. + + In their most simple form of use, side windows allow to display +specific buffers always in the same area of a frame. Hence they can be +regarded as a generalization of the concept provided by +@code{display-buffer-at-bottom} (@pxref{Display Action Functions}) to +the remaining sides of a frame. With suitable customizations, however, +side windows can be also used to provide frame layouts similar to those +found in so-called integrated development environments (IDEs). + +@menu +* Displaying Buffers in Side Windows:: An action function for displaying + buffers in side windows. +* Side Window Options and Functions:: Further tuning of side windows. +* Frame Layouts with Side Windows:: Setting up frame layouts with side + windows. +@end menu + + +@node Displaying Buffers in Side Windows +@subsection Displaying Buffers in Side Windows + +The following action function for @code{display-buffer} (@pxref{Display +Action Functions}) creates or reuses a side window for displaying the +specified buffer. + +@defun display-buffer-in-side-window buffer alist +This function displays @var{buffer} in a side window of the selected +frame. It returns the window used for displaying @var{buffer}, +@code{nil} if no such window can be found or created. + +@var{alist} is an association list of symbols and values as for +@code{display-buffer}. The following symbols in @var{alist} are special +for this function: + +@table @code +@item side +Denotes the side of the frame where the window shall be located. Valid +values are @code{left}, @code{top}, @code{right} and @code{bottom}. If +unspecified, the window is located at the bottom of the frame. + +@item slot +Denotes a slot at the specified side where to locate the window. A +value of zero means to preferably position the window in the middle of +the specified side. A negative value means to use a slot preceding +(that is, above or on the left of) the middle slot. A positive value +means to use a slot following (that is, below or on the right of) the +middle slot. Hence, all windows on a specific side are ordered by their +@code{slot} value. If unspecified, the window is located in the middle +of the specified side. +@end table + +If you specify the same slot on the same side for two or more different +buffers, the buffer displayed last is shown in the corresponding window. +Hence, slots can be used for sharing the same side window between +buffers. + +This function installs the @code{window-side} and @code{window-slot} +parameters (@pxref{Window Parameters}) and makes them persistent. It +does not install any other window parameters unless they have been +explicitly provided via a @code{window-parameters} entry in @var{alist}. +@end defun + +By default, side windows cannot be split via @code{split-window} +(@pxref{Splitting Windows}). Also, a side window is not reused or split +by any buffer display action (@pxref{Display Action Functions}) unless +it is explicitly specified as target of that action. Note also that +@code{delete-other-windows} cannot make a side window the only window on +its frame (@pxref{Deleting Windows}). + + Once set up, side windows also change the behavior of the commands +@code{switch-to-prev-buffer} and @code{switch-to-next-buffer} +(@pxref{Window History}). In particular, these commands will refrain +from showing, in a side window, buffers that have not been displayed in +that window before. They will also refrain from having a normal, +non-side window show a buffer that has been already displayed in a side +window. A notable exception to the latter rule occurs when an +application, after displaying a buffer, resets that buffer's local +variables. + + +@node Side Window Options and Functions +@subsection Side Window Options and Functions + +The following options provide additional control over the placement of +side windows. + +@defopt window-sides-vertical +If non-@code{nil}, the side windows on the left and right of a frame +occupy the frame's full height. Otherwise, the side windows on the top +and bottom of the frame occupy the frame's full width. +@end defopt + +@defopt window-sides-slots +This option specifies the maximum number of side windows on each side of +a frame. The value is a list of four elements specifying the number of +side window slots on (in this order) the left, top, right and bottom of +each frame. If an element is a number, it means to display at most that +many windows on the corresponding side. If an element is @code{nil}, it +means there's no bound on the number of slots on that side. + +If any of the specified values is zero, no window can be created on the +corresponding side. @code{display-buffer-in-side-window} will not +signal an error in that case, but will return @code{nil}. If a specified +value just forbids the creation of an additional side window, the most +suitable window on that side is reused and may have its +@code{window-slot} parameter changed accordingly. +@end defopt + +@defopt window-sides-reversed +This option specifies whether top/bottom side windows should appear in +reverse order. When this is @code{nil}, side windows on the top and +bottom of a frame are always drawn from left to right with increasing +slot values. When this is @code{t}, the drawing order is reversed and +side windows on the top and bottom of a frame are drawn from right to +left with increasing slot values. + +When this is @code{bidi}, the drawing order is reversed if and only if +the value of @code{bidi-paragraph-direction} (@pxref{Bidirectional +Display}) is @code{right-to-left} in the buffer displayed in the window +most recently selected within the main window area of this frame. +Sometimes that window may be hard to find, so heuristics are used to +avoid that the drawing order changes inadvertently when another window +gets selected. + +The layout of side windows on the left or right of a frame is not +affected by the value of this variable. +@end defopt + +When a frame has side windows, the following function returns the main +window of that frame. + +@defun window-main-window &optional frame +This function returns the main window of the specified @var{frame}. The +optional argument @var{frame} must be a live frame and defaults to the +selected one. + +If @var{frame} has no side windows, it returns @var{frame}'s root +window. Otherwise, it returns either an internal non-side window such +that all other non-side windows on @var{frame} descend from it, or the +single live non-side window of @var{frame}. Note that the main window +of a frame cannot be deleted via @code{delete-window}. +@end defun + +The following command is handy to toggle the appearance of all side +windows on a specified frame. + +@deffn Command window-toggle-side-windows &optional frame +This command toggles side windows on the specified @var{frame}. The +optional argument @var{frame} must be a live frame and defaults to the +selected one. + +If @var{frame} has at least one side window, this command saves the +state of @var{frame}'s root window in the @var{frame}'s +@code{window-state} frame parameter and deletes all side windows on +@var{frame} afterwards. + +If @var{frame} has no side windows, but does have a @code{window-state} +parameter, this command uses that parameter's value to restore the side +windows on @var{frame} leaving @var{frame}'s main window alone. + +An error is signaled if @var{frame} has no side windows and no saved +state is found for it. +@end deffn + + +@node Frame Layouts with Side Windows +@subsection Frame Layouts with Side Windows + +Side windows can be used to create more complex frame layouts like those +provided by integrated development environments (IDEs). In such +layouts, the area of the main window is where the normal editing +activities take place. Side windows are not conceived for editing in +the usual sense. Rather, they are supposed to display information +complementary to the current editing activity, like lists of files, tags +or buffers, help information, search or grep results or shell output. + + The layout of such a frame might appear as follows: + +@smallexample +@group + ___________________________________ + | *Buffer List* | + |___________________________________| + | | | | + | * | | * | + | d | | T | + | i | | a | + | r | Main Window Area | g | + | e | | s | + | d | | * | + | * | | | + |_____|_______________________|_____| + | *help*/*grep*/ | *shell*/ | + | *Completions* | *compilation* | + |_________________|_________________| + | Echo Area | + |___________________________________| + + +@end group +@end smallexample + +The following example illustrates how window parameters (@pxref{Window +Parameters}) can be used with @code{display-buffer-in-side-window} +(@pxref{Displaying Buffers in Side Windows}) to set up code for +producing the frame layout sketched above. + +@example +@group +(defvar parameters + '(window-parameters . ((no-other-window . t) (no-delete-other-window . t)))) + +(setq fit-window-to-buffer-horizontally t) +(setq window-resize-pixelwise t) + +(setq + display-buffer-alist + `(("\\*Buffer List\\*" display-buffer-in-side-window + (side . top) (slot . 0) (window-height . fit-window-to-buffer) + (preserve-size . (nil . t)) ,parameters) + ("\\*Tags List\\*" display-buffer-in-side-window + (side . right) (slot . 0) (window-width . fit-window-to-buffer) + (preserve-size . (t . nil)) ,parameters) + ("\\*\\(?:help\\|grep\\|Completions\\)\\*" display-buffer-in-side-window + (side . bottom) (slot . -1) (preserve-size . (nil . t)) ,parameters) + ("\\*\\(?:shell\\|compilation\\)\\*" display-buffer-in-side-window + (side . bottom) (slot . 1) (preserve-size . (nil . t)) ,parameters))) +@end group +@end example + +This specifies @code{display-buffer-alist} entries (@pxref{Choosing +Window}) for buffers with fixed names. In particular, it asks for +showing @file{*Buffer List*} with adjustable height at the top of the +frame and @file{*Tags List*} with adjustable width on the frame's right. +It also asks for having the @file{*help*}, @file{*grep*} and +@file{*Completions*} buffers share a window on the bottom left side of +the frame and the @file{*shell*} and @file{*compilation*} buffers appear +in a window on the bottom right side of the frame. + + Note that the option @code{fit-window-to-buffer-horizontally} must +have a non-@code{nil} value in order to allow horizontal adjustment of +windows. Entries are also added that ask for preserving the height of +side windows at the top and bottom of the frame and the width of side +windows at the left or right of the frame. To assure that side windows +retain their respective sizes when maximizing the frame, the variable +@code{window-resize-pixelwise} is set to a non-@code{nil} value. +@xref{Resizing Windows}. + + The last form also makes sure that none of the created side windows +are accessible via @kbd{C-x o} by installing the @code{no-other-window} +parameter for each of these windows. In addition, it makes sure that +side windows are not deleted via @kbd{C-x 1} by installing the +@code{no-delete-other-window} parameter for each of these windows. + + Since @code{dired} buffers have no fixed names, we use a special +function @code{dired-default-directory-on-left} in order to display a +lean directory buffer on the left side of the frame. + +@example +@group +(defun dired-default-directory-on-left () + "Display `default-directory' in side window on left, hiding details." + (interactive) + (let ((buffer (dired-noselect default-directory))) + (with-current-buffer buffer (dired-hide-details-mode t)) + (display-buffer-in-side-window + buffer `((side . left) (slot . 0) + (window-width . fit-window-to-buffer) + (preserve-size . (t . nil)) ,parameters)))) +@end group +@end example + +Evaluating the preceding forms and typing, in any order, @w{@kbd{M-x +list-buffers}}, @kbd{C-h f}, @kbd{M-x shell}, @w{@kbd{M-x list-tags}}, +and @kbd{M-x dired-default-directory-on-left} should now reproduce the +frame layout sketched above. + + +@node Atomic Windows +@section Atomic Windows +@cindex atomic windows + +Atomic windows are rectangular compositions of at least two live +windows. They have the following distinctive characteristics: + +@itemize @bullet +@item +The function @code{split-window} (@pxref{Splitting Windows}), when +applied to a constituent of an atomic window, will try to create the new +window outside of the atomic window. + +@item +The function @code{delete-window} (@pxref{Deleting Windows}), when +applied to a constituent of an atomic window, will try to delete the +entire atomic window instead. + +@item +The function @code{delete-other-windows} (@pxref{Deleting Windows}), +when applied to a constituent of an atomic window, will try to make the +atomic window fill its frame or main window (@pxref{Side Windows}). +@end itemize + +This means that the basic groups of functions that alter the window +structure treat an atomic window like a live one, thus preserving the +internal structure of the atomic window. + + Atomic windows are useful to construct and preserve window layouts +that are meaningful only when all involved buffers are shown +simultaneously in a specific manner, such as when showing differences +between file revisions, or the same text in different languages or +markups. They can also be used to permanently display information +pertinent to a specific window in bars on that window's sides. + +@cindex root window of atomic window + Atomic windows are implemented with the help of the reserved +@code{window-atom} window parameter (@pxref{Window Parameters}) and an +internal window (@pxref{Basic Windows}) called the root window of the +atomic window. All windows that are part of the same atomic window have +this root window as their common ancestor and are assigned a +non-@code{nil} @code{window-atom} parameter. + + The following function returns the root of the atomic window a +specified window is part of: + +@defun window-atom-root &optional window +This functions returns the root of the atomic window @var{window} is a +part of. The specified @var{window} must be a valid window and defaults +to the selected one. It returns @code{nil} if @var{window} is not part +of an atomic window. +@end defun + +The most simple approach to make a new atomic window is to take an +existing internal window and apply the following function: + +@defun window-make-atom window +This function converts @var{window} into an atomic window. The +specified @var{window} must be an internal window. All this function +does is to set the @code{window-atom} parameter of each descendant of +@var{window} to @code{t}. +@end defun + +To create a new atomic window from an existing live window or to add a +new window to an existing atomic window, the following buffer display +action function (@pxref{Display Action Functions}) can be used: + +@defun display-buffer-in-atom-window buffer alist +This function tries to display @var{buffer} in a new window that will be +combined with an existing window to form an atomic window. If the +existing window is already part of an atomic window, it adds the new +window to that atomic window. + +The specified @var{alist} is an association list of symbols and values. +The following symbols have a special meaning: + +@table @code +@item window +The value of such an element specifies an existing window the new window +shall be combined with. If it specifies an internal window, all +children of that window become part of the atomic window too. If no +window is specified, the new window becomes a sibling of the selected +window. The @code{window-atom} parameter of the existing window is set +to @code{main} provided that window is live and its @code{window-atom} +parameter was not already set. + +@item side +The value of such an element denotes the side of the existing window +where the new window shall be located. Valid values are @code{below}, +@code{right}, @code{above} and @code{left}. The default is +@code{below}. The @code{window-atom} parameter of the new window is set +to this value. +@end table + +The return value is the new window, @code{nil} when creating that window +failed. +@end defun + +Note that the value of the @code{window-atom} parameter does not really +matter as long as it is non-@code{nil}. The values assigned by +@code{display-buffer-in-atom-window} just allow for easy retrieval of +the original and the new window after that function has been applied. +Note also that the @code{window-atom} parameter is the only window +parameter assigned by @code{display-buffer-in-atom-window}. Further +parameters have to be set by the application explicitly via a +@code{window-parameters} entry in @var{alist}. + + The following code snippet, when applied to a single-window frame, +first splits the selected window and makes the selected and the new +window constituents of an atomic window with their parent as root. It +then displays the buffer @file{*Messages*} in a new window at the +frame's bottom and makes that new window part of the atomic window just +created. + +@example +@group +(let ((window (split-window-right))) + (window-make-atom (window-parent window)) + (display-buffer-in-atom-window + (get-buffer-create "*Messages*") + `((window . ,(window-parent window)) (window-height . 5)))) +@end group +@end example + +At this moment typing @w{@kbd{C-x 2}} in any window of that frame +produces a new window at the bottom of the frame. Typing @w{@kbd{C-x +3}} instead will put the new window at the frame's right. In either +case, typing now @w{@kbd{C-x 1}} in any window of the atomic window will +remove the new window only. Typing @w{@kbd{C-x 0}} in any window of the +atomic window will make that new window fill the frame. + + @node Window Point @section Windows and Point @cindex window position @@ -4093,11 +4563,11 @@ was created for. The argument @var{configuration} must be a value that was previously returned by @code{current-window-configuration}. The configuration is restored in the frame from which @var{configuration} was made, whether -that frame is selected or not. This always counts as a window size -change and triggers execution of the @code{window-size-change-functions} -(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't -know how to tell whether the new configuration actually differs from the -old one. +that frame is selected or not. In some rare cases this may trigger +execution of the @code{window-size-change-functions} (@pxref{Window +Hooks}) even if the size of windows did not change at all. The +@code{window-configuration-change-hook} functions will be called if and +only if at least one window was added to or deleted from the frame. If the frame from which @var{configuration} was saved is dead, all this function does is restore the three variables @code{window-min-height}, @@ -4205,6 +4675,25 @@ is @code{safe}, this means windows can get as small as one line and/or two columns. @end defun +The functions @code{window-state-get} and @code{window-state-put} also +allow to exchange the contents of two live windows. The following +function does precisely that: + +@deffn Command window-swap-states &optional window-1 window-2 size +This command swaps the states of the two live windows @var{window-1} and +@var{window-2}. @var{window-1} must specify a live window and defaults +to the selected one. @var{window-2} must specify a live window and +defaults to the window following @var{window-1} in the cyclic ordering +of windows, excluding minibuffer windows and including live windows on +all visible frames. + +Optional argument @var{size} non-@code{nil} means to try swapping the +sizes of @var{window-1} and @var{window-2} as well. A value of +@code{height} means to swap heights only, a value of @code{width} +means to swap widths only, while @code{t} means to swap both widths +and heights, if possible. Frames are not resized by this function. +@end deffn + @node Window Parameters @section Window Parameters @@ -4242,6 +4731,7 @@ earlier by @code{window-state-get}, all cloned windows have their parameters reset to @code{nil}. The following variable allows you to override the standard behavior: +@cindex persistent window parameters @defvar window-persistent-parameters This variable is an alist specifying which parameters get saved by @code{current-window-configuration} and @code{window-state-get}, and @@ -4271,9 +4761,10 @@ may fail with an @code{invalid-read-syntax} error. @end defvar Some functions (notably @code{delete-window}, -@code{delete-other-windows} and @code{split-window}), may behave specially -when their @var{window} argument has a parameter set. You can override -such special behavior by binding the following variable to a +@code{delete-other-windows} and @code{split-window}), may behave +specially when the window specified by their @var{window} argument has +a parameter whose name is equal to the function's name. You can +override such special behavior by binding the following variable to a non-@code{nil} value: @defvar ignore-window-parameters @@ -4300,6 +4791,10 @@ This parameter affects the execution of @code{delete-window} This parameter affects the execution of @code{delete-other-windows} (@pxref{Deleting Windows}). +@item @code{no-delete-other-window} +This parameter marks the window as not deletable by +@code{delete-other-windows} (@pxref{Deleting Windows}). + @item @code{split-window} This parameter affects the execution of @code{split-window} (@pxref{Splitting Windows}). @@ -4350,6 +4845,14 @@ The fourth element is the buffer whose display caused the creation of this parameter. @code{quit-restore-window} deletes the specified window only if it still shows that buffer. +@item @code{window-side} @code{window-slot} +These parameters are used for implementing side windows (@pxref{Side +Windows}). + +@item @code{window-atom} +This parameter is used for implementing atomic windows, see @ref{Atomic +Windows}. + @item @code{min-margins} The value of this parameter is a cons cell whose @sc{car} and @sc{cdr}, if non-@code{nil}, specify the minimum values (in columns) for the left @@ -4372,8 +4875,7 @@ applications. It might be replaced by an improved solution in future versions of Emacs. @end table -There are additional parameters @code{window-atom} and @code{window-side}; -these are reserved and should not be used by applications. +The @code{window-atom} parameter is used for implementing atomic windows. @node Window Hooks @@ -4405,33 +4907,38 @@ work. @end defvar @defvar window-size-change-functions -This variable holds a list of functions to be called if the size of -any window changes for any reason. The functions are called at the -beginning of a redisplay cycle, and just once for each frame on which -size changes have occurred. - -Each function receives the frame as its sole argument. There is no -direct way to find out which windows on that frame have changed size, or -precisely how. However, if a size-change function records, at each -call, the existing windows and their sizes, it can also compare the -present sizes and the previous sizes. - -Creating or deleting windows counts as a size change, and therefore -causes these functions to be called. Changing the frame size also -counts, because it changes the sizes of the existing windows. +This variable holds a list of functions to be called if the size of any +window changes for any reason. The functions are called once per +redisplay, and once for each frame on which size changes have occurred. + +Each function receives the frame as its sole argument. To find out +whether a specific window has changed size, compare the return values of +@code{window-pixel-width-before-size-change} and +@code{window-pixel-width} respectively +@code{window-pixel-height-before-size-change} and +@code{window-pixel-height} for that window (@pxref{Window Sizes}). + +These function are usually only called when at least one window was +added or has changed size since the last time this hook was run for the +associated frame. In some rare cases this hook also runs when a window +that was added intermittently has been deleted afterwards. In these +cases none of the windows on the frame will appear to have changed its +size. You may use @code{save-selected-window} in these functions (@pxref{Selecting Windows}). However, do not use @code{save-window-excursion} (@pxref{Window Configurations}); exiting -that macro counts as a size change, which would cause these functions -to be called over and over. +that macro counts as a size change, which would cause these functions to +be called again. @end defvar @defvar window-configuration-change-hook -A normal hook that is run every time you change the window configuration -of an existing frame. This includes splitting or deleting windows, -changing the sizes of windows, or displaying a different buffer in a -window. +A normal hook that is run every time the window configuration of a frame +changes. Window configuration changes include splitting and deleting +windows and the display of a different buffer in a window. Resizing the +frame or individual windows do not count as configuration changes. Use +@code{window-size-change-functions}, see above, when you want to track +size changes that are not caused by the deletion or creation of windows. The buffer-local part of this hook is run once for each window on the affected frame, with the relevant window selected and its buffer |