branch: externals/greader
commit 221c6036d2e726a88d1c132797a5678462c96e02
Author: Michelangelo Rodriguez <[email protected]>
Commit: Michelangelo Rodriguez <[email protected]>
Fix/Refactor: Improve dictionary functions' robustness and docs
- In `greader-dict.el`:
- Remove a `goto-char` call in `greader-dict-substitute-words`,
which was a leftover from a previous refactoring.
- In `greader-dict-add-interactive`, prevent users from adding a
replacement that contains non-word characters. This avoids
unexpected behavior with text-to-speech engines.
- Improve the docstrings for `greader-dict-add` and
`greader-dict-filter-add` to better explain their behavior and
limitations, especially regarding input validation and the use of
special characters.
---
greader-dict.el | 24 ++++++++++++++++++------
1 file changed, 18 insertions(+), 6 deletions(-)
diff --git a/greader-dict.el b/greader-dict.el
index e6989b4db0..e6fbb90c72 100644
--- a/greader-dict.el
+++ b/greader-dict.el
@@ -370,8 +370,7 @@ as a word definition."
(concat (match-string 1)
(gethash match greader-dictionary)
(match-string 3))))
- (replace-match replacement nil t))
- (goto-char (point-min))))))
+ (replace-match replacement nil t))))))
;; This function adds to the `greader-dictionary' variable the
;; key/value pair that you pass as arguments.
@@ -382,7 +381,9 @@ A value of 0 indicates saving immediately."
(defun greader-dict-add (word replacement)
"Add the WORD REPLACEMENT pair to `greader-dictionary'.
If you want to add a partial replacement, you should
-add `\*'to the end of the WORD string parameter."
+add `\*'to the end of the WORD string parameter.
+This function only checks that WORD and REPLACEMENT are not the same.
+Other checks for record integrity are responsibility of the caller."
;; We prevent an infinite loop if disallowing that key and values
;; are the same.
(unless replacement
@@ -625,7 +626,8 @@ the current sentence."
key)
" with:
")
- nil nil(gethash key greader-dictionary)))
+ nil nil(gethash key
+ greader-dictionary)))
(greader-dict-add key value))
((region-active-p)
(when (= (count-words(region-beginning) (region-end)) 1)
@@ -658,7 +660,12 @@ modify: "
'word))))
(setq value (read-string (concat "substitute word " key
" with: ")
- (gethash key greader-dictionary)))
+ (gethash key
+ greader-dictionary)))
+ (when (string-match "\\W" value)
+ (user-error "Replacement cannot contain non-word constituents.
+If you want to listen a sign, please include it literally \(wrote by
+letters\) in the replacement"))
(greader-dict-add key value))
(setq key (read-string "Word to add or modify: " nil nil
(greader-dict--get-matches 'word)))
@@ -974,7 +981,12 @@ in the current sentence."
(string-suffix-p greader-dict-filter-indicator key))
(defun greader-dict-filter-add (key value)
- "Add KEY as a filter with associated VALUE."
+ "Add KEY as a filter with associated VALUE.
+KEY should be a regexp, and value can contain \"shi-groups\".
+You should hobey using punctuation signs in your replacement, apart
+from those that constitute the pattern.
+Adding a punctuation sign in the replacement part of a filter is
+considered undefined behavior."
(interactive
(let*
((key (read-string "filter (regexp) to add or modify: " nil nil
