Function: org-persist-read

org-persist-read is a byte-compiled function defined in org-persist.el.gz.

Signature

(org-persist-read CONTAINER &optional ASSOCIATED HASH-MUST-MATCH LOAD &key READ-RELATED)

Documentation

Restore CONTAINER data for ASSOCIATED.

When HASH-MUST-MATCH is non-nil, do not restore data if hash for ASSOCIATED file or buffer does not match.

ASSOCIATED can be a plist, a buffer, or a string. A buffer is treated as (:buffer ASSOCIATED). A string is treated as (:file ASSOCIATED).

When LOAD is non-nil, load the data instead of reading.

When READ-RELATED is non-nil, return the data stored alongside with CONTAINER as well. For example:

    (let ((info "test"))
      (org-persist-register
        `("My data" (elisp-data ,info))
        nil :write-immediately t))
    (org-persist-read "My data") ; => "My data"
    (org-persist-read "My data" nil nil nil
                      :read-related t) ; => ("My data" "test")

Source Code

;; Defined in /usr/src/emacs/lisp/org/org-persist.el.gz
(cl-defun org-persist-read (container &optional associated hash-must-match load &key read-related)
  "Restore CONTAINER data for ASSOCIATED.
When HASH-MUST-MATCH is non-nil, do not restore data if hash for
ASSOCIATED file or buffer does not match.

ASSOCIATED can be a plist, a buffer, or a string.
A buffer is treated as (:buffer ASSOCIATED).
A string is treated as (:file ASSOCIATED).

When LOAD is non-nil, load the data instead of reading.

When READ-RELATED is non-nil, return the data stored alongside with
CONTAINER as well.  For example:

    (let ((info \"test\"))
      (org-persist-register
        \\=`(\"My data\" (elisp-data ,info))
        nil :write-immediately t))
    (org-persist-read \"My data\") ; => \"My data\"
    (org-persist-read \"My data\" nil nil nil
                      :read-related t) ; => (\"My data\" \"test\")"
  (unless org-persist--index (org-persist--load-index))
  (setq associated (org-persist--normalize-associated associated))
  (setq container (org-persist--normalize-container container))
  (let* ((collection (org-persist--find-index `(:container ,container :associated ,associated)))
         (persist-file
          (when collection
            (org-file-name-concat
             org-persist-directory
             (plist-get collection :persist-file))))
         (data nil))
    (when (and collection
               (or (not (plist-get collection :expiry)) ; current session
                   (not (org-persist--gc-expired-p
                       (plist-get collection :expiry) collection)))
               (or (not hash-must-match)
                   (and (plist-get associated :hash)
                        (equal (plist-get associated :hash)
                               (plist-get (plist-get collection :associated) :hash))))
               (or (file-exists-p persist-file)
                   ;; Attempt to write data if it is not yet written.
                   (progn
                     (org-persist-write container associated 'no-read)
                     (file-exists-p persist-file))))
      (unless (seq-find (lambda (v)
                          (run-hook-with-args-until-success 'org-persist-before-read-hook v associated))
                        (plist-get collection :container))
        (setq data (or (gethash persist-file org-persist--write-cache)
                       (org-persist--read-elisp-file persist-file)))
        (when data
          (cl-loop for c in (plist-get collection :container)
                   with result = nil
                   do
                   (when (or read-related
                             (equal c container)
                             (member c container))
                     (if load
                         (push (org-persist-load:generic c (alist-get c data nil nil #'equal) collection) result)
                       (push (org-persist-read:generic c (alist-get c data nil nil #'equal) collection) result)))
                   (run-hook-with-args 'org-persist-after-read-hook c associated)
                   finally return (if (= 1 (length result)) (car result) (nreverse result))))))))