diff options
Diffstat (limited to 'doc/lispref/variables.texi')
| -rw-r--r-- | doc/lispref/variables.texi | 190 |
1 files changed, 164 insertions, 26 deletions
diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index a1d1919b4bf..98a9487aea9 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -44,6 +44,7 @@ representing the variable. * Variables with Restricted Values:: Non-constant variables whose value can @emph{not} be an arbitrary Lisp object. * Generalized Variables:: Extending the concept of variables. +* Multisession Variables:: Variables that survive restarting Emacs. @end menu @node Global Variables @@ -363,7 +364,7 @@ where you are in Emacs. @cindex evaluation error @cindex infinite recursion This variable defines the limit on the total number of local variable -bindings and @code{unwind-protect} cleanups (see @ref{Cleanups,, +bindings and @code{unwind-protect} cleanups (@pxref{Cleanups,, Cleaning Up from Nonlocal Exits}) that are allowed before Emacs signals an error (with data @code{"Variable binding depth exceeds max-specpdl-size"}). @@ -686,7 +687,7 @@ entire computation of the value into the @code{defvar}, like this: @example (defvar my-mode-map (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) + (keymap-set map "C-c C-a" 'my-command) @dots{} map) @var{docstring}) @@ -702,25 +703,6 @@ important if the user has run hooks to alter part of the contents (such as, to rebind keys). Third, evaluating the @code{defvar} form with @kbd{C-M-x} will reinitialize the map completely. - Putting so much code in the @code{defvar} form has one disadvantage: -it puts the documentation string far away from the line which names the -variable. Here's a safe way to avoid that: - -@example -(defvar my-mode-map nil - @var{docstring}) -(unless my-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) - @dots{} - (setq my-mode-map map))) -@end example - -@noindent -This has all the same advantages as putting the initialization inside -the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on -each form, if you do want to reinitialize the variable. - @node Accessing Variables @section Accessing Variable Values @@ -1695,12 +1677,14 @@ buffer-local variables interactively. @end deffn @cindex local variables, killed by major mode -@defun kill-all-local-variables +@defun kill-all-local-variables &optional kill-permanent This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as permanent and local -hook functions that have a non-@code{nil} @code{permanent-local-hook} -property (@pxref{Setting Hooks}). As a result, the buffer will see -the default values of most variables. +current buffer. As a result, the buffer will see the default values +of most variables. By default, for variables marked as permanent and +local hook functions that have a non-@code{nil} +@code{permanent-local-hook} property (@pxref{Setting Hooks}) won't be +killed, but if the optional @var{kill-permanent} argument is +non-@code{nil}, even these variables will be killed. This function also resets certain other information pertaining to the buffer: it sets the local keymap to @code{nil}, the syntax table to the @@ -2769,3 +2753,157 @@ form that has not already had an appropriate expansion defined. In Common Lisp, this is not an error since the function @code{(setf @var{func})} might be defined later. @end quotation + +@node Multisession Variables +@section Multisession Variables + +@cindex multisession variable + When you set a variable to a value and then close Emacs and restart +it, that value won't be automatically restored. Users usually set +normal variables in their startup files, or use Customize +(@pxref{Customization}) to set user options permanently, and various +packages have various files wher they store the data (e.g., Gnus +stores this in @file{.newsrc.eld} and the URL library stores cookies +in @file{~/.emacs.d/url/cookies}). + +For things in between these two extremes (i.e., configuration which +goes in the startup file, and massive application state that goes into +separate files), Emacs provides a facility to replicate data between +sessions called @dfn{multisession variables}. (This facility may not +be available on all systems.) To give you an idea of how these are +meant to be used, here's a small example: + +@lisp +@group +(define-multisession-variable foo-var 0) +(defun my-adder (num) + (interactive "nAdd number: ") + (setf (multisession-value foo) + (+ (multisession-value foo) num)) + (message "The new number is: %s" (multisession-value foo))) +@end group +@end lisp + +@noindent +This defines the variable @code{foo-var} and binds it to a special +multisession object which is initialized with the value @samp{0} (if +the variable doesn't already exist from a previous session). The +@code{my-adder} command queries the user for a number, adds this to +the old (possibly saved value), and then saves the new value. + +This facility isn't meant to be used for huge data structures, but +should be performant for most values. + +@defmac define-multisession-variable name initial-value &optional doc &rest args +This macro defines @var{name} as a multisession variable, and gives it +the @var{initial-value} if this variable hasn't been assigned a value +earlier. @var{doc} is the doc string, and several keyword arguments can +be used in @var{args}: + +@table @code +@item :package @var{package-symbol} +This keyword says that a multisession variable belongs to the package +specified by @var{package-symbol}. The combination of +@var{package-symbol} and @var{name} has to be unique. If +@var{package-symbol} isn't given, this will default to the first +``segment'' of the @var{name} symbol's name, which is the part of its +name up to and excluding the first @samp{-}. For instance, if +@var{name} is @code{foo-var} and @var{package-symbol} isn't given, +@var{package-symbol} will default to @code{foo}. + +@cindex synchronized multisession variables +@item :synchronized @var{bool} +Multisession variables can be @dfn{synchronized} if @var{bool} is +non-@code{nil}. This means that if there're two concurrent Emacs +instances running, and the other Emacs changes the multisession +variable @code{foo-var}, the current Emacs instance will retrieve that +modified data when accessing the value. If @var{synchronized} is +@code{nil} or missing, this won't happen, and the values in all +Emacs sessions using the variable will be independent of each other. + +@item :storage @var{storage} +Use the specified @var{storage} method. This can be either +@code{sqlite} (in Emacs compiled with SQLite support) or @code{files}. +If not given, this defaults to the value of the +@code{multisession-storage} variable, described below. +@end table +@end defmac + +@defun multisession-value variable +This function returns the current value of @var{variable}. If this +variable hasn't been accessed before in this Emacs session, or if it's +changed externally, it will be read in from external storage. If not, +the current value in this session is returned as is. It is an error +to call this function for a @var{variable} that is not a multisession +variable. + +Values retrieved via @code{multisession-value} may or may not be +@code{eq} to each other, but they will always be @code{equal}. + +This is a generalized variable (@pxref{Generalized Variables}), so the +way to update such a variable is to say, for instance: + +@lisp +(setf (multisession-value foo-bar) 'zot) +@end lisp + +Only Emacs Lisp values that have a readable print syntax +(@pxref{Printed Representation}) can be saved this way. + +If the multisession variable is synchronized, setting it may update +the value first. For instance: + +@lisp +(cl-incf (multisession-value foo-bar)) +@end lisp + +This first checks whether the value has changed in a different +Emacs instance, retrieves that value, and then adds 1 to that value and +stores it. But note that this is done without locking, so if many +instances are updating the value at the same time, it's unpredictable +which instance ``wins''. +@end defun + +@defun multisession-delete object +This function deletes @var{object} and its value from its persistent +storage. +@end defun + +@c FIXME: this lacks the documentation of the form of the arguments. +@defun make-multisession +You can also make persistent values that aren't tied to a specific +variable, but are tied to an explicit package and key. + +@example +(setq foo (make-multisession :package "mail" + :key "friends")) +(setf (multisession-value foo) 'everybody) +@end example + +This supports the same keywords as +@code{define-multisession-variable}, but also supports a +@code{:initial-value} keyword, which specifies the default value. +@end defun + +@defopt multisession-storage +This variable controls how the multisession variables are stored. It +value defaults to @code{files}, which means that the values are stored +in a one-file-per-variable structure inside the directory specified by +@code{multisession-directory}. If this value is @code{sqlite} +instead, the values are stored in an SQLite database; this is only +available if Emacs was built with SQLite support. +@end defopt + +@defopt multisession-directory +The multisession variables are stored under this directory, which +defaults to @file{multisession/} subdirectory of the +@code{user-emacs-directory}, which is typically +@file{~/.emacs.d/multisession/}. +@end defopt + +@findex multisession-edit-mode +@deffn Command list-multisession-values +This command pops up a buffer listing all the multisession variables, +and enters a special mode @code{multisession-edit-mode} which allows +you to delete them and edit their values. +@end deffn |