emacs/code/elpa/magit-section-20230805.1908/magit-section.info

This is magit-section.info, produced by makeinfo version 6.7 from
magit-section.texi.

     Copyright (C) 2015-2023 Jonas Bernoulli <jonas@bernoul.li>

     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.

INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Magit-Section: (magit-section). Use Magit sections in your own packages.
END-INFO-DIR-ENTRY


File: magit-section.info,  Node: Top,  Next: Introduction,  Up: (dir)

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 *note (magit)Sections::.  This manual documents how
you can use sections in your own packages.

This manual is for Magit-Section version 3.3.0.50-git.

     Copyright (C) 2015-2023 Jonas Bernoulli <jonas@bernoul.li>

     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.

* Menu:

* Introduction::
* Creating Sections::
* Core Functions::
* Matching Functions::


File: magit-section.info,  Node: Introduction,  Next: Creating Sections,  Prev: Top,  Up: Top

1 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 *note (magit)Sections::.  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!


File: magit-section.info,  Node: Creating Sections,  Next: Core Functions,  Prev: Introduction,  Up: Top

2 Creating Sections
*******************

 -- Macro: magit-insert-section [name] (type &optional value hide) &rest
          body
     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.

 -- Function: magit-insert-heading &rest args
     Insert the heading for the section currently being inserted.

     This function should only be used inside ‘magit-insert-section’.

     When called without any arguments, then just set the ‘content’ slot
     of the object representing the section being inserted to a marker
     at ‘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 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 ‘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 ‘content’ property of the section object is the end of the
     heading (which lasts from ‘start’ to ‘content’) and the beginning
     of the the body (which lasts from ‘content’ to ‘end’).  If the
     value of ‘content’ is 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.

 -- Macro: 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
     ‘progn’.  Otherwise BODY isn’t evaluated until the section is
     explicitly expanded.

 -- Function: magit-cancel-section
     Cancel inserting the section that is currently being inserted.
     Remove all traces of that section.

 -- Function: magit-wash-sequence function
     Repeatedly call FUNCTION until it returns ‘nil’ or the end of the
     buffer is reached.  FUNCTION has to move point forward or return
     ‘nil’.


File: magit-section.info,  Node: Core Functions,  Next: Matching Functions,  Prev: Creating Sections,  Up: Top

3 Core Functions
****************

 -- Function: 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.

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

 -- Function: magit-section-ident section
     Return an unique identifier for SECTION.  The return value has the
     form ‘((TYPE . VALUE)...)’.

 -- Function: magit-section-ident-value value
     Return a constant representation of VALUE.

     VALUE is the value of a ‘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.

 -- Function: magit-get-section ident &optional root
     Return the section identified by IDENT.  IDENT has to be a list as
     returned by ‘magit-section-ident’.  If optional ROOT is non-nil,
     then search in that section tree instead of in the one whose root
     ‘magit-root-section’ is.

 -- Function: magit-section-lineage section
     Return the lineage of SECTION.  The return value has the form
     ‘(TYPE...)’.

 -- Function: magit-section-content-p section
     Return non-nil if SECTION has content or an unused washer function.

   The next two functions are replacements for the Emacs functions that
have the same name except for the ‘magit-’ prefix.  Like
‘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.

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 ‘point’.

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 ‘thing-at-point’.
     For the meaning of THING and NO-PROPERTIES see that function.


File: magit-section.info,  Node: Matching Functions,  Prev: Core Functions,  Up: Top

4 Matching Functions
********************

 -- Function: magit-section-match condition &optional (section
          (magit-current-section))
     Return 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 nil.

     CONDITION can take the following forms:

        • ‘(CONDITION...)’ matches if any of the CONDITIONs matches.
        • ‘[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.

        • ‘[* CLASS...]’ matches sections that match [CLASS...] and also
          recursively all their child sections.
        • ‘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.

     Each CLASS should be a class symbol, identifying a class that
     derives from ‘magit-section’.  For backward compatibility CLASS can
     also be a "type symbol".  A section matches such a symbol if the
     value of its ‘type’ slot is ‘eq’.  If a type symbol has an entry in
     ‘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 ‘magit-describe-section-briefly’, unless of
     course you want to be that precise.

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

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

     See ‘magit-section-match’ for the forms CONDITION can take.

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

     Each clause looks like ‘(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 ‘it’ is bound to the
     section at point.  If no clause succeeds or if there is no section
     at point, return nil.

     See ‘magit-section-match’ for the forms CONDITION can take.
     Additionally a CONDITION of t is allowed in the final clause, and
     matches if no other CONDITION match, even if there is no section at
     point.



Tag Table:
Node: Top788
Node: Introduction2076
Node: Creating Sections2846
Node: Core Functions7354
Node: Matching Functions10406

End Tag Table


Local Variables:
coding: utf-8
End: