[elpa] externals/persist ac30592 2/3: First release ready

[Phillip Lord]

branch: externals/persist
commit ac305927c792998d0a85cd5cb41d4e219001791e
Author: Phillip Lord <address@hidden>
Commit: Phillip Lord <address@hidden>

    First release ready
---
 .gitignore   |   2 +
 Makefile     |   3 ++
 persist.el   |  63 ++++++++++++++++++-------
 persist.texi | 147 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 198 insertions(+), 17 deletions(-)

diff --git a/.gitignore b/.gitignore
index fac3642..eea17b8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,4 @@
 /.cask
 /makefile-local
+/persist.html
+/dist/
diff --git a/Makefile b/Makefile
index e0f1c02..fda2dde 100644
--- a/Makefile
+++ b/Makefile
@@ -18,3 +18,6 @@ just-test:
 
 install:
        $(EMACS_ENV) $(CASK) install
+
+html:
+       texi2html persist.texi
diff --git a/persist.el b/persist.el
index 00b0fc3..a87728d 100644
--- a/persist.el
+++ b/persist.el
@@ -30,23 +30,21 @@
 ;; This package provides variables which persist across sessions.
 
 ;; The main entry point is `persist-defvar' which behaves like
-;; `defvar' but which persists the variables between session. Variables
-;; are automatically saved when emacs exits.
+;; `defvar' but which persists the variables between session.  Variables
+;; are automatically saved when Emacs exits.
 
 ;; Other useful functions are `persist-save' which saves the variable
 ;; immediately, `persist-load' which loads the saved value,
 ;; `persist-reset' which resets to the default value.
 
 ;; Values are stored in a directory in `user-emacs-directory', using
-;; one file per value. This makes it easy to delete or remove unused
+;; one file per value.  This makes it easy to delete or remove unused
 ;; variables.
 
 ;;; Code:
-
 (defvar persist--directory-location
   (concat user-emacs-directory "persist/")
-  "The location of persist directory."
-  )
+  "The location of persist directory.")
 
 (defvar persist--symbols nil
   "List of symbols to persist.")
@@ -55,33 +53,58 @@
   "Special hook run on loading a variable.
 
 Hook functions are called with two values: the symbol and the
-value it will be set to. If any function returns nil, the
+value it will be set to.  If any function returns nil, the
 variable is not set to the value.")
 
 (defun persist--file-location (symbol)
+  "Return the file name at which SYMBOL does or will persist."
   (concat persist--directory-location (symbol-name symbol)))
 
 (defmacro persist-defvar (symbol initvalue docstring)
+  "Define SYMBOL as a persistant variable and return SYMBOL.
+
+This form is nearly equivalent to `defvar', except that the
+variable persists between Emacs sessions.
+
+It does not support the optional parameters.  Both INITVALUE and
+DOCSTRING need to be given."
+  ;; We cannot distinguish between calls with initvalue of nil and a
+  ;; single parameter call. Unfortunately, these two calls have
+  ;; different semantics -- the single arity shuts up the byte
+  ;; compiler, but does not define the symbol. So, don't support a
+  ;; single arity persist-defvar.
+
+  ;; Don't support 2-arity calls either because we are lazy and
+  ;; because if you want to persist it, you want to doc it.
   (let ((form
-         `(defvar ,symbol ,initvalue ,docstring)
-         ))
+         `(defvar ,symbol ,initvalue ,docstring)))
     (persist-symbol symbol initvalue)
     (persist-load symbol)
     form))
 
