---
magit.el | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 105 insertions(+), 2 deletions(-)
diff --git a/magit.el b/magit.el
index 7632448..3576f5b 100644
--- a/magit.el
+++ b/magit.el
@@ -579,7 +579,8 @@ Many Magit faces inherit from this one by default."
parent title beginning end children hidden type info
needs-refresh-on-show)
-(defvar magit-top-section nil)
+(defvar magit-top-section nil
+ "The top section of the current buffer.")
(make-variable-buffer-local 'magit-top-section)
(put 'magit-top-section 'permanent-local t)
@@ -588,6 +589,12 @@ Many Magit faces inherit from this one by default."
(defvar magit-section-hidden-default nil)
(defun magit-new-section (title type)
+ "Create a new section with title TITLE and type TYPE in current buffer.
+
+If not `magit-top-section' exist, the new section will be the new top-section
+otherwise, the new-section will be a child of the current top-section.
+
+If TYPE is nil, the section won't be highlighted."
(let* ((s (make-magit-section :parent magit-top-section
:title title
:type type
@@ -603,6 +610,7 @@ Many Magit faces inherit from this one by default."
s))
(defun magit-cancel-section (section)
+ "Delete the section SECTION."
(delete-region (magit-section-beginning section)
(magit-section-end section))
(let ((parent (magit-section-parent section)))
@@ -612,6 +620,12 @@ Many Magit faces inherit from this one by default."
(setq magit-top-section nil))))
(defmacro magit-with-section (title type &rest body)
+ "Create a new section of title TITLE and type TYPE and evaluate BODY there.
+
+Sections create into BODY will be child of the new section.
+BODY must leave point at the end of the created section.
+
+If TYPE is nil, the section won't be highlighted."
(declare (indent 2))
(let ((s (gensym)))
`(let* ((,s (magit-new-section ,title ,type))
@@ -632,6 +646,7 @@ Many Magit faces inherit from this one by default."
flag))
(defmacro magit-create-buffer-sections (&rest body)
+ "Empty current buffer of text and magit's section, and then evaluate BODY."
(declare (indent 0))
`(let ((inhibit-read-only t))
(erase-buffer)
@@ -646,6 +661,7 @@ Many Magit faces inherit from this one by default."
(magit-section-hidden magit-top-section)))))
(defun magit-propertize-section (section)
+ "Add text-property needed for SECTION."
(put-text-property (magit-section-beginning section)
(magit-section-end section)
'magit-section section)
@@ -653,6 +669,7 @@ Many Magit faces inherit from this one by default."
(magit-propertize-section s)))
(defun magit-find-section (path top)
+ "Find in subsection of section TOP the section at the path PATH."
(if (null path)
top
(let ((sec (find-if (lambda (s) (equal (car path)
@@ -663,12 +680,16 @@ Many Magit faces inherit from this one by default."
nil))))
(defun magit-section-path (section)
+ "Return the path of SECTION."
(if (not (magit-section-parent section))
'()
(append (magit-section-path (magit-section-parent section))
(list (magit-section-title section)))))
+;; Dead code:
(defun magit-find-section-at (pos secs)
+ "Return the section at POS in SECS."
+ ;; Could use the text-property
(while (and secs
(not (and (<= (magit-section-beginning (car secs)) pos)
(< pos (magit-section-end (car secs))))))
@@ -679,12 +700,14 @@ Many Magit faces inherit from this one by default."
nil))
(defun magit-find-section-after (pos secs)
+ "Find the first section in the list SECS that begin after POS."
(while (and secs
(not (> (magit-section-beginning (car secs)) pos)))
(setq secs (cdr secs)))
(car secs))
(defun magit-find-section-before (pos secs)
+ "Find the last section in the list SECS that begin before POS."
(let ((prev nil))
(while (and secs
(not (> (magit-section-beginning (car secs)) pos)))
@@ -693,11 +716,26 @@ Many Magit faces inherit from this one by default."
prev))
(defun magit-current-section ()
+ "Return the magit section at point."
(or (get-text-property (point) 'magit-section)
magit-top-section))
(defun magit-insert-section (section-title-and-type
buffer-title washer cmd &rest args)
+ "Run CMD and put its result in a new section.
+
+SECTION-TITLE-AND-TYPE is either a string that is the title of the section
+or (TITLE . TYPE) where TITLE is the title of the section and TYPE is its type.
+
+If there is no type, or if type is nil, the section won't be highlighted.
+
+BUFFER-TITLE is the inserted title of the section
+
+WASHER is a function that will be run after CMD.
+The buffer will be narrowed to the inserted text.
+It should add sectioning as needed for magit interaction
+
+CMD is an external command that will be run with ARGS as arguments"
(let* ((body-beg nil)
(section-title (if (consp section-title-and-type)
(car section-title-and-type)
@@ -727,6 +765,9 @@ Many Magit faces inherit from this one by default."
(defun magit-git-section (section-title-and-type
buffer-title washer &rest args)
+ "Run git and put its result in a new section.
+
+see `magit-insert-section' for meaning of the arguments"
(apply #'magit-insert-section
section-title-and-type
buffer-title
@@ -735,6 +776,7 @@ Many Magit faces inherit from this one by default."
(append magit-git-standard-options args)))
(defun magit-next-section (section)
+ "Return the section that is after SECTION."
(let ((parent (magit-section-parent section)))
(if parent
(let ((next (cadr (memq section
@@ -743,6 +785,7 @@ Many Magit faces inherit from this one by default."
(magit-next-section parent))))))
(defun magit-goto-next-section ()
+ "Go to the next magit section."
(interactive)
(let* ((section (magit-current-section))
(next (or (and (not (magit-section-hidden section))
@@ -767,6 +810,7 @@ Many Magit faces inherit from this one by default."
(message "No next section"))))
(defun magit-prev-section (section)
+ "Return the section that is before SECTION."
(let ((parent (magit-section-parent section)))
(if parent
(let ((prev (cadr (memq section
@@ -780,6 +824,7 @@ Many Magit faces inherit from this one by default."
parent))))))
(defun magit-goto-previous-section ()
+ "Goto the previous magit section."
(interactive)
(let ((section (magit-current-section)))
(cond ((= (point) (magit-section-beginning section))
@@ -799,18 +844,23 @@ Many Magit faces inherit from this one by default."
(goto-char (magit-section-beginning (or prev section))))))))
(defun magit-goto-parent-section ()
+ "Goto the parent section."
(interactive)
(let ((parent (magit-section-parent (magit-current-section))))
(when parent
(goto-char (magit-section-beginning parent)))))
(defun magit-goto-section (path)
+ "Goto the section describe by PATH."
(let ((sec (magit-find-section path magit-top-section)))
(if sec
(goto-char (magit-section-beginning sec))
(message "No such section"))))
(defun magit-for-all-sections (func &optional top)
+ "Run FUNC on TOP and recursively on all its children.
+
+Default value for TOP is `magit-top-section'"
(let ((section (or top magit-top-section)))
(when section
(funcall func section)
@@ -818,6 +868,7 @@ Many Magit faces inherit from this one by default."
(magit-for-all-sections func c)))))
(defun magit-section-set-hidden (section hidden)
+ "Hide SECTION if HIDDEN is not nil, show it otherwise."
(setf (magit-section-hidden section) hidden)
(if (and (not hidden)
(magit-section-needs-refresh-on-show section))
@@ -834,29 +885,38 @@ Many Magit faces inherit from this one by default."
(magit-section-set-hidden c (magit-section-hidden c))))))
(defun magit-section-any-hidden (section)
+ "Return true if SECTION or any of its children is hidden."
(or (magit-section-hidden section)
(some #'magit-section-any-hidden (magit-section-children section))))
(defun magit-section-collapse (section)
+ "Show SECTION and hide all its children."
(dolist (c (magit-section-children section))
(setf (magit-section-hidden c) t))
(magit-section-set-hidden section nil))
(defun magit-section-expand (section)
+ "Show SECTION and all its children."
(dolist (c (magit-section-children section))
(setf (magit-section-hidden c) nil))
(magit-section-set-hidden section nil))
(defun magit-section-expand-all-aux (section)
+ "Show recursively all SECTION's children."
(dolist (c (magit-section-children section))
(setf (magit-section-hidden c) nil)
(magit-section-expand-all-aux c)))
(defun magit-section-expand-all (section)
+ "Show SECTION and all its children."
(magit-section-expand-all-aux section)
(magit-section-set-hidden section nil))
(defun magit-section-hideshow (flag-or-func)
+ "Show or hide current section depending on FLAG-OR-FUNC.
+
+If FLAG-OR-FUNC is a function, it will be ran on current section
+IF FLAG-OR-FUNC is a Boolean value, the section will be hidden if its true,
shown otherwise"
(let ((section (magit-current-section)))
(when (magit-section-parent section)
(goto-char (magit-section-beginning section))
@@ -870,14 +930,17 @@ Many Magit faces inherit from this one by default."
(magit-section-hideshow nil))
(defun magit-hide-section ()
+ "Hide current section."
(interactive)
(magit-section-hideshow t))
(defun magit-collapse-section ()
+ "Hide all subsection of current section."
(interactive)
(magit-section-hideshow #'magit-section-collapse))
(defun magit-expand-section ()
+ "Show all subsection of current section."
(interactive)
(magit-section-hideshow #'magit-section-expand))
@@ -889,12 +952,14 @@ Many Magit faces inherit from this one by default."
(magit-toggle-section))
(defun magit-toggle-section ()
+ "Toggle hidden status of current section."
(interactive)
(magit-section-hideshow
(lambda (s)
(magit-section-set-hidden s (not (magit-section-hidden s))))))
(defun magit-expand-collapse-section ()
+ "Toggle hidden status of subsections of current section."
(interactive)
(magit-section-hideshow
(lambda (s)
@@ -904,6 +969,11 @@ Many Magit faces inherit from this one by default."
(magit-section-collapse s))))))
(defun magit-cycle-section ()
+ "Cycle between expanded, hidden and collapsed state for current section.
+
+Hidden: only the first line of the section is shown
+Collapsed: only the first line of the subsection is shown
+Expanded: everything is shown."
(interactive)
(magit-section-hideshow
(lambda (s)
@@ -915,7 +985,9 @@ Many Magit faces inherit from this one by default."
(magit-section-expand s))))))
(defun magit-section-lineage (s)
- (and s (cons s (magit-section-lineage (magit-section-parent s)))))
+ "Return list of parent, grand-parents... for section S."
+ (when s
+ (cons s (magit-section-lineage (magit-section-parent s)))))
(defun magit-section-show-level (section level threshold path)
(magit-section-set-hidden section (>= level threshold))
@@ -926,6 +998,9 @@ Many Magit faces inherit from this one by default."
(magit-section-show-level c (1+ level) threshold nil)))))
(defun magit-show-level (level all)
+ "Show section whose level is less than LEVEL, hide the others.
+If ALL is non nil, do this in all sections,
+otherwise do it only on ancestors and descendants of current section."
(magit-with-refresh
(if all
(magit-section-show-level magit-top-section 0 level nil)
@@ -933,18 +1008,28 @@ Many Magit faces inherit from this one by default."
(magit-section-show-level (car path) 0 level (cdr path))))))
(defun magit-show-only-files ()
+ "Show section that are files, but not there subsection.
+
+Do this in on ancestors and descendants of current section."
(interactive)
(if (eq magit-submode 'status)
(call-interactively 'magit-show-level-2)
(call-interactively 'magit-show-level-1)))
(defun magit-show-only-files-all ()
+ "Show section that are files, but not there subsection.
+
+Do this for all sections"
(interactive)
(if (eq magit-submode 'status)
(call-interactively 'magit-show-level-2-all)
(call-interactively 'magit-show-level-1-all)))
(defmacro magit-define-level-shower-1 (level all)
+ "Define an interactive function to show function of level LEVEL.
+
+If ALL is non nil, this function will affect all section,
+otherwise it will affect only ancestors and descendants of current section."
(let ((fun (intern (format "magit-show-level-%s%s"
level (if all "-all" ""))))
(doc (format "Show sections on level %s." level)))
@@ -954,11 +1039,16 @@ Many Magit faces inherit from this one by default."
(magit-show-level ,level ,all))))
(defmacro magit-define-level-shower (level)
+ "Define two interactive function to show function of level LEVEL.
+one for all, one for current lineage."
`(progn
(magit-define-level-shower-1 ,level nil)
(magit-define-level-shower-1 ,level t)))
(defmacro magit-define-section-jumper (sym title)
+ "Define an interactive function to go to section SYM.
+
+TITLE is the displayed title of the section."
(let ((fun (intern (format "magit-jump-to-%s" sym)))
(doc (format "Jump to section `%s'." title)))
`(defun ,fun ()
@@ -971,6 +1061,7 @@ Many Magit faces inherit from this one by default."
(defvar magit-highlighted-section nil)
(defun magit-highlight-section ()
+ "Highlight current section if it have a type."
(let ((section (magit-current-section)))
(when (not (eq section magit-highlighted-section))
(setq magit-highlighted-section section)
@@ -1008,6 +1099,15 @@ Many Magit faces inherit from this one by default."
(magit-prefix-p (cdr prefix) (cdr list))))))
(defmacro magit-section-case (head &rest clauses)
+ "Make different action depending of current section.
+
+HEAD is (SECTION INFO &optional OPNAME),
+ SECTION will be bind to the current section,
+ INFO will be bind to the info's of the current section,
+ OPNAME is a string that will be used to describe current action,
+
+CLAUSES is a list of CLAUSE, each clause is (SECTION-TYPE &BODY)
+where SECTION-TYPE describe section where BODY will be run."
(declare (indent 1))
(let ((section (car head))
(info (cadr head))
@@ -1041,6 +1141,9 @@ Many Magit faces inherit from this one by default."
(magit-section-case ,head ,@clauses)))
(defun magit-wash-sequence (func)
+ "Run FUNC until end of buffer is reached.
+
+FUNC should leave point at the end of the modified region"
(while (and (not (eobp))
(funcall func))))
--
Rémi Vanicat
To unsubscribe from this group, send email to magit+unsubscribegooglegroups.com
or reply to this email with the words "REMOVE ME" as the subject.
