[nongnu] elpa/org-superstar e668df215c 016/162: Major cleanup: fixing inconsistencies spotted by flycheck

[Stefan Kangas]

branch: elpa/org-superstar
commit e668df215cc490981ed59101013ee6c02607163e
Author: D. Williams <d.williams@posteo.net>
Commit: D. Williams <d.williams@posteo.net>

    Major cleanup: fixing inconsistencies spotted by flycheck
    
    Code now compiles and runs through flycheck without warning.
    
    Inluded requires for implicitly used packages.
    
    Changed names to be consistent with package name.
    
    Fixed insufficient Emacs version requirement.
    
    Added pagebreaks (^L) for each section.
    
    Replacing (currently defunct) org-list-in-valid-context-p by a
    predicate suggested by Nicolas Goaziou on the org mailing list.
---
 org-superstar.el | 208 ++++++++++++++++++++++++++++++-------------------------
 1 file changed, 115 insertions(+), 93 deletions(-)

diff --git a/org-superstar.el b/org-superstar.el
index 37f73d89ee..851fa61589 100644
--- a/org-superstar.el
+++ b/org-superstar.el
@@ -7,7 +7,7 @@
 ;; Keywords: faces, outlines
 ;; Version: 0
 ;; Homepage: https://github.com/dw-github-mirror/org-superstar-mode
-;; Package-Requires: ((org "9.1.9") (emacs "26"))
+;; Package-Requires: ((org "9.1.9") (emacs "26.2"))
 
 ;; This file is NOT part of GNU Emacs.
 
