Function: magit-insert-section

magit-insert-section is a macro defined in magit-section.el.

Signature

(magit-insert-section [NAME] (CLASS &optional VALUE HIDE) &rest BODY)

Documentation

Insert a section at point.

Create a section object of type CLASS, storing VALUE in its value slot, and insert the section at point. CLASS is a subclass of magit-section(var)/magit-section(fun) or has the form (eval FORM), in which case FORM is evaluated at runtime and should return a subclass. In other places a sections class is often referred to as its "type".

Many commands behave differently depending on the class of the current section and sections of a certain class can have their own keymap, which is specified using the keymap class slot. The value of that slot should be a variable whose value is a keymap.

For historic reasons Magit and Forge in most cases use symbols as CLASS that don't actually identify a class and that lack the appropriate package prefix. This works due to some undocumented kludges, which are not available to other packages.

When optional HIDE is non-nil collapse the section body by default, i.e., when first creating the section, but not when refreshing the buffer. Else expand it by default. This can be overwritten using magit-section-set-visibility-hook. When a section is recreated during a refresh, then the visibility of predecessor is inherited and HIDE is ignored (but the hook is still honored).

BODY is any number of forms that actually insert the section's heading and body. Optional NAME, if specified, has to be a symbol, which is then bound to the object of the section being inserted.

Before BODY is evaluated the start of the section object is set to the value of point and after BODY was evaluated its end is set to the new value of point; BODY is responsible for moving point forward.

If it turns out inside BODY that the section is empty, then magit-cancel-section can be used to abort and remove all traces of the partially inserted section. This can happen when creating a section by washing Git's output and Git didn't actually output anything this time around.

Source Code

;; Defined in ~/.emacs.d/elpa/magit-section-20260330.1102/magit-section.el
(defmacro magit-insert-section (&rest args)
  "Insert a section at point.

Create a section object of type CLASS, storing VALUE in its
`value' slot, and insert the section at point.  CLASS is a
subclass of `magit-section' or has the form `(eval FORM)', in
which case FORM is evaluated at runtime and should return a
subclass.  In other places a sections class is often referred
to as its \"type\".

Many commands behave differently depending on the class of the
current section and sections of a certain class can have their
own keymap, which is specified using the `keymap' class slot.
The value of that slot should be a variable whose value is a
keymap.

For historic reasons Magit and Forge in most cases use symbols
as CLASS that don't actually identify a class and that lack the
appropriate package prefix.  This works due to some undocumented
kludges, which are not available to other packages.

When optional HIDE is non-nil collapse the section body by
default, i.e., when first creating the section, but not when
refreshing the buffer.  Else expand it by default.  This can be
overwritten using `magit-section-set-visibility-hook'.  When a
section is recreated during a refresh, then the visibility of
predecessor is inherited and HIDE is ignored (but the hook is
still honored).

BODY is any number of forms that actually insert the section's
heading and body.  Optional NAME, if specified, has to be a
symbol, which is then bound to the object of the section being
inserted.

Before BODY is evaluated the `start' of the section object is set
to the value of `point' and after BODY was evaluated its `end' is
set to the new value of `point'; BODY is responsible for moving
`point' forward.

If it turns out inside BODY that the section is empty, then
`magit-cancel-section' can be used to abort and remove all traces
of the partially inserted section.  This can happen when creating
a section by washing Git's output and Git didn't actually output
anything this time around.

\(fn [NAME] (CLASS &optional VALUE HIDE) &rest BODY)"
  (declare (indent 1) ;sic
           (debug ([&optional symbolp]
                   (&or [("eval" form) &optional form form &rest form]
                        [symbolp &optional form form &rest form])
                   body)))
  (pcase-let* ((bind (and (symbolp (car args))
                          (pop args)))
               (`((,class ,value ,hide . ,args) . ,body) args)
               (obj (gensym "section")))
    `(let* ((,obj (magit-insert-section--create
                   ,(if (eq (car-safe class) 'eval) (cadr class) `',class)
                   ,value ,hide ,@args))
            (magit-insert-section--current ,obj)
            (magit-insert-section--oldroot
             (or magit-insert-section--oldroot
                 (and (not magit-insert-section--parent)
                      (prog1 magit-root-section
                        (setq magit-root-section ,obj)))))
            (magit-insert-section--parent ,obj))
       (catch 'cancel-section
         ,@(if bind `((let ((,bind ,obj)) ,@body)) body)
         (magit-insert-section--finish ,obj))
       ,obj)))