[nongnu] elpa/org-superstar 930a887430 111/162: Add support for extra-wide headline bullets + terminal fallback.

[Stefan Kangas]

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

    Add support for extra-wide headline bullets + terminal fallback.
    
    Untested changes addressing Issue #9 and a few typo fixes.
---
 README.org       | 48 ++++++++++++++++++++++---------
 org-superstar.el | 86 ++++++++++++++++++++++++++++++++++++++++++++------------
 2 files changed, 102 insertions(+), 32 deletions(-)

diff --git a/README.org b/README.org
index 30cfe3559d..31974b3342 100644
--- a/README.org
+++ b/README.org
@@ -45,7 +45,7 @@ used, allowing the user to inherit the level-dependent 
default look.
           I have realized that this feature exceeds the scope of the
           package, being too interactive.  This would require a lot of
           font-lock related boilerplate which I am currently
-          in the process of dedicating it's own package to.
+          in the process of dedicating its own package to.
    * optionally display a leading bullet for inline tasks :: Please see
         [[https://github.com/integral-dw/org-superstar-mode/issues/5][this 
issue]].
 
@@ -69,7 +69,7 @@ used, allowing the user to inherit the level-dependent 
default look.
   documentation.
 
 ** "Can you make it more like =org-bullets=?"
-   Naturally!  In fact, I made the answer to this it's own function:
+   Naturally!  In fact, I made the answer to this its own function:
 
 *** ~org-superstar-configure-like-org-bullets~
     This function configures ~superstar-mode~ to be as similar to
@@ -90,7 +90,13 @@ used, allowing the user to inherit the level-dependent 
default look.
     list: It's a list of single-character strings where the /Nth/ entry
     is used to determine the bullet used for heading level /N/.  By
     default, this list is cycled through for /N/ greater than the length
-    of the list.
+    of the list.  Strings are not the only valid way to provide
+    headline bullets, however.  Since version *1.3.0*, this variable
+    also recognizes characters as well as specific lists, with
+    characters being the new default way of providing bullets.  Lists
+    on the other hand provide the user with the means to access
+    advanced composition features and fallback options for terminal
+    users.
 
 *** ~org-superstar-cycle-headline-bullets~
     This variable gives you more control over how ~superstar-mode~ picks
@@ -115,7 +121,7 @@ used, allowing the user to inherit the level-dependent 
default look.
 
 *** Hide leading stars
     Since ~org-mode~ already takes care of hiding leading stars by
-    providing the dedicated variable ~org-hide-leading-stars~ and it's
+    providing the dedicated variable ~org-hide-leading-stars~ and its
     associated face ~org-hide~, there is no extra option for /hiding/
     leading stars like that.  Instead, ~org-hide-leading-stars~
     implicitly disables further fontification.
@@ -232,17 +238,18 @@ used, allowing the user to inherit the level-dependent 
default look.
 
 * NEWS
 
-** =2020-04-14=
-   Version *1.2.0* is now available.  This version adds support for
-   using advanced features of ~compose-region~ for TODO item bullets.
-
-   Also, the package's downloads doubled in less than two weeks,
-   meaning Org Superstar now has [[https://melpa.org/#/org-superstar][over 
1000 downloads on MELPA]]!  I have
-   given the whole situation some more thought, and decided that I
-   will contact the Spacemacs team should we reach 2000 downloads this
-   year, which I would consider enough proof of the package's
-   popularity.
+** =2020-08-08=
+   Version *1.3.0* is about to go live.  This version adds support for
+   using advanced features of ~compose-region~ for headline bullets,
+   thus continuing efforts to make the package more visually coherent
+   for general setups while remaining terminal friendly.
 
