[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/org 13e78df46a 6/9: * lisp/org-persist.el: Update comme
From: |
ELPA Syncer |
Subject: |
[elpa] externals/org 13e78df46a 6/9: * lisp/org-persist.el: Update commentary |
Date: |
Thu, 29 Dec 2022 04:58:03 -0500 (EST) |
branch: externals/org
commit 13e78df46a0829dd7e984665a13a0556a24590f7
Author: Ihor Radchenko <yantar92@posteo.net>
Commit: Ihor Radchenko <yantar92@posteo.net>
* lisp/org-persist.el: Update commentary
Add more examples and document recent additions.
---
lisp/org-persist.el | 97 +++++++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 91 insertions(+), 6 deletions(-)
diff --git a/lisp/org-persist.el b/lisp/org-persist.el
index b2a92667a8..9d973606fd 100644
--- a/lisp/org-persist.el
+++ b/lisp/org-persist.el
@@ -27,24 +27,44 @@
;; implementation is not meant to be used to store important data -
;; all the caches should be safe to remove at any time.
;;
+;; Entry points are `org-persist-register', `org-persist-write',
+;; `org-persist-read', and `org-persist-load'.
+;;
+;; `org-persist-register' will mark the data to be stored. By
+;; default, the data is written on disk before exiting Emacs session.
+;; Optionally, the data can be written immediately.
+;;
+;; `org-persist-write' will immediately write the data onto disk.
+;;
+;; `org-persist-read' will read the data and return its value or list
+;; of values for each requested container.
+;;
+;; `org-persist-load' will read the data with side effects. For
+;; example, loading `elisp' container will assign the values to
+;; variables.
+;;
;; 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).
@@ -58,11 +78,25 @@
;; ;; 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:
+;;
+;; 8. Define a named container group:
+;;
+;; (let ((info1 "test")
+;; (info2 "test 2"))
+;; (org-persist-register
+;; `((version "Named data") (elisp info1 local) (elisp info2 local))
+;; nil :write-immediately t))
+;; (org-persist-read
+;; '(version "Named data")
+;; nil nil nil :read-related t) ; => ("Named data" "test" "test2")
+;;
+;; 9. 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
@@ -82,7 +116,8 @@
;;
;; The data collections can be versioned and removed upon expiry.
;;
-;; In the code below I will use the following naming conventions:
+;; 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
@@ -90,14 +125,47 @@
;; variable symbol. (elisp variable) is a container storing
;; Lisp variable value. Similarly, (version "2.0") container
;; will store version number.
+;;
+;; Container can also refer to a list of simple containers:
+;;
+;; ;; Three containers stored together.
+;; '((elisp variable) (file "/path") (version "x.x"))
+;;
+;; Providing a single container from the list to `org-persist-read'
+;; is sufficient to retrieve all the containers.
+;;
+;; Example:
+;;
+;; (org-persist-register '((version "My data") (file "/path/to/file"))
'(:key "key") :write-immediately t)
+;; (org-persist-read '(version "My data") '(:key "key")) ;; => '("My data"
"/path/to/file/copy")
+;;
;; 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.
+;;
+;; Example:
+;;
+;; '(:file "/path/to/file" :inode number :hash buffer-hash :key
arbitrary-key)
+;;
+;; When several objects are associated with a single container, it
+;; is not necessary to provide them all to access the container.
+;; Just using a single :file/:inode/:hash/:key is sufficient.
+;;
;; 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.
+;;
+;; Example:
+;;
+;; (:container
+;; ((index "2.7"))
+;; :persist-file "ba/cef3b7-e31c-4791-813e-8bd0bf6c5f9c"
+;; :associated nil :expiry never
+;; :last-access 1672207741.6422956 :last-access-hr
"2022-12-28T09:09:01+0300")
+;;
;; 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
@@ -111,6 +179,7 @@
;;
;; Each collection is represented as a plist containing the following
;; properties:
+;;
;; - `:container' : list of data continers to be stored in single
;; file;
;; - `:persist-file': data file name;
@@ -120,15 +189,30 @@
;; - all other keywords are ignored
;;
;; The available types of data containers are:
-;; 1. (file variable-symbol) or just variable-symbol :: Storing
-;; elisp variable data.
+;; 1. (elisp variable-symbol scope) or just variable-symbol :: Storing
+;; elisp variable data. SCOPE can be
+;;
+;; - `nil' :: Use buffer-local value in associated :file or global
+;; value if no :file is associated.
+;; - string :: Use buffer-local value in buffer named STRING or
+;; with STRING `buffer-file-name'.
+;; - `local' :: Use symbol value in current scope.
+;; Note: If `local' scope is used without writing the
+;; value immediately, the actual stored value is
+;; undefined.
+;;
;; 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.
+;;
+;; 4. (url) :: Store a downloaded copy of URL object given by
+;; associated :file.
+;; (url "path") :: Use "path" instead of associated :file.
;;
;; The data collections can expire, in which case they will be removed
;; from the persistent storage at the end of Emacs session. The
@@ -145,7 +229,8 @@
;; 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'.
+;; `org-persist-before-write-hook', `org-persist-before-read-hook',
+;; and `org-persist-after-read-hook'.
;;; Code:
- [elpa] externals/org updated (5549357bf2 -> a9c0d4cde2), ELPA Syncer, 2022/12/29
- [elpa] externals/org e8cb52bd3e 1/9: org-persist-read: Attempt to write newly register data before reading, ELPA Syncer, 2022/12/29
- [elpa] externals/org f8428d0f3e 2/9: org-fold-core--isearch-show: Small refactoring, ELPA Syncer, 2022/12/29
- [elpa] externals/org 14bfe2841c 5/9: org-persist: Use `list-data-mode' for stored data, ELPA Syncer, 2022/12/29
- [elpa] externals/org 13e78df46a 6/9: * lisp/org-persist.el: Update commentary,
ELPA Syncer <=
- [elpa] externals/org a97b378ee5 4/9: org-persist-read: Do not return related containers by default, ELPA Syncer, 2022/12/29
- [elpa] externals/org ffec2db731 3/9: org-persist-write:elisp: Allow buffer-local/global elisp container scope, ELPA Syncer, 2022/12/29
- [elpa] externals/org b86989c8df 8/9: Merge branch 'bugfix', ELPA Syncer, 2022/12/29
- [elpa] externals/org a9c0d4cde2 9/9: org-occur-in-agenda-files: Respect agenda restriction, ELPA Syncer, 2022/12/29
- [elpa] externals/org dedf1cc21f 7/9: org-persist: Add more normalizations and new `elisp-data' container, ELPA Syncer, 2022/12/29