Previous: , Up: Magit-Section Developer Manual   [Contents]


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.


Previous: Core Functions, Up: Magit-Section Developer Manual   [Contents]