File: org-persist.el.html

This file implements persistent cache storage across Emacs sessions. Both global and buffer-local data can be stored. This implementation is not meant to be used to store important data - all the caches should be safe to remove at any time.

Example usage:

1. Temporarily cache Elisp symbol value to disk. Remove upon
   closing Emacs:
   (org-persist-write 'variable-symbol)
   (org-persist-read 'variable-symbol) ;; read the data later
2. Temporarily cache a remote URL file to disk. Remove upon
   closing Emacs:
   (org-persist-write 'url "https://static.fsf.org/common/img/logo-new.png")
   (org-persist-read 'url "https://static.fsf.org/common/img/logo-new.png")
   org-persist-read will return the cached file location or nil if cached file
   has been removed.
3. Temporarily cache a file, including TRAMP path to disk:
   (org-persist-write 'file "/path/to/file")
4. Cache file or URL while some other file exists.
   (org-persist-register '(url "https://static.fsf.org/common/img/logo-new.png") '(:file "/path to the other file") :expiry 'never :write-immediately t)
   or, if the other file is current buffer file
   (org-persist-register '(url "https://static.fsf.org/common/img/logo-new.png") (current-buffer) :expiry 'never :write-immediately t)
5. Cache value of a Elisp variable to disk. The value will be
   saved and restored automatically (except buffer-local
   variables).
   ;; Until org-persist-default-expiry
   (org-persist-register 'variable-symbol)
   ;; Specify expiry explicitly
   (org-persist-register 'variable-symbol :expiry 'never)
   ;; Save buffer-local variable (buffer-local will not be
   ;; autoloaded!)
   (org-persist-register 'org-element--cache (current-buffer))
   ;; Save buffer-local variable preserving circular links:
   (org-persist-register 'org-element--headline-cache (current-buffer)
              :inherit 'org-element--cache)
6. Load variable by side effects assigning variable symbol:
   (org-persist-load 'variable-symbol (current-buffer))
7. Version variable value:
   (org-persist-register '((elisp variable-symbol) (version "2.0")))
8. Cancel variable persistence:
   (org-persist-unregister 'variable-symbol 'all) ; in all buffers
   (org-persist-unregister 'variable-symbol) ;; global variable
   (org-persist-unregister 'variable-symbol (current-buffer)) ;; buffer-local

Most common data type is variable data. However, other data types can also be stored.

Persistent data is stored in individual files. Each of the files can contain a collection of related data, which is particularly useful when, say, several variables cross-reference each-other's data-cells and we want to preserve their circular structure.

Each data collection can be associated with a local or remote file, its inode number, or contents hash. The persistent data collection can later be accessed using either file buffer, file, inode, or contents hash.

The data collections can be versioned and removed upon expiry.

In the code below I will use the following naming conventions:
1. Container :: a type of data to be stored
   Containers can store elisp variables, files, and version
   numbers. Each container can be customized with container
   options. For example, elisp container is customized with
   variable symbol. (elisp variable) is a container storing
   Lisp variable value. Similarly, (version "2.0") container
   will store version number.
2. Associated :: an object the container is associated with. The
   object can be a buffer, file, inode number, file contents hash,
   a generic key, or multiple of them. Associated can also be nil.
3. Data collection :: a list of containers linked to an associated
   object/objects. Each data collection can also have auxiliary
   records. Their only purpose is readability of the collection
   index.
4. Index file :: a file listing all the stored data collections.
5. Persist file :: a file holding data values or references to
   actual data values for a single data collection. This file
   contains an alist associating each data container in data
   collection with its value or a reference to the actual value.

All the persistent data is stored in org-persist-directory. The data collections are listed in org-persist-index-file and the actual data is stored in UID-style subfolders.

The org-persist-index-file stores the value of org-persist--index.

Each collection is represented as a plist containing the following properties:
- :container : list of data containers to be stored in single
                   file;
- :persist-file: data file name;
- :associated : list of associated objects;
- :last-access : last date when the container has been accessed;
- :expiry : list of expiry conditions.
- all other keywords are ignored

The available types of data containers are:
1. (file variable-symbol) or just variable-symbol :: Storing
   elisp variable data.
2. (file) :: Store a copy of the associated file preserving the
   extension.
   (file "/path/to/a/file") :: Store a copy of the file in path.
3. (version "version number") :: Version the data collection.
    If the stored collection has different version than "version
    number", disregard it.
4. (url) :: Store a downloaded copy of URL object.

The data collections can expire, in which case they will be removed from the persistent storage at the end of Emacs session. The expiry condition can be set when saving/registering data containers. The expirty condition can be never - data will never expire; nil - data will expire at the end of current Emacs session; a number - data will expire after the number days from last access; a function - data will expire if the function, called with a single argument - collection, returns non-nil.

Data collections associated with files will automatically expire when the file is removed. If the associated file is remote, the expiry is controlled by org-persist-remote-files instead.

Data loading/writing can be more accurately controlled using org-persist-before-write-hook, org-persist-before-read-hook, and org-persist-after-read-hook.

Defined variables (14)

Defined functions (47)

Defined faces (0)