[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/org 4ec57a9453 16/31: org-persist: Update commentary
From: |
ELPA Syncer |
Subject: |
[elpa] externals/org 4ec57a9453 16/31: org-persist: Update commentary |
Date: |
Sat, 29 Jan 2022 04:58:04 -0500 (EST) |
branch: externals/org
commit 4ec57a94534c15e616c581d5d6fa138f4061e0b4
Author: Ihor Radchenko <yantar92@gmail.com>
Commit: Ihor Radchenko <yantar92@gmail.com>
org-persist: Update commentary
---
lisp/org-persist.el | 54 +++++++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 50 insertions(+), 4 deletions(-)
diff --git a/lisp/org-persist.el b/lisp/org-persist.el
index fad67e84c0..cd1a499e16 100644
--- a/lisp/org-persist.el
+++ b/lisp/org-persist.el
@@ -1,4 +1,4 @@
-;;; org-persist.el --- Persist data across Emacs sessions -*-
lexical-binding: t; -*-
+;;; org-persist.el --- Persist cached data across Emacs sessions -*-
lexical-binding: t; -*-
;; Copyright (C) 2021-2022 Free Software Foundation, Inc.
@@ -22,8 +22,46 @@
;;; Commentary:
;;
-;; This file implements persistant data storage across Emacs sessions.
-;; Both global and buffer-local data can be stored.
+;; This file implements persistant 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 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)
+;; 5. Load variable by side effects assigning variable symbol:
+;; (org-persist-load 'variable-symbol (current-buffer))
+;; 6. Version variable value:
+;; (org-persist-register '(("elisp" variable-symbol) (version "2.0")))
+;; 7. 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.
@@ -73,7 +111,7 @@
;; file;
;; - `:persist-file': data file name;
;; - `:associated' : list of associated objects;
-;; - `:last-access' : last date when the container has been read;
+;; - `:last-access' : last date when the container has been accessed;
;; - `:expiry' : list of expiry conditions.
;; - all other keywords are ignored
;;
@@ -95,6 +133,14 @@
;; 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'.
;;; Code:
- [elpa] externals/org fca80139ee 18/31: org-persist: Fix compatibility with Emacs 27, (continued)
- [elpa] externals/org fca80139ee 18/31: org-persist: Fix compatibility with Emacs 27, ELPA Syncer, 2022/01/29
- [elpa] externals/org dc52c0fe99 17/31: Fix native-comp warnings, ELPA Syncer, 2022/01/29
- [elpa] externals/org f3bd1dcb77 20/31: org-persist: Fix compiler warnings, ELPA Syncer, 2022/01/29
- [elpa] externals/org 1bc8389871 21/31: org-persist-read: Check expiry, ELPA Syncer, 2022/01/29
- [elpa] externals/org 6b175fb227 27/31: org-persist-register: Make return value meaningful with :write-immidiately, ELPA Syncer, 2022/01/29
- [elpa] externals/org f0e0716f54 28/31: org-element: Use new cache container format, ELPA Syncer, 2022/01/29
- [elpa] externals/org 19a383d9f4 29/31: org-persist-write-all: Speed up writing, ELPA Syncer, 2022/01/29
- [elpa] externals/org ac5742f296 31/31: Merge branch 'feature/org-persist-new-tidy', ELPA Syncer, 2022/01/29
- [elpa] externals/org 38a681fdae 05/31: org-element-cache-reset: Do not persist caches for non-file buffers, ELPA Syncer, 2022/01/29
- [elpa] externals/org 8821ff5811 09/31: org-persist-read: Do not try to read non-existing containers, ELPA Syncer, 2022/01/29
- [elpa] externals/org 4ec57a9453 16/31: org-persist: Update commentary,
ELPA Syncer <=
- [elpa] externals/org ec787fb218 19/31: org-persist: Implement "file" and "url" containers linked to other file, ELPA Syncer, 2022/01/29
- [elpa] externals/org 6a5874bb26 25/31: org-persist-write: Overwrite existing copy if write is requested, ELPA Syncer, 2022/01/29
- [elpa] externals/org 0e18c617cf 24/31: org-persist-write:index: Return index path on write, ELPA Syncer, 2022/01/29
- [elpa] externals/org eca678195b 23/31: org-persist-write: Return the written value on success, ELPA Syncer, 2022/01/29
- [elpa] externals/org 0526acd16f 22/31: org-persist-register: New optional keyword to force immidiate write, ELPA Syncer, 2022/01/29
- [elpa] externals/org caccec2c54 26/31: org-persist: Use symbols as container names, ELPA Syncer, 2022/01/29
- [elpa] externals/org 7014675226 30/31: org-mode: Fix cache loading order, ELPA Syncer, 2022/01/29
- [elpa] externals/org 1c79af13df 04/31: org-persist-gc: Fix when expiry is days and data is freshly created, ELPA Syncer, 2022/01/29