+   In other news, Org Superstar reached 
[[https://melpa.org/#/org-superstar][over 16000 downloads on MELPA]]!
+   This is absolutely insane, and already surpasses my hopes for this
+   year by more than a factor of 8!  I am speechless.  And, as
+   promised, I will contact the Spacemacs team sometimes this year.
+   However, updates may be slow, given current circumstances.  My
+   apologies.
 
 * Announcement Log
 ** =2020-02-02=
@@ -301,4 +308,17 @@ used, allowing the user to inherit the level-dependent 
default look.
    minor fixes, as well as a new feature to disable expensive syntax
    checks for plain list items. See the FAQ for more info.
 
+** =2020-04-14=
+   Version *1.2.0* is now available.  This version adds support for
+   using advanced features of ~compose-region~ for TODO item bullets.
+
+   Also, the package's downloads doubled in less than two weeks,
+   meaning Org Superstar now has [[https://melpa.org/#/org-superstar][over 
1000 downloads on MELPA]]!  I have
+   given the whole situation some more thought, and decided that I
+   will contact the Spacemacs team should we reach 2000 downloads this
+   year, which I would consider enough proof of the package's
+   popularity.
+
+
 #  LocalWords:  Org's MELPA ELPA Worg fontification TODO README UTF Spacemacs
+#  LocalWords:  Org fallback setups
diff --git a/org-superstar.el b/org-superstar.el
index 178bdefd07..3c9ae3fbf5 100644
--- a/org-superstar.el
+++ b/org-superstar.el
@@ -5,7 +5,7 @@
 ;; Author: D. Williams <d.williams@posteo.net>
 ;; Maintainer: D. Williams <d.williams@posteo.net>
 ;; Keywords: faces, outlines
-;; Version: 1.2.1
+;; Version: 1.2.2
 ;; Homepage: https://github.com/integral-dw/org-superstar-mode
 ;; Package-Requires: ((org "9.1.9") (emacs "26.1"))
 
@@ -86,20 +86,44 @@
 
 (defcustom org-superstar-headline-bullets-list
   '(;; Original ones nicked from org-bullets
-    "◉"
-    "○"
-    "✸"
-    "✿") ;; "◉" "🞛" "○" "▷"
+    ?◉
+    ?○
+    ?✸
+    ?✿) ;; My default: ?◉ ?🞛 ?○ ?▷
   "List of bullets used in Org headings.
 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-superstar-cycle-headline-bullets’.
 
+Every entry in this list can either be a string, a character, or
+a cons cell.  Characters and strings are used as simple, verbatim
+replacements of the asterisk for every display (be it graphical
+or terminal).  In the case of strings, everything past the first
+character is ignored.  If the list element is a cons cell, it
+should be a proper list of the form
+\(COMPOSE-STRING CHARACTER [REST...])
+
+where COMPOSE-STRING should be a string according to the rules of
+the third argument of ‘compose-region’.  It will be used to
+compose the specific headline bullet.  CHARACTER is the fallback
+character used in terminal displays, where composing characters
+cannot be relied upon.
+
 You should call ‘org-superstar-restart’ after changing this
 variable for your changes to take effect."
   :group 'org-superstar
-  :type '(repeat (string :tag "Bullet character")))
+  :type '(repeat (choice
+                  (character :value ?◉
+                             :format "Bullet character: %v\n"
+                             :tag "Simple bullet character")
+                  (string :value "◉"
+                          :tag "Bullet character")
+                  (list :tag "Advanced string and fallback"
+                        (string :value "◉"
+                                :format "String of characters to compose: %v")
+                        (character :value ?◉
+                                   :format "Fallback character for terminal: 
%v\n")))))
 
 (defcustom org-superstar-item-bullet-alist
   '((?* . ?•)
@@ -426,27 +450,54 @@ the current keyword, return nil."
 
 If the headline is also a TODO item, you can override the usually
 displayed bullet depending on the TODO keyword by setting
-‘org-superstar-special-todo-items’ to t and adding relevant
-TODO keyword entries to ‘org-superstar-todo-bullet-alist’.
+‘org-superstar-special-todo-items’ to t and adding relevant TODO
+keyword entries to ‘org-superstar-todo-bullet-alist’.
+
+For more information on how to customize headline bullets, see
+‘org-superstar-headline-bullets-list’.
 
 See also ‘org-superstar-cycle-headline-bullets’."
+  ;; string-to-char no longer makes sense here.
+  ;; If you want to support strings properly, return the string.
+  ;; However, allowing for fallback means the list may contain
+  ;; strings, chars or conses.  The cons must be resolved.
+  ;; Hence, a new funtion is needed to keep the complexity to a minimum.
   (let ((max-bullets org-superstar-cycle-headline-bullets)
         (n (if org-odd-levels-only (/ (1- level) 2) (1- level)))
         (todo-bullet (when org-superstar-special-todo-items
                        (org-superstar--todo-bullet))))
     (cond (todo-bullet)
           ((integerp max-bullets)
-           (string-to-char
-            (elt org-superstar-headline-bullets-list
-                 (% n max-bullets))))
+           (org-superstar--nth-headline-bullet (% n max-bullets)))
           (max-bullets
-           (string-to-char
-            (elt org-superstar-headline-bullets-list
-                 (% n (org-superstar--hbullets-length)))))
+           (org-superstar--nth-headline-bullet
+            (% n (org-superstar--hbullets-length))))
           (t
-           (string-to-char
-            (elt org-superstar-headline-bullets-list
-                 (min n (1- (org-superstar--hbullets-length)))))))))
+           (org-superstar--nth-headline-bullet
+            (min n (1- (org-superstar--hbullets-length))))))))
+
+(defun org-superstar--nth-headline-bullet (n)
+  "Return the Nth specified headline bullet or its corresponding fallback.
+N counts from zero.  Headline bullets are specified in
+‘org-superstar-headline-bullets-list’."
+  (let ((bullet-entry
+         (elt org-superstar-headline-bullets-list n)))
+    (cond
+     ;; Using characters for bullets is actually way more consistent
+     ;; with the rest of the package, so why not just support it.
+     ((characterp bullet-entry)
+      bullet-entry)
+     ;; Strip bullets provided as strings down to their first char.
+     ;; The main reason hbullets can be defined using strings is
+     ;; because org-bullets did it.
+     ((stringp bullet-entry)
+      (string-to-char bullet-entry))
+     ;; If the element is a cons, assume the user knows what they are
+     ;; doing.
+     ((org-superstar-graphic-p)
+      (elt bullet-entry 0))
+     (t
+      (elt bullet-entry 1)))))
 
 (defun org-superstar--ibullet (bullet-string)
   "Return BULLET-STRINGs desired UTF-8 replacement.
@@ -492,7 +543,6 @@ such cases to avoid slowdown."
 
 (defun org-superstar-headline-p ()
   "Return t if the current match is a proper headline."
-  (interactive)
   (save-match-data
     (org-with-limited-levels
      (and (org-at-heading-p) t))))