[elpa] externals/taxy 34aa94d 23/39: Add: taxy-magit-section

[ELPA Syncer]

branch: externals/taxy
commit 34aa94df48791d74fdd41412627968d7482425ba
Author: Adam Porter <adam@alphapapa.net>
Commit: Adam Porter <adam@alphapapa.net>

    Add: taxy-magit-section
    
    This is so simple!
---
 README.org                       | 132 ++++++++++++++++++++++++---------------
 images/magit-section-numbery.png | Bin 0 -> 18985 bytes
 taxy-magit-section.el            |  84 +++++++++++++++++++++++++
 3 files changed, 165 insertions(+), 51 deletions(-)

diff --git a/README.org b/README.org
index 9c46940..2e40b12 100644
--- a/README.org
+++ b/README.org
@@ -27,6 +27,7 @@ Helpful features include:
   - [[#dynamic-taxys][Dynamic taxys]]
   - [[#reusable-taxys][Reusable taxys]]
   - [[#threading-macros][Threading macros]]
+  - [[#magit-section][Magit section]]
 - [[#changelog][Changelog]]
 - [[#development][Development]]
 :END:
@@ -65,27 +66,27 @@ Let's imagine a silly taxonomy of numbers below 100:
      ;; These sub-taxys further classify the numbers below 10 into odd
      ;; and even.  The odd taxy "consumes" numbers, while the even one
      ;; doesn't, leaving them to reappear in the parent taxy's objects.
-     (("Odd (consuming)"
+     (("Odd" "(consuming)"
        (1 3 5 7 9))
-      ("Even (non-consuming)"
+      ("Even" "(non-consuming)"
        (0 2 4 6 8))))
     (">= 10" "Numbers above 9"
      ;; Like in the "< 10" taxy, these numbers are leftovers from this
      ;; taxy's sub-taxys, three of which are non-consuming.
      (10 11 13 14 17 19 22 23 25 26 29 31 34 35 37 38 41 43 46 47 49 50 53 55 
58
          59 61 62 65 67 70 71 73 74 77 79 82 83 85 86 89 91 94 95 97 98)
-     (("Divisible by 3 (non-consuming)"
+     (("Divisible by 3" "(non-consuming)"
        (12 15 18 21 24 27 30 33 36 39 42 45 48 51 54 57 60 63 66 69 72 75 78 
81 84
            87 90 93 96 99))
-      ("Divisible by 4 (non-consuming)"
+      ("Divisible by 4" "(non-consuming)"
        (12 16 20 24 28 32 36 40 44 48 52 56 60 64 68 72 76 80 84 88 92 96))
-      ("Divisible by 3 or 4 (consuming)"
+      ("Divisible by 3 or 4" "(consuming)"
        ;; This taxy consumes numbers it takes in, but since these
        ;; numbers have already been taken in (without being consumed) by
        ;; the previous two sibling taxys, they may also appear in them.
        (12 15 16 18 20 21 24 27 28 30 32 33 36 39 40 42 44 45 48 51 52 54 56 
57 60
            63 64 66 68 69 72 75 76 78 80 81 84 87 88 90 92 93 96 99))
-      ("Divisible by 5 (non-consuming)"
+      ("Divisible by 5" "(non-consuming)"
        (10 25 35 50 55 65 70 85 95))))))
 #+END_SRC
 
@@ -94,51 +95,61 @@ You might think about how to produce that by writing some 
imperative code, but =
 #+BEGIN_SRC elisp :exports code
   (require 'taxy)
 
-  (let ((numbery
-         (make-taxy
-          :name "Numbery"
-          :description "A silly taxonomy of numbers."
-          :taxys (list (make-taxy
-                        :name "< 10"
-                        :description "Numbers below 10 (consuming)"
-                        :predicate (lambda (n) (< n 10))
-                        :taxys (list
-                                ;; These sub-taxys further classify the 
numbers below 10 into odd
-                                ;; and even.  The odd taxy "consumes" numbers, 
while the even one
-                                ;; doesn't, leaving them to reappear in the 
parent taxy's objects.
-                                (make-taxy :name "Odd (consuming)"
-                                           :predicate #'oddp)
-                                (make-taxy :name "Even (non-consuming)"
-                                           :predicate #'evenp
-                                           :then #'identity)))
-                       (make-taxy
-                        :name ">= 10"
-                        :description "Numbers above 9 (consuming)"
-                        :predicate (lambda (n) (>= n 10))
-                        :taxys (list
-                                ;; Like in the "< 10" taxy, these sub-taxys 
further classify
-                                ;; the numbers, but only one of them consumes 
numbers it
-                                ;; takes in, leaving the rest to reappear in 
the parent taxy.
-                                (make-taxy :name "Divisible by 3 
(non-consuming)"
-                                           :predicate (lambda (n) (zerop (mod 
n 3)))
-                                           :then #'identity)
-                                (make-taxy :name "Divisible by 4 
(non-consuming)"
-                                           :predicate (lambda (n) (zerop (mod 
n 4)))
-                                           :then #'identity)
-                                (make-taxy :name "Divisible by 3 or 4 
(consuming)"
-                                           ;; Since this taxy's `:then' 
function is unset,
-                                           ;; it defaults to `ignore', which 
causes it to
-                                           ;; consume numbers it takes in.  
Since these
-                                           ;; numbers have already been taken 
in (without
-                                           ;; being consumed) by the previous 
two sibling
-                                           ;; taxys, they also appear in them.
-                                           :predicate (lambda (n) (or (zerop 
(mod n 3))
-                                                                      (zerop 
(mod n 4)))))
-                                (make-taxy :name "Divisible by 5 
(non-consuming)"
-                                           :predicate (lambda (n) (zerop (mod 
n 5)))
-                                           :then #'identity))))))
-        (numbers (cl-loop for i below 100 collect i)))
-    (taxy-plain (taxy-fill (reverse numbers) numbery)))
+  (defvar numbery
+    (make-taxy
+     :name "Numbery"
+     :description "A silly taxonomy of numbers."
+     :taxys (list (make-taxy
+                   :name "< 10"
+                   :description "Numbers below 10 (consuming)"
+                   :predicate (lambda (n) (< n 10))
+                   :taxys (list
+                           ;; These sub-taxys further classify the numbers 
below 10 into odd
+                           ;; and even.  The odd taxy "consumes" numbers, 
while the even one
+                           ;; doesn't, leaving them to reappear in the parent 
taxy's objects.
+                           (make-taxy :name "Odd"
+                                      :description "(consuming)"
+                                      :predicate #'oddp)
+                           (make-taxy :name "Even"
+                                      :description "(non-consuming)"
+                                      :predicate #'evenp
+                                      :then #'identity)))
+                  (make-taxy
+                   :name ">= 10"
+                   :description "Numbers above 9 (consuming)"
+                   :predicate (lambda (n) (>= n 10))
+                   :taxys (list
+                           ;; Like in the "< 10" taxy, these sub-taxys further 
classify
+                           ;; the numbers, but only one of them consumes 
numbers it
+                           ;; takes in, leaving the rest to reappear in the 
parent taxy.
+                           (make-taxy :name "Divisible by 3"
+                                      :description "(non-consuming)"
+                                      :predicate (lambda (n) (zerop (mod n 3)))
+                                      :then #'identity)
+                           (make-taxy :name "Divisible by 4"
+                                      :description "(non-consuming)"
+                                      :predicate (lambda (n) (zerop (mod n 4)))
+                                      :then #'identity)
+                           (make-taxy :name "Divisible by 3 or 4"
+                                      :description "(consuming)"
+                                      ;; Since this taxy's `:then' function is 
unset,
+                                      ;; it defaults to `ignore', which causes 
it to
+                                      ;; consume numbers it takes in.  Since 
these
+                                      ;; numbers have already been taken in 
(without
+                                      ;; being consumed) by the previous two 
sibling
+                                      ;; taxys, they also appear in them.
+                                      :predicate (lambda (n) (or (zerop (mod n 
3))
+                                                                 (zerop (mod n 
4)))))
+                           (make-taxy :name "Divisible by 5"
+                                      :description "(non-consuming)"
+                                      :predicate (lambda (n) (zerop (mod n 5)))
+                                      :then #'identity))))))
+
+  (let ((numbers (cl-loop for i below 100 collect i))
+        ;; Since `numbery' is stored in a variable, we use an emptied
+        ;; copy of it to avoid mutating the original taxy.
+        (taxy (taxy-emptied numbery)))
+    (taxy-plain (taxy-fill (reverse numbers) taxy)))
 #+END_SRC
 
 The ~taxy-fill~ function applies the numbers in a "cascade" down the hierarchy 
of "taxys", and the ~taxy-plain~ function returns a meaningful subset of the 
taxys' slots, suitable for display.
@@ -217,6 +228,7 @@ That's better:
 - [[#dynamic-taxys][Dynamic taxys]]
 - [[#reusable-taxys][Reusable taxys]]
 - [[#threading-macros][Threading macros]]
+- [[#magit-section][Magit section]]
 :END:
 
 A taxy is defined with the ~make-taxy~ constructor, like:
@@ -396,6 +408,24 @@ If you happen to like macros, ~taxy~ works well with 
threading (i.e. ~thread-las
     taxy-plain)
 #+END_SRC
 
+** Magit section
+
+Showing a =taxy= with =magit-section= is very easy:
+
+#+BEGIN_SRC elisp
+  (require 'taxy-magit-section)
+
+  ;; Using the `numbery' taxy defined in earlier examples:
+  (thread-last numbery
+    taxy-emptied ;; Get an empty copy of the taxy, since it's defined in a 
variable.
+    (taxy-fill (reverse (cl-loop for i below 30 collect i)))
+    taxy-magit-section-pp)
+#+END_SRC
+
+That shows a buffer like this:
+
+[[images/magit-section-numbery.png]]
+
 * Changelog
 :PROPERTIES:
 :TOC:      :depth 0
diff --git a/images/magit-section-numbery.png b/images/magit-section-numbery.png
new file mode 100644
index 0000000..72255669
Binary files /dev/null and b/images/magit-section-numbery.png differ
diff --git a/taxy-magit-section.el b/taxy-magit-section.el
new file mode 100644
index 0000000..afad87c
--- /dev/null
+++ b/taxy-magit-section.el
@@ -0,0 +1,84 @@
+;;; taxy-magit-section.el ---                        -*- lexical-binding: t; 
-*-
+
+;; Copyright (C) 2021  Adam Porter
+
+;; Author: Adam Porter <adam@alphapapa.net>
+;; Keywords:
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;;
+
+;;; Code:
+
+;;;; Requirements
+
+(require 'taxy)
+(require 'magit-section)
+
+;;;; Variables
+
+
+;;;; Customization
+
+
+;;;; Commands
+
+
+;;;; Functions
+
+(cl-defun taxy-magit-section-pp (taxy &key (objects 'first))
+  "Pretty-print TAXY into a buffer with `magit-section' and show it."
+  (with-current-buffer (get-buffer-create "*taxy-magit-section-pp*")
+    (setf buffer-read-only t)
+    (use-local-map magit-section-mode-map)
+    (let ((inhibit-read-only t))
+      (erase-buffer)
+      (taxy-magit-section-insert taxy :objects objects))
+    (pop-to-buffer (current-buffer))))
+
+(cl-defun taxy-magit-section-insert (taxy &key (objects 'first))
+  "Insert a `magit-section' for TAXY into current buffer.
+If OBJECTS is `first', insert a taxy's objects before its
+descendant taxys; if `last', insert them after descendants."
+  (let ((depth 0))
+    (cl-labels ((insert-object
+                 (object) (insert (make-string (+ 2 (* depth 2)) ? )
+                                  (format "%s" object)
+                                  "\n"))
+                (insert-taxy
+                 (taxy) (magit-insert-section (magit-section taxy)
+                          (magit-insert-heading
+                            (make-string (* depth 2) ? )
+                            (propertize (taxy-name taxy) 'face 
'magit-section-heading)
+                            (when (taxy-description taxy)
+                              (concat " (" (taxy-description taxy) ")")))
+                          (magit-insert-section-body
+                            (when (eq 'first objects)
+                              (mapc #'insert-object (taxy-objects taxy)))
+                            (cl-incf depth)
+                            (mapc #'insert-taxy (taxy-taxys taxy))
+                            (cl-decf depth)
+                            (when (eq 'last objects)
+                              (mapc #'insert-object (taxy-objects taxy)))))))
+      (magit-insert-section (magit-section)
+        (insert-taxy taxy)))))
+
+;;;; Footer
+
+(provide 'taxy-magit-section)
+
+;;; taxy-magit-section.el ends here