[nongnu] elpa/org-superstar 026c54f1bf 100/162: Version bump: Add new option allowing a more efficient (but sloppy) display of list items

[Stefan Kangas]

branch: elpa/org-superstar
commit 026c54f1bfcb39b0d6ed1f99db0bb384ec10443c
Merge: 7a33a131a2 092de74fb9
Author: D. Williams <d.williams@posteo.net>
Commit: GitHub <noreply@github.com>

    Version bump: Add new option allowing a more efficient (but sloppy) display 
of list items
    
    Add a new feature, allowing Org Superstar to remain handy for Org files 
with many list items.
    This merge also addresses #8, lowering the minimum version of Emacs a wee 
bit.
---
 README.org       | 40 ++++++++++++++++++++++++++++++++++++----
 org-superstar.el | 39 +++++++++++++++++++++++++++++++--------
 2 files changed, 67 insertions(+), 12 deletions(-)

diff --git a/README.org b/README.org
index 30bb446cb0..e3cce0a99d 100644
--- a/README.org
+++ b/README.org
@@ -46,10 +46,8 @@ used, allowing the user to inherit the level-dependent 
default look.
           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.
-   * optional display of two leading bullets for inline tasks :: This
-        feature is perfectly within the scope of this package.
-        However, I will not add it unless asked, to avoid preemptive
-        accumulation of features no one asked for.
+   * optionally display a leading bullet for inline tasks :: Please see
+        [[https://github.com/integral-dw/org-superstar-mode/issues/5][this 
issue]].
 
 * Installation
 
@@ -145,6 +143,31 @@ used, allowing the user to inherit the level-dependent 
default look.
     Exactly as it says on the tin.  Set this variable to ~nil~ to stop
     ~org-superstar-mode~ from prettifying lists.
 
+*** Fast Plain List Items
+    The default syntax-checking done to ensure only actual plain list
+    items are prettified is rather expensive, but usually not
+    expensive enough to cause significant slowdown.  This can change
+    when dealing with Org files containing hundreds or even thousands
+    of plain list items.  The command
+    =org-superstar-toggle-lightweight-lists= allows the user to disable
+    syntax checking for plain lists both interactively and in code.
+    For example, if you experience issues for files with more than 100
+    list items, you could simply add the following to ~org-mode-hook~
+    instead of a direct call to ~org-superstar-mode~:
+
+    #+BEGIN_SRC emacs-lisp
+      (defun my-auto-lightweight-mode ()
+        "Start Org Superstar differently depending on the number of lists 
items."
+        (let ((list-items
+               (count-matches "^[ \t]*?\\([+-]\\|[ \t]\\*\\)"
+                              (point-min) (point-max))))
+          (unless (< list-items 100)
+            (org-superstar-toggle-lightweight-lists)))
+        (org-superstar))
+
+      (add-hook 'org-mode-hook #'my-auto-lightweight-mode)
+    #+END_SRC
+
 ** Custom faces
    These faces allow you to further manipulate the look and feel of
    prettified bullets.
@@ -178,6 +201,15 @@ used, allowing the user to inherit the level-dependent 
default look.
    problem.  If this should not fix the problem, please consider
    opening an issue or sending me a mail!
 
+*** "I experience lag when working with long plain lists!"
+    By default, Org Superstar does expensive syntax checking to ensure
+    plain lists are actual plain lists.  This is usually not an issue
+    for small files.  However, this may pose a problem when your file
+    contains hundreds or thousands of items!  You can deal with this
+    interactively using the command
+    =org-superstar-toggle-lightweight-lists=.  See also the subsection
+    "*Fast Plain List Items*" above.
+
 * NEWS
 
 ** =2020-04-01=
diff --git a/org-superstar.el b/org-superstar.el
index 4b5fb97690..935249605b 100644
--- a/org-superstar.el
+++ b/org-superstar.el
@@ -5,9 +5,9 @@
 ;; Author: D. Williams <d.williams@posteo.net>
 ;; Maintainer: D. Williams <d.williams@posteo.net>
 ;; Keywords: faces, outlines
-;; Version: 1.0.3
+;; Version: 1.1.0
 ;; Homepage: https://github.com/integral-dw/org-superstar-mode
-;; Package-Requires: ((org "9.1.9") (emacs "26.2"))
+;; Package-Requires: ((org "9.1.9") (emacs "26.1"))
 
 ;; This file is NOT part of GNU Emacs.
 
@@ -272,6 +272,12 @@ keyword)."
   :group 'org-superstar
   :type 'boolean)
 
+(defvar-local org-superstar-lightweight-lists nil
+  "Non-nil means circumvent expensive calls to ‘org-superstar-plain-list-p’.
+
+There is usually no need to use this variable directly; instead,
+use the command ‘org-superstar-toggle-lightweight-lists’.")
+
 
 ;;; Faces
 
@@ -348,6 +354,18 @@ variable for your changes to take effect."
   (setq org-superstar-special-todo-items nil)
   nil)
 
+;;;###autoload
+(defun org-superstar-toggle-lightweight-lists ()
+  "Toggle syntax checking for plain list items.
+
+Disabling syntax checking will cause Org Superstar to display
+lines looking like plain lists (for example in code) like plain
+lists.  However, this may cause significant speedup for org files
+containing several hundred list items."
+  (interactive)
+  (setq org-superstar-lightweight-lists
+        (not org-superstar-lightweight-lists)))
+
 
 ;;; Accessor Functions
 
@@ -425,11 +443,16 @@ replaced by their corresponding entry in 
‘org-superstar-item-bullet-alist’."
 ;; Explicitly returning t is redundant, but does not leak information
 ;; about how the predicate is implemented.
 (defun org-superstar-plain-list-p ()
-  "Return t if the current match is a proper plain list."
-  (save-match-data
-    (when (org-element-lineage (org-element-at-point)
-                               '(plain-list) t)
-      t)))
+  "Return t if the current match is a proper plain list.
+
+This function may be expensive for files with very large plain
+lists; consider using ‘org-superstar-toggle-lightweight-lists’ in
+such cases to avoid slowdown."
+  (or org-superstar-lightweight-lists
+      (save-match-data
+        (org-element-lineage (org-element-at-point)
+                             '(plain-list) t))
+      t))
 
 (defun org-superstar-headline-or-inlinetask-p ()
   "Return t if the current match is a proper headline or inlinetask."
@@ -623,7 +646,7 @@ cleanup routines."
     (org-superstar--fontify-buffer))))
 
 (defun org-superstar-restart ()
-  "Re-enable ‘org-superstar-mode’, if the mode is enabled."
+  "Re-enable Org Superstar mode, if the mode is enabled."
   (interactive)
   (when org-superstar-mode
     (org-superstar-mode 0)