-(defun persist-symbol (symbol initvalue)
-  (add-to-list 'persist--symbols symbol)
-  (put symbol 'persist t)
-  (put symbol 'persist-default initvalue))
+(defun persist-symbol (symbol &optional initvalue)
+  "Make SYMBOL a persistant variable.
 
-;; Do we want a type checker or other assertion mechanism, that if it
-;; fails just resets to the default. Perhaps a single hook?
+If non-nil, INITVALUE is the value to which SYMBOL will be set if
+`persist-reset' is called.  Otherwise, the INITVALUE will be the
+current `symbol-value' of SYMBOL.
+
+INITVALUE is set for the session and will itself not persist
+across sessions."
+  (let ((initvalue (or initvalue (symbol-value symbol))))
+    (add-to-list 'persist--symbols symbol)
+    (put symbol 'persist t)
+    (put symbol 'persist-default initvalue)))
 
 (defun persist--persistant-p (symbol)
+  "Return non-nil if SYMBOL is a persistant variable."
   (get symbol 'persist))
 
-;; specifically save a variable NOW
 (defun persist-save (symbol)
+  "Save SYMBOL now.
+
+Normally, it should not be necessary to call this explicitly, as
+variables persist automatically when Emacs exits."
   (unless (persist--persistant-p symbol)
     (error (format
             "Symbol %s is not persistant" symbol)))
@@ -93,14 +116,16 @@ variable is not set to the value.")
                   (persist--file-location symbol)
                   nil 'quiet)))
 
-;; Delete the saved persistent value and reset to default
 (defun persist-default (symbol)
+  "Return the default value for SYMBOL."
   (get symbol 'persist-default))
 
 (defun persist-reset (symbol)
+  "Reset the value of SYMBOL to the default."
   (set symbol (persist-default symbol)))
 
 (defun persist-load (symbol)
+  "Load the saved value of SYMBOL."
   (when (file-exists-p (persist--file-location symbol))
     (with-temp-buffer
       (insert-file-contents (persist--file-location symbol))
@@ -110,11 +135,15 @@ variable is not set to the value.")
           (set symbol val))))))
 
 (defun persist-unpersist (symbol)
+  "Stop the value in SYMBOL from persisting.
+
+This does not remove any saved value of SYMBOL."
   (put symbol 'persist nil)
   (setq persist--symbols
         (remove symbol persist--symbols)))
 
 (defun persist--save-all ()
+  "Save all persistant symbols."
   (mapc 'persist-save persist--symbols))
 
 ;; Save on kill-emacs-hook anyway
diff --git a/persist.texi b/persist.texi
new file mode 100644
index 0000000..2309f88
--- /dev/null
+++ b/persist.texi
@@ -0,0 +1,147 @@
+\input texinfo
+@setfilename persist.info
+@settitle persist persistant variables
+
+@dircategory Emacs
+@direntry
+* Persist: (persist).  Persistant variables for Emacs.
+@end direntry
+
+@copying
+Copyright @copyright{} 2019 Phillip Lord
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover, or Back-Cover Texts.  A copy of
+the license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+This document is part of a collection distributed under the GNU Free
+Documentation License.  If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+
+All Emacs Lisp code contained in this document may be used, distributed,
+and modified without restriction.
+@end quotation
+@end copying
+
+@titlepage
+@title Persist -- Persistant Variables for Emacs
+@author by Phillip Lord
+@page
+@insertcopying
+@end titlepage
+
+@contents
+
+@node Top
+@top Persist -- Persistant Variables for Emacs
+
+Perist is a library for making variables persistant; that it, their
+state can be changed from the default and the new value will remain even
+after Emacs has been closed and restarted.
+
+@menu
+* Persist::                     Simple Usage
+* The details::        All functions for interacting with Persist
+* Comparison::                  How this relates to other, similar techniques
+* Implementation::              How variables are saved
+@end menu
+
+@node Persist
+@section Persist
+
+This section describes simple usage of persist.
+
+@defmac persist-defvar (var initvalue docstring) body@dots{}
+This macro is equivalent in form to @code{defvar}, except any changes to
+the value of @code{var} will persist between sessions.  This macro does
+not support the lower arity versions of @code{defvar}. Both an
+@code{initvalue} and @code{docstring} needs to be provided.
+@end defmac
+
+@example
+@group
+(persist-defvar my-persistant-variable 10
+   "A variable of no purpose.
+   
+This variable is persistant between sessions")
+@end group
+@end example
+
+
+@node The details
+@section The details
+
+
+@defmac persist-defvar (var initvalue docstring) body@dots{}
+This macro is equivalent to @code{defvar} and can be used to make a
+variable persistant.
+@end defmac
+
+@defun persist-symbol (symbol &optional initvalue)
+This function takes @code{symbol} for an existing, non-persistant variable
+and makes it persistant. If @code{initvalue} is not given, then the
+current value is used. For package developers, @code{persist-defvar}
+would generally be prefered; this function might be useful for making
+third-party variables persistant.
+@end defun
+
+@example
+@group
+(defvar my-persistant-variable 10
+    "A variable of no purpose")
+
+(persist-symbol 'my-persistant-variable 10)
+@end group
+@end example
+
+@defun persist-save (symbol)
+This function saves @code{symbol} immediately rather than waiting till
+the normal time
+@end defun
+
+
+@defun persist-default (symbol)
+Return the default value for @code{symbol}. The default value is
+actually set for each session and does not persist from session to
+session, although if the value is set by either @code{persist-defvar} or
+@code{persist-symbol} saved it in a file, it will be set to the same
+value across sessions.
+@end defun
+
+@defun persist-reset (symbol)
+Change the value of @code{symbol} to the last saved value if it exists.
+@end defun
+
+@node Comparison
+@section Comparison
+
+There are several other packages which also persist aspects of Emacs
+across sessions, however, these fulfil a different purpose.
+
+Custom persists values of variables across sessions. However, it does
+this for user options, and is associated with a user interface for
+editing the value.
+
+desktop.el is also user-centric and is aimed at persisting the session
+in terms of buffers, modes and minor modes. It can be used to persist
+individual variables, but this will also save the session which the user
+may or may not want.
+
+savehist.el can save individual variables but, as with desktop.el, is a
+a global setting and has other implications such as saving mini-buffer
+history.
+
+@node Implementation
+@section Implementation
+
+persist is implemented by saving values for each symbol into an
+different. This makes it relatively easy to update or delete the stored
+value for a variable by hand if necessary. It should scale to 10 or 100
+variables, but may get a bit slow after this.
+
+@bye