\input texinfo    @c -*- texinfo -*-
@c %**start of header
@setfilename magit-section.info
@settitle Magit-Section Developer Manual
@documentencoding UTF-8
@documentlanguage en
@c %**end of header

@copying
@quotation
Copyright (C) 2015-2026 Jonas Bernoulli <emacs.magit@@jonas.bernoulli.dev>

You can redistribute this document 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 document 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.

@end quotation
@end copying

@dircategory Emacs
@direntry
* Magit-Section: (magit-section). Use Magit sections in your own packages.
@end direntry

@finalout
@titlepage
@title Magit-Section Developer Manual
@subtitle for version 4.5.0
@author Jonas Bernoulli
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Magit-Section Developer Manual

This package implements the main user interface of Magit — the
collapsible sections that make up its buffers.  This package used
to be distributed as part of Magit but how it can also be used by
other packages that have nothing to do with Magit or Git.

To learn more about the section abstraction and available commands and
user options see @ref{Sections,,,magit,}.  This manual documents how you
can use sections in your own packages.

@noindent
This manual is for Magit-Section version 4.5.0.

@insertcopying
@end ifnottex

@menu
* Introduction::
* Creating Sections::
* Core Functions::
* Matching Functions::
@end menu

@node Introduction
@chapter Introduction

This package implements the main user interface of Magit — the
collapsible sections that make up its buffers.  This package used
to be distributed as part of Magit but how it can also be used by
other packages that have nothing to do with Magit or Git.

To learn more about the section abstraction and available commands
and user options see @ref{Sections,,,magit,}.  This manual documents
how you can use sections in your own packages.

When the documentation leaves something unaddressed, then please
consider that Magit uses this library extensively and search its
source for suitable examples before asking me for help.  Thanks!

@node Creating Sections
@chapter Creating Sections

@defmac magit-insert-section [name] (type &optional value hide) &rest body
Create a section object of type CLASS, storing VALUE in its
@code{value} slot, and insert the section at point.  CLASS is a
subclass of `magit-section' or has the form @code{(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-@code{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 @code{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 @code{start} of the section object is set
to the value of `point' and after BODY was evaluated its @code{end} is
set to the new value of @code{point}; BODY is responsible for moving
@code{point} forward.

