mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-11-22 07:09:54 +00:00
Code Issues Releases Activity

Brush up doc strings and terminology in plstore.el

Browse Source 
* lisp/plstore.el (plstore-encoded, plstore-passphrase-callback-function)
(plstore--init-from-buffer, plstore-revert, plstore-close)
(plstore--merge-secret, plstore--decrypt, plstore--match, plstore-find)
(plstore-get, plstore-put, plstore-delete, plstore--insert-buffer)
(plstore-save, plstore--encode, plstore--decode)
(plstore--write-contents-functions, plstore-mode-decoded)
(plstore-mode): Brush up doc strings and documentation in general.
Fix terminology, in particular spurious occurences of all uppercase
"PLSTORE".  (Bug#63627)
This commit is contained in:
Jens Schmidt 2023-05-22 21:47:13 +02:00 committed by Eli Zaretskii
parent 372bc1278c
commit 2e20e318da
1 changed files with 52 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

70
lisp/plstore.el
View File

@ -78,7 +78,7 @@
;; Editing:
;;
;; This file also provides `plstore-mode', a major mode for editing
;; the PLSTORE format file. Visit a non-existing file and put the
;; the plstore format file. Visit a non-existing file and put the
;; following line:
;;
;; (("foo" :host "foo.example.org" :secret-user "user"))
@ -235,10 +235,13 @@ symmetric encryption will be used."
(put 'plstore-encrypt-to 'permanent-local t)
(defvar plstore-encoded nil)
(defvar plstore-encoded nil
"Non-nil if the current buffer shows the decoded alist.") ; [sic!]
(put 'plstore-encoded 'permanent-local t)
;;; EasyPG callback functions.
(defvar plstore-cache-passphrase-for-symmetric-encryption nil)
(defvar plstore-passphrase-alist nil)
@ -255,11 +258,11 @@ symmetric encryption will be used."
(cons entry
plstore-passphrase-alist)))
(setq passphrase
(read-passwd (format "Passphrase for PLSTORE %s: "
(read-passwd (format "Passphrase for plstore %s: "
(plstore--get-buffer plstore))))
(setcdr entry (copy-sequence passphrase))
passphrase)))
(read-passwd (format "Passphrase for PLSTORE %s: "
(read-passwd (format "Passphrase for plstore %s: "
(plstore--get-buffer plstore)))))
(defun plstore-progress-callback-function (_context _what _char current total
@ -269,6 +272,8 @@ symmetric encryption will be used."
(message "%s...%d%%" handback
(if (> total 0) (floor (* (/ current (float total)) 100)) 0))))
;;; Core functions.
(defun plstore--get-buffer (arg)
(aref arg 0))
@ -307,6 +312,7 @@ symmetric encryption will be used."
(vector buffer alist encrypted-data secret-alist merged-alist))
(defun plstore--init-from-buffer (plstore)
"Parse current buffer and initialize PLSTORE from it."
(goto-char (point-min))
(when (looking-at ";;; public entries")
(forward-line)
@ -337,16 +343,20 @@ symmetric encryption will be used."
store)))
(defun plstore-revert (plstore)
"Replace current data in PLSTORE with the file on disk."
"Replace current data in PLSTORE from its associated file."
(with-current-buffer (plstore--get-buffer plstore)
(revert-buffer t t)
(plstore--init-from-buffer plstore)))
(defun plstore-close (plstore)
"Destroy a plstore instance PLSTORE."
"Destroy plstore instance PLSTORE."
(kill-buffer (plstore--get-buffer plstore)))
(defun plstore--merge-secret (plstore)
"Determine the merged alist of PLSTORE.
Create the merged alist as a copy of the template alist with all
placeholder properties that have corresponding properties in the
secret alist replaced by their plain-text secret properties."
(let ((alist (plstore--get-secret-alist plstore))
modified-alist
modified-plist
@ -365,19 +375,26 @@ symmetric encryption will be used."
modified-entry (assoc (car entry) modified-alist)
modified-plist (cdr modified-entry))
(while plist
;; Search for a placeholder property in the merged alist
;; corresponding to the current secret property.
(setq placeholder
(plist-member
modified-plist
(intern (concat ":secret-"
(substring (symbol-name (car plist)) 1)))))
;; Replace its name with the real, secret property name.
(if placeholder
(setcar placeholder (car plist)))
;; Update its value to the plain-text secret property value.
(setq modified-plist
(plist-put modified-plist (car plist) (car (cdr plist))))
(setq plist (nthcdr 2 plist)))
(setcdr modified-entry modified-plist))))
(defun plstore--decrypt (plstore)
"Decrypt the encrypted data of PLSTORE.
Update its internal alists and other data structures
accordingly."
(if (plstore--get-encrypted-data plstore)
(let ((context (epg-make-context 'OpenPGP))
plain)
@ -404,6 +421,11 @@ symmetric encryption will be used."
(plstore--set-encrypted-data plstore nil))))
(defun plstore--match (entry keys skip-if-secret-found)
"Return whether plist KEYS matches ENTRY.
ENTRY should be a key of the merged alist of a PLSTORE. This
function returns nil if KEYS do not match ENTRY, t if they match,
and symbol `secret' if the secret alist needs to be consulted to
perform a match."
(let ((result t) key-name key-value prop-value secret-name)
(while keys
(setq key-name (car keys)
@ -425,11 +447,10 @@ symmetric encryption will be used."
result))
(defun plstore-find (plstore keys)
"Perform search on PLSTORE with KEYS.
KEYS is a plist."
"Return all PLSTORE entries matching plist KEYS."
(let (entries alist entry match decrypt plist)
;; First, go through the merged plist alist and collect entries
;; matched with keys.
;; First, go through the merged alist and collect entries matched
;; by the keys.
(setq alist (plstore--get-merged-alist plstore))
(while alist
(setq entry (car alist)
@ -445,7 +466,7 @@ KEYS is a plist."
plist nil))
(setq plist (nthcdr 2 plist)))
(setq entries (cons entry entries)))))
;; Second, decrypt the encrypted plist and try again.
;; Second, decrypt the plstore and try again.
(when decrypt
(setq entries nil)
(plstore--decrypt plstore)
@ -459,7 +480,8 @@ KEYS is a plist."
(nreverse entries)))
(defun plstore-get (plstore name)
"Get an entry with NAME in PLSTORE."
"Return the entry named NAME in PLSTORE.
Return nil if there is none."
(let ((entry (assoc name (plstore--get-merged-alist plstore)))
plist)
(setq plist (cdr entry))
@ -473,7 +495,7 @@ KEYS is a plist."
entry))
(defun plstore-put (plstore name keys secret-keys)
"Put an entry with NAME in PLSTORE.
"Put an entry named NAME in PLSTORE.
KEYS is a plist containing non-secret data.
SECRET-KEYS is a plist containing secret data."
(let (entry
@ -512,7 +534,7 @@ SECRET-KEYS is a plist containing secret data."
(plstore--merge-secret plstore)))
(defun plstore-delete (plstore name)
"Delete an entry with NAME from PLSTORE."
"Delete the first entry named NAME from PLSTORE."
(let ((entry (assoc name (plstore--get-alist plstore))))
(if entry
(plstore--set-alist
@ -531,6 +553,8 @@ SECRET-KEYS is a plist containing secret data."
(defvar pp-escape-newlines)
(defun plstore--insert-buffer (plstore)
"Insert the file representation of PLSTORE at point.
Assumes that PLSTORE has been decrypted."
(insert ";;; public entries -*- mode: plstore -*- \n"
(pp-to-string (plstore--get-alist plstore)))
(if (plstore--get-secret-alist plstore)
@ -565,12 +589,14 @@ If no one is selected, symmetric encryption will be performed. "
(insert ";;; secret entries\n" (pp-to-string cipher)))))
(defun plstore-save (plstore)
"Save the contents of PLSTORE associated with a FILE."
"Save PLSTORE to its associated file."
(with-current-buffer (plstore--get-buffer plstore)
(erase-buffer)
(plstore--insert-buffer plstore)
(save-buffer)))
;;; plstore mode.
;; The functions related to plstore mode unfortunately introduce yet
;; another alist format ("decoded alist"). After executing the "foo",
;; "bar", "baz" example from above the decoded alist of the plstore
@ -587,6 +613,7 @@ If no one is selected, symmetric encryption will be performed. "
;; `plstore-encoded' is non-nil if a buffer shows the decoded form.
(defun plstore--encode (plstore)
"Return the printed representation of the decoded alist of PLSTORE."
(plstore--decrypt plstore)
(let ((merged-alist (plstore--get-merged-alist plstore)))
(concat "("
@ -611,6 +638,9 @@ If no one is selected, symmetric encryption will be performed. "
")")))
(defun plstore--decode (string)
"Create a plstore instance from STRING.
STRING should be the printed representation of a decoded alist of
some plstore."
(let* ((alist (car (read-from-string string)))
(pointer alist)
secret-alist
@ -618,7 +648,7 @@ If no one is selected, symmetric encryption will be performed. "
entry)
(while pointer
(unless (stringp (car (car pointer)))
(error "Invalid PLSTORE format %s" string))
(error "Invalid plstore format %s" string))
(setq plist (cdr (car pointer)))
(while plist
(when (string-match "\\`:secret-" (symbol-name (car plist)))
@ -638,6 +668,10 @@ If no one is selected, symmetric encryption will be performed. "
(plstore--make nil alist nil secret-alist)))
(defun plstore--write-contents-functions ()
"Convert the decoded form of a plstore in the current buffer.
Convert it to the regular file representation of a plstore if
needed. This function is used on hook `write-contents-functions'
in plstore mode buffers."
(when plstore-encoded
(let ((store (plstore--decode (buffer-string)))
(file (buffer-file-name)))
@ -675,7 +709,7 @@ If no one is selected, symmetric encryption will be performed. "
(erase-buffer)
(insert
(substitute-command-keys "\
;;; You are looking at the decoded form of the PLSTORE file.\n\
;;; You are looking at the decoded form of the plstore file.\n\
;;; To see the original form content, do \\[plstore-mode-toggle-display]\n\n"))
(insert (plstore--encode store))
(set-buffer-modified-p nil)
@ -690,7 +724,7 @@ If no one is selected, symmetric encryption will be performed. "
;;;###autoload
(define-derived-mode plstore-mode emacs-lisp-mode "PLSTORE"
"Major mode for editing PLSTORE files."
"Major mode for editing plstore files."
(make-local-variable 'plstore-encoded)
(add-hook 'write-contents-functions #'plstore--write-contents-functions)
(define-key plstore-mode-map "\C-c\C-c" #'plstore-mode-toggle-display)