[nongnu] elpa/org-superstar ceb3be1018 088/162: Implement circumvention for plain list syntax checking

[Stefan Kangas]

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

    Implement circumvention for plain list syntax checking
    
    While semantic prettification is a very nice concept on paper, it is a
    rather expensive feature to implement.  For this reason I have come to
    believe the user should have the option to disable it on a
    case-by-case (or rather buffer-by-buffer) basis.
---
 README.org       | 19 +++++++++++++++++++
 org-superstar.el | 37 ++++++++++++++++++++++++++++++-------
 2 files changed, 49 insertions(+), 7 deletions(-)

diff --git a/README.org b/README.org
index 204c229c32..86205da042 100644
--- a/README.org
+++ b/README.org
@@ -145,6 +145,16 @@ 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.
+**** TODO Give an elisp example for automated toggling!
+
 ** Custom faces
    These faces allow you to further manipulate the look and feel of
    prettified bullets.
@@ -178,6 +188,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-03-08=
diff --git a/org-superstar.el b/org-superstar.el
index 4ebebbafe8..3e902c7b59 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.0.2
+;; Version: 1.1.0
 ;; Homepage: https://github.com/integral-dw/org-superstar-mode
 ;; Package-Requires: ((org "9.1.9") (emacs "26.2"))
 
@@ -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."
@@ -622,7 +645,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)