If it turns out inside BODY that the section is empty, then
@code{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.
@end defmac

@defun magit-insert-heading [child-count] &rest args
Insert the heading for the section currently being inserted.

This function should only be used inside @code{magit-insert-section}.

When called without any arguments, then just set the @code{content}
slot of the object representing the section being inserted to
a marker at @code{point}.  The section should only contain a single
line when this function is used like this.

When called with arguments ARGS, which have to be strings, or
@code{nil}, then insert those strings at point.  The section should not
contain any text before this happens and afterwards it should
again only contain a single line.  If the @code{face} property is set
anywhere inside any of these strings, then insert all of them
unchanged.  Otherwise use the `magit-section-heading' face for
all inserted text.

The @code{content} property of the section object is the end of the
heading (which lasts from @code{start} to @code{content}) and the beginning
of the the body (which lasts from @code{content} to @code{end}).  If the
value of @code{content} is @code{nil}, then the section has no heading and
its body cannot be collapsed.  If a section does have a heading,
then its height must be exactly one line, including a trailing
newline character.  This isn't enforced, you are responsible for
getting it right.  The only exception is that this function does
insert a newline character if necessary.

If provided, optional CHILD-COUNT must evaluate to an integer or
boolean.  If @code{t}, then the count is determined once the children have been
inserted, using @code{magit-insert-child-count} (which see).  For historic
reasons, if the heading ends with ":", the count is substituted for
that, at this time as well.  If @code{magit-section-show-child-count} is @code{nil},
no counts are inserted
@end defun

@defmac magit-insert-section-body &rest body
Use BODY to insert the section body, once the section is expanded.
If the section is expanded when it is created, then this is
like @code{progn}.  Otherwise BODY isn't evaluated until the section
is explicitly expanded.
@end defmac

@defun magit-cancel-section
Cancel inserting the section that is currently being inserted.
Remove all traces of that section.
@end defun

@defun magit-wash-sequence function
Repeatedly call FUNCTION until it returns @code{nil} or the end of the
buffer is reached.  FUNCTION has to move point forward or return
@code{nil}.
@end defun

@node Core Functions
@chapter Core Functions

@defun magit-current-section
Return the section at point or where the context menu was invoked.
When using the context menu, return the section that the user
clicked on, provided the current buffer is the buffer in which
the click occurred.  Otherwise return the section at point.
@end defun

@table @asis
@item Function magit-section-at &optional position
Return the section at POSITION, defaulting to point.  Default to
point even when the context menu is used.
@end table

@defun magit-section-ident section
Return an unique identifier for SECTION@. The return value has the
form @code{((TYPE . VALUE)...)}.
@end defun

@defun magit-section-ident-value value
Return a constant representation of VALUE@.

VALUE is the value of a @code{magit-section} object.  If that is an
object itself, then that is not suitable to be used to identify
the section because two objects may represent the same thing but
not be equal.  If possible a method should be added for such
objects, which returns a value that is equal.  Otherwise the
catch-all method is used, which just returns the argument
itself.
@end defun

@defun magit-get-section ident &optional root
Return the section identified by IDENT@.
IDENT has to be a list as returned by @code{magit-section-ident}.
If optional ROOT is non-@code{nil}, then search in that section tree
instead of in the one whose root @code{magit-root-section} is.
@end defun

@defun magit-section-lineage section &optional raw
Return the lineage of SECTION@.
If optional RAW is non-@code{nil}, return a list of section objects,
beginning with SECTION, otherwise return a list of section types.
@end defun

@defun magit-section-content-p section
Return non-@code{nil} if SECTION has content or an unused washer function.
@end defun

The next two functions are replacements for the Emacs functions that
have the same name except for the @code{magit-} prefix.  Like
@code{magit-current-section} they do not act on point, the cursors position,
but on the position where the user clicked to invoke the context menu.

If your package provides a context menu and some of its commands act
on the "thing at point", even if just as a default, then use the
prefixed functions to teach them to instead use the click location
when appropriate.

@table @asis
@item Function magit-point
Return point or the position where the context menu was invoked.
When using the context menu, return the position the user clicked
on, provided the current buffer is the buffer in which the click
occurred.  Otherwise return the same value as @code{point}.

@item Function magit-thing-at-point thing &optional no-properties
Return the THING at point or where the context menu was invoked.
When using the context menu, return the thing the user clicked
on, provided the current buffer is the buffer in which the click
occurred.  Otherwise return the same value as @code{thing-at-point}.
For the meaning of THING and NO-PROPERTIES see that function.
@end table

@node Matching Functions
@chapter Matching Functions

@defun magit-section-match condition &optional (section (magit-current-section))
Return @code{t} if SECTION matches CONDITION@.

SECTION defaults to the section at point.  If SECTION is not
specified and there also is no section at point, then return
@code{nil}.

CONDITION can take the following forms:

@itemize
@item
@code{(CONDITION...)} matches if any of the CONDITIONs matches.
@item
@code{[CLASS...]} matches if the section's class is the same
as the first CLASS or a subclass of that;
the section's parent class matches the
second CLASS; and so on.

@item
@code{[* CLASS...]} matches sections that match [CLASS@dots{}] and
also recursively all their child sections.
@item
@code{CLASS} matches if the section's class is the same
as CLASS or a subclass of that; regardless
of the classes of the parent sections.
@end itemize

Each CLASS should be a class symbol, identifying a class that
derives from @code{magit-section}.  For backward compatibility CLASS
can also be a "type symbol".  A section matches such a symbol
if the value of its @code{type} slot is @code{eq}.  If a type symbol has
an entry in @code{magit--section-type-alist}, then a section also
matches that type if its class is a subclass of the class that
corresponds to the type as per that alist.

Note that it is not necessary to specify the complete section
lineage as printed by @code{magit-describe-section-briefly}, unless
of course you want to be that precise.
@end defun

@defun magit-section-value-if condition &optional section
If the section at point matches CONDITION, then return its value.

If optional SECTION is non-@code{nil} then test whether that matches
instead.  If there is no section at point and SECTION is @code{nil},
then return @code{nil}.  If the section does not match, then return
@code{nil}.

See @code{magit-section-match} for the forms CONDITION can take.
@end defun

@defmac magit-section-case &rest clauses
Choose among clauses on the type of the section at point.

Each clause looks like @code{(CONDITION BODY...)}.  The type of the
section is compared against each CONDITION; the BODY forms of the
first match are evaluated sequentially and the value of the last
form is returned.  Inside BODY the symbol @code{it} is bound to the
section at point.  If no clause succeeds or if there is no
section at point, return @code{nil}.

See @code{magit-section-match} for the forms CONDITION can take.
Additionally a CONDITION of @code{t} is allowed in the final clause, and
matches if no other CONDITION match, even if there is no section
at point.
@end defmac

@bye