@@ -48,6 +48,8 @@
 ;;; Code:
 
 (require 'org)
+(require 'org-element)
+(require 'wid-edit)
 
 (defgroup org-superstar nil
   "Use UTF8 bullets for headlines and plain lists."
@@ -55,7 +57,7 @@
 
 ;;; Bullet Variables
 
-(defcustom org-sstar-headline-bullets-list
+(defcustom org-superstar-headline-bullets-list
   '(;; Original ones nicked from org-bullets
     "◉"
     "○"
@@ -65,14 +67,14 @@
 It can contain any number of bullets, the Nth entry usually
 corresponding to the bullet used for level N.  The way this list
 is cycled through can use fine-tuned by customizing
-‘org-sstar-cycle-headline-bullets’.
+‘org-superstar-cycle-headline-bullets’.
 
 You should re-enable ‘\\[org-superstar-mode]’ after changing this
 variable for your changes to take effect."
     :group 'org-superstar
     :type '(repeat (string :tag "Bullet character")))
 
-(defcustom org-sstar-item-bullet-alist
+(defcustom org-superstar-item-bullet-alist
   '((?* . ?•)
     (?+ . ?➤)
     (?- . ?–))
@@ -88,11 +90,11 @@ variable for your changes to take effect."
                           (?- (character)))))
 
 ;;;###autoload
-(put 'org-sstar-leading-bullet
+(put 'org-superstar-leading-bullet
      'safe-local-variable
      #'char-or-string-p)
 
-(defcustom org-sstar-leading-bullet " ․"
+(defcustom org-superstar-leading-bullet " ․"
   "A special bullet used for leading stars.
 Normally, this variable is a character replacing the default
 stars.  If it’s a string, list, or vector, compose the
@@ -101,7 +103,7 @@ COMPONENTS argument.
 
 If ‘org-hide-leading-stars’ is nil, leading stars in a headline
 are represented as a sequence of this bullet using the face
-‘org-sstar-leading’.  Otherwise, this variable has no effect and
+‘org-superstar-leading’.  Otherwise, this variable has no effect and
 ‘org-mode’ covers leading stars using ‘org-hide’.
 
 You should re-enable ‘\\[org-superstar-mode]’ after changing this
@@ -131,7 +133,7 @@ variable for your changes to take effect."
 
 ;;; Other Custom Variables
 
-(defcustom org-sstar-prettify-leading-stars t
+(defcustom org-superstar-prettify-leading-stars t
   "Non-nil means prettify leading stars in headlines.
 
 It is a good idea to disable this feature when you run into any
@@ -145,7 +147,7 @@ variable for your changes to take effect."
           (const :tag "Prettify leading stars." t)
           (const :tag "Don’t prettify leading stars." nil)))
 
-(defcustom org-sstar-cycle-headline-bullets t
+(defcustom org-superstar-cycle-headline-bullets t
   "Non-nil means cycle through all available headline bullets.
 
 The following values are meaningful:
@@ -168,14 +170,16 @@ variable for your changes to take effect."
                    :format "Repeat the first %v entries exclusively.\n"
                    :size 8
                    :value 1
-                   :validate org-sstar--validate-hcycle)))
-
-(defun org-sstar--validate-hcycle (text-field)
-  "Validate integer values of ‘org-sstar-cycle-headline-bullets’ in TEXT-FIELD.
-If the integer exceeds the length of ‘org-sstar-headline-bullets-list’,
-set it to the length and raise an error."
+                   :validate org-superstar--validate-hcycle)))
+
+(defun org-superstar--validate-hcycle (text-field)
+  "Raise an error if TEXT-FIELD’s value is an invalid hbullet number.
+This function is used for ‘org-superstar-cycle-headline-bullets’.
+If the integer exceeds the length of
+‘org-superstar-headline-bullets-list’, set it to the length and
+raise an error."
   (let ((ncycle (widget-value text-field))
-        (maxcycle (org-sstar--hbullets)))
+        (maxcycle (org-superstar--hbullets)))
     (unless (<= 1 ncycle maxcycle)
       (widget-put
        text-field
@@ -184,11 +188,11 @@ set it to the length and raise an error."
       (widget-value-set text-field maxcycle)
       text-field)))
 
-(defcustom org-sstar-prettify-item-bullets t
+(defcustom org-superstar-prettify-item-bullets t
   "Non-nil means display plain lists bullets as UTF8 bullets.
 
 Each type of plain list bullet is associated with a
-corresponding UTF8 character in ‘org-sstar-item-bullet-alist’.
+corresponding UTF8 character in ‘org-superstar-item-bullet-alist’.
 
 You should re-enable ‘\\[org-superstar-mode]’ after changing this
 variable for your changes to take effect."
@@ -199,12 +203,12 @@ variable for your changes to take effect."
 
 ;;; Faces
 
-(defface org-sstar-leading
+(defface org-superstar-leading
   '((default . (:inherit default :foreground "gray")))
   "Face used to display prettified leading stars in a headline."
   :group 'org-superstar)
 
-(defface org-sstar-header-bullet
+(defface org-superstar-header-bullet
   '((default . nil))
   "Face containing distinguishing features headline bullets.
 This face is applied to header bullets \"on top of\" existing
@@ -215,14 +219,15 @@ currently in place.  Consequently, leaving all face 
properties
 unspecified inherits the org-level-X faces for header bullets."
   :group 'org-superstar)
 
-(defface org-sstar-item
+(defface org-superstar-item
   '((default . (:inherit default)))
   "Face used to display prettified item bullets."
   :group 'org-superstar)
 
+
 ;;; Functions
 
-(defun org-sstar-configure-like-org-bullets ()
+(defun org-superstar-configure-like-org-bullets ()
   "Configure ‘\\[org-superstar-mode]’ to approximate ‘\\[org-bullets-mode]’.
 This function automatically sets various custom variables, and
 therefore should only be called *once* per session, before any
@@ -237,168 +242,185 @@ fine-grained customization, it’s better to just set the 
variables
 you want.
 
 This changes the following variables:
-‘org-sstar-prettify-leading-stars’: Disabled.
-‘org-sstar-prettify-leading-stars’: Disabled.
-‘org-sstar-cycle-headline-bullets’: Enabled.
+‘org-superstar-prettify-leading-stars’: Disabled.
+‘org-superstar-prettify-leading-stars’: Disabled.
+‘org-superstar-cycle-headline-bullets’: Enabled.
 ‘org-hide-leading-stars’: Enabled.
 
 You should re-enable ‘\\[org-superstar-mode]’ after calling this
 function for your changes to take effect."
-  (setq org-sstar-prettify-leading-stars nil)
-  (setq org-sstar-cycle-headline-bullets t)
+  (setq org-superstar-prettify-leading-stars nil)
+  (setq org-superstar-cycle-headline-bullets t)
   (setq org-hide-leading-stars t)
   nil)
 
+
 ;;; Accessor Functions
 
-(defun org-sstar--hbullets ()
-    "Return the length of ‘org-sstar-headline-bullets-list’."
-  (length org-sstar-headline-bullets-list))
+(defun org-superstar--hbullets ()
+    "Return the length of ‘org-superstar-headline-bullets-list’."
+  (length org-superstar-headline-bullets-list))
 
-(defun org-sstar--hbullet (level)
+(defun org-superstar--hbullet (level)
   "Return the desired headline bullet replacement for LEVEL N.
 
-See also ‘org-sstar-cycle-headline-bullets’."
-  (let ((max-bullets org-sstar-cycle-headline-bullets)
+See also ‘org-superstar-cycle-headline-bullets’."
+  (let ((max-bullets org-superstar-cycle-headline-bullets)
         (n (1- level)))
     (string-to-char
      (cond ((integerp max-bullets)
-            (elt org-sstar-headline-bullets-list
+            (elt org-superstar-headline-bullets-list
                  (% n max-bullets)))
            (max-bullets
-            (elt org-sstar-headline-bullets-list
-                 (% n (org-sstar--hbullets))))
+            (elt org-superstar-headline-bullets-list
+                 (% n (org-superstar--hbullets))))
            (t
-            (elt org-sstar-headline-bullets-list
-                 (min n (1- (org-sstar--hbullets)))))))))
+            (elt org-superstar-headline-bullets-list
+                 (min n (1- (org-superstar--hbullets)))))))))
 
-(defun org-sstar--ibullet (bullet-string)
+(defun org-superstar--ibullet (bullet-string)
   "Return BULLET-STRINGs desired UTF-8 replacement.
 
 Each of the three regular plain list bullets +, - and * will be
-replaced by their corresponding entry in ‘org-sstar-item-bullet-alist’."
+replaced by their corresponding entry in ‘org-superstar-item-bullet-alist’."
   (or (cdr (assq (string-to-char bullet-string)
-                 org-sstar-item-bullet-alist))
+                 org-superstar-item-bullet-alist))
       (string-to-char bullet-string)))
 
+
 ;;; Fontification
 
-(defun org-sstar-in-valid-context-p ()
-  "Return t if the current match is in a meaningful context."
-  (org-list-in-valid-context-p))
-
-(defun org-sstar--prettify-ibullets ()
+;; ‘org-list-in-valid-context-p’ is currently not working.
+
+;; Explicitly returning t is redundant, but does not leak information
+;; about how the predicate is implemented.
+(defun org-superstar-plain-list-p ()
+  "Return non-nil if the current match is a proper plain list."
+  (save-match-data
+    (when (org-element-lineage (org-element-at-point)
+                               '(plain-list) t)
+      t)))
+
+(defun org-superstar-headline-or-inlinetask-p ()
+  "Return non-nil if the current match is a proper headline or inlinetask."
+  (save-match-data
+    (when (org-element-lineage (org-element-at-point)
+                               '(headline inlinetask) t)
+      t)))
+
+(defun org-superstar--prettify-ibullets ()
   "Prettify plain list bullets.
 
-This function uses ‘org-list-in-valid-context-p’ to avoid
+This function uses ‘org-superstar-plain-list-p’ to avoid
 prettifying bullets in (for example) source blocks."
-  (when (org-list-in-valid-context-p)
+  (when (org-superstar-plain-list-p)
     (let* ((current-bullet (match-string 1)))
       (compose-region (match-beginning 1)
                       (match-end 1)
-                      (org-sstar--ibullet current-bullet)))
+                      (org-superstar--ibullet current-bullet)))
 
-    'org-sstar-item))
+    'org-superstar-item))
 
-(defun org-sstar--unprettify-ibullets ()
-  "Revert all changes made to item bullets."
+(defun org-superstar--unprettify-ibullets ()
+  "Revert visual tweaks made to item bullets in current buffer."
   (save-excursion
     (goto-char (point-min))
     (while (re-search-forward "^[ \t]+\\([-+*]\\) " nil t)
         (decompose-region (match-beginning 1) (match-end 1)))))
 
 
-(defun org-sstar--prettify-main-hbullet ()
+(defun org-superstar--prettify-main-hbullet ()
   "Prettify the trailing star in a headline.
 
-This function uses ‘org-sstar-in-valid-context-p’ to avoid
+This function uses ‘org-superstar-headline-or-inlinetask-p’ to avoid
 prettifying bullets in (for example) source blocks."
-  (when (org-sstar-in-valid-context-p)
+  (when (org-superstar-headline-or-inlinetask-p)
     (let ((level (- (match-end 0) (match-beginning 0) 1)))
       (compose-region (match-beginning 1) (match-end 1)
-                      (org-sstar--hbullet level))))
-  'org-sstar-header-bullet)
+                      (org-superstar--hbullet level))))
+  'org-superstar-header-bullet)
 
-(defun org-sstar--prettify-other-hbullet ()
+(defun org-superstar--prettify-other-hbullet ()
   "Prettify the second last star in a headline.
 This is only done if the particular title’s level is part of an
 inline task, see ‘org-inlinetask-min-level’.  Otherwise, this
 block is formatted like the leading asterisks, see
-‘org-sstar--prettify-leading-hbullets’.
+‘org-superstar--prettify-leading-hbullets’.
 
-This function uses ‘org-sstar-in-valid-context-p’ to avoid
+This function uses ‘org-superstar-headline-or-inlinetask-p’ to avoid
 prettifying bullets in (for example) source blocks."
-  (when (org-sstar-in-valid-context-p)
+  (when (org-superstar-headline-or-inlinetask-p)
     (let* ((level (- (match-end 0) (match-beginning 0) 1))
            (is-inline-task
             (and (boundp 'org-inlinetask-min-level)
                  (>= level org-inlinetask-min-level)))
            (compose-star (or is-inline-task
                              (and (not org-hide-leading-stars)
-                                  org-sstar-prettify-leading-stars)))
+                                  org-superstar-prettify-leading-stars)))
            (bullet-char (if is-inline-task
-                            (org-sstar--hbullet level)
-                            org-sstar-leading-bullet)))
+                            (org-superstar--hbullet level)
+                            org-superstar-leading-bullet)))
       (when compose-star
         (compose-region (match-beginning 2) (match-end 2)
                         bullet-char))
-      (cond (is-inline-task 'org-sstar-header-bullet)
-            (org-sstar-prettify-leading-stars 'org-sstar-leading)
+      (cond (is-inline-task 'org-superstar-header-bullet)
+            (org-superstar-prettify-leading-stars 'org-superstar-leading)
             (t 'custom-invalid)))))
 
 
-(defun org-sstar--prettify-leading-hbullets ()
+(defun org-superstar--prettify-leading-hbullets ()
   "Prettify the leading bullets of a header line.
 Unless ‘org-hide-leading-stars’ is non-nil, each leading star is
-visually replaced by ‘org-sstar-leading-bullet-char’ and inherits
-face properties from ‘org-sstar-leading’.
+visually replaced by ‘org-superstar-leading-bullet-char’ and inherits
+face properties from ‘org-superstar-leading’.
 
-This function uses ‘org-sstar-in-valid-context-p’ to avoid
+This function uses ‘org-superstar-headline-or-inlinetask-p’ to avoid
 prettifying bullets in (for example) source blocks."
-  (when (org-sstar-in-valid-context-p)
+  (when (org-superstar-headline-or-inlinetask-p)
     (unless org-hide-leading-stars
       (let ((star-beg (match-beginning 3))
             (lead-end (match-end 3)))
         (while (< star-beg lead-end)
           (compose-region star-beg (setq star-beg (1+ star-beg))
-                          org-sstar-leading-bullet))
-        'org-sstar-leading))))
+                          org-superstar-leading-bullet))
+        'org-superstar-leading))))
 
 
 
-(defun org-sstar--unprettify-hbullets ()
-  "Revert all changes made to header bullets."
+(defun org-superstar--unprettify-hbullets ()
+  "Revert visual tweaks made to header bullets in current buffer."
   (save-excursion
     (goto-char (point-min))
     (while (re-search-forward "^\\*+ " nil t)
         (decompose-region (match-beginning 0) (match-end 0)))))
 
+
 ;;; Font Lock
 
-(defvar-local org-sstar--font-lock-keywords nil)
+(defvar-local org-superstar--font-lock-keywords nil)
 
-(defun org-sstar--update-font-lock-keywords ()
-  "Set ‘org-sstar--font-lock-keywords’ to reflect current settings.
+(defun org-superstar--update-font-lock-keywords ()
+  "Set ‘org-superstar--font-lock-keywords’ to reflect current settings.
 You should not call this function to avoid confusing the cleanup
 routines of ‘\\[org-superstar-mode]’."
   ;; The below regex is nicked from ‘org-list-full-item-re’, but
   ;; reduced to only match simple lists.  Replaced [ \t]* by [ \t]+ to
   ;; avoid confusion with title bullets.
-  (setq org-sstar--font-lock-keywords
-        `(,@(when org-sstar-prettify-item-bullets
+  (setq org-superstar--font-lock-keywords
+        `(,@(when org-superstar-prettify-item-bullets
               '(("^[ \t]+\\([-+*]\\) "
-                 (1 (org-sstar--prettify-ibullets)))))
+                 (1 (org-superstar--prettify-ibullets)))))
           ("^\\(?3:\\**?\\)\\(?2:\\*?\\)\\(?1:\\*\\) "
-           (1 (org-sstar--prettify-main-hbullet) prepend)
-           ,@(when org-sstar-prettify-leading-stars
-               '((3 (org-sstar--prettify-leading-hbullets)
+           (1 (org-superstar--prettify-main-hbullet) prepend)
+           ,@(when org-superstar-prettify-leading-stars
+               '((3 (org-superstar--prettify-leading-hbullets)
                     t)))
-           (2 (org-sstar--prettify-other-hbullet) prepend))
+           (2 (org-superstar--prettify-other-hbullet) prepend))
           ;; If requested, put another function here that formats the
           ;; first two stars of an inline as a bullet.
           )))
 
-(defun org-sstar--fontify-buffer ()
+(defun org-superstar--fontify-buffer ()
   "Fontify the buffer."
   (when font-lock-mode
     (if (and (fboundp 'font-lock-flush)
@@ -416,15 +438,15 @@ routines of ‘\\[org-superstar-mode]’."
   :require 'org
   (cond
    (org-superstar-mode
-    (org-sstar--update-font-lock-keywords)
-    (font-lock-add-keywords nil org-sstar--font-lock-keywords
+    (org-superstar--update-font-lock-keywords)
+    (font-lock-add-keywords nil org-superstar--font-lock-keywords
                             'append)
-    (org-sstar--fontify-buffer))
+    (org-superstar--fontify-buffer))
    (t
-    (font-lock-remove-keywords nil org-sstar--font-lock-keywords)
-    (org-sstar--unprettify-ibullets)
-    (org-sstar--unprettify-hbullets)
-    (org-sstar--fontify-buffer))))
+    (font-lock-remove-keywords nil org-superstar--font-lock-keywords)
+    (org-superstar--unprettify-ibullets)
+    (org-superstar--unprettify-hbullets)
+    (org-superstar--fontify-buffer))))
 
 (provide 'org-superstar)
 ;;; org-superstar.el ends here