| 1 | This is magit-section.info, produced by makeinfo version 7.1.1 from |
| 2 | magit-section.texi. |
| 3 | |
| 4 | Copyright (C) 2015-2026 Jonas Bernoulli |
| 5 | <emacs.magit@jonas.bernoulli.dev> |
| 6 | |
| 7 | You can redistribute this document and/or modify it under the terms |
| 8 | of the GNU General Public License as published by the Free Software |
| 9 | Foundation, either version 3 of the License, or (at your option) |
| 10 | any later version. |
| 11 | |
| 12 | This document is distributed in the hope that it will be useful, |
| 13 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 15 | General Public License for more details. |
| 16 | |
| 17 | INFO-DIR-SECTION Emacs |
| 18 | START-INFO-DIR-ENTRY |
| 19 | * Magit-Section: (magit-section). Use Magit sections in your own packages. |
| 20 | END-INFO-DIR-ENTRY |
| 21 | |
| 22 | |
| 23 | File: magit-section.info, Node: Top, Next: Introduction, Up: (dir) |
| 24 | |
| 25 | Magit-Section Developer Manual |
| 26 | ****************************** |
| 27 | |
| 28 | This package implements the main user interface of Magit — the |
| 29 | collapsible sections that make up its buffers. This package used to be |
| 30 | distributed as part of Magit but how it can also be used by other |
| 31 | packages that have nothing to do with Magit or Git. |
| 32 | |
| 33 | To learn more about the section abstraction and available commands |
| 34 | and user options see *note (magit)Sections::. This manual documents how |
| 35 | you can use sections in your own packages. |
| 36 | |
| 37 | This manual is for Magit-Section version 4.7.1. |
| 38 | |
| 39 | Copyright (C) 2015-2026 Jonas Bernoulli |
| 40 | <emacs.magit@jonas.bernoulli.dev> |
| 41 | |
| 42 | You can redistribute this document and/or modify it under the terms |
| 43 | of the GNU General Public License as published by the Free Software |
| 44 | Foundation, either version 3 of the License, or (at your option) |
| 45 | any later version. |
| 46 | |
| 47 | This document is distributed in the hope that it will be useful, |
| 48 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 49 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 50 | General Public License for more details. |
| 51 | |
| 52 | * Menu: |
| 53 | |
| 54 | * Introduction:: |
| 55 | * Creating Sections:: |
| 56 | * Core Functions:: |
| 57 | * Matching Functions:: |
| 58 | |
| 59 | |
| 60 | File: magit-section.info, Node: Introduction, Next: Creating Sections, Prev: Top, Up: Top |
| 61 | |
| 62 | 1 Introduction |
| 63 | ************** |
| 64 | |
| 65 | This package implements the main user interface of Magit — the |
| 66 | collapsible sections that make up its buffers. This package used to be |
| 67 | distributed as part of Magit but how it can also be used by other |
| 68 | packages that have nothing to do with Magit or Git. |
| 69 | |
| 70 | To learn more about the section abstraction and available commands |
| 71 | and user options see *note (magit)Sections::. This manual documents how |
| 72 | you can use sections in your own packages. |
| 73 | |
| 74 | When the documentation leaves something unaddressed, then please |
| 75 | consider that Magit uses this library extensively and search its source |
| 76 | for suitable examples before asking me for help. Thanks! |
| 77 | |
| 78 | |
| 79 | File: magit-section.info, Node: Creating Sections, Next: Core Functions, Prev: Introduction, Up: Top |
| 80 | |
| 81 | 2 Creating Sections |
| 82 | ******************* |
| 83 | |
| 84 | -- Macro: magit-insert-section [name] (type &optional value hide) &rest |
| 85 | body |
| 86 | Create a section object of type CLASS, storing VALUE in its ‘value’ |
| 87 | slot, and insert the section at point. CLASS is a subclass of |
| 88 | 'magit-section' or has the form ‘(eval FORM)’, in which case FORM |
| 89 | is evaluated at runtime and should return a subclass. In other |
| 90 | places a sections class is often referred to as its "type". |
| 91 | |
| 92 | Many commands behave differently depending on the class of the |
| 93 | current section and sections of a certain class can have their own |
| 94 | keymap, which is specified using the 'keymap' class slot. The |
| 95 | value of that slot should be a variable whose value is a keymap. |
| 96 | |
| 97 | For historic reasons Magit and Forge in most cases use symbols as |
| 98 | CLASS that don't actually identify a class and that lack the |
| 99 | appropriate package prefix. This works due to some undocumented |
| 100 | kludges, which are not available to other packages. |
| 101 | |
| 102 | When optional HIDE is non-‘nil’ collapse the section body by |
| 103 | default, i.e., when first creating the section, but not when |
| 104 | refreshing the buffer. Else expand it by default. This can be |
| 105 | overwritten using ‘magit-section-set-visibility-hook’. When a |
| 106 | section is recreated during a refresh, then the visibility of |
| 107 | predecessor is inherited and HIDE is ignored (but the hook is still |
| 108 | honored). |
| 109 | |
| 110 | BODY is any number of forms that actually insert the section's |
| 111 | heading and body. Optional NAME, if specified, has to be a symbol, |
| 112 | which is then bound to the object of the section being inserted. |
| 113 | |
| 114 | Before BODY is evaluated the ‘start’ of the section object is set |
| 115 | to the value of 'point' and after BODY was evaluated its ‘end’ is |
| 116 | set to the new value of ‘point’; BODY is responsible for moving |
| 117 | ‘point’ forward. |
| 118 | |
| 119 | If it turns out inside BODY that the section is empty, then |
| 120 | ‘magit-cancel-section’ can be used to abort and remove all traces |
| 121 | of the partially inserted section. This can happen when creating a |
| 122 | section by washing Git's output and Git didn't actually output |
| 123 | anything this time around. |
| 124 | |
| 125 | -- Function: magit-insert-heading [child-count] &rest args |
| 126 | Insert the heading for the section currently being inserted. |
| 127 | |
| 128 | This function should only be used inside ‘magit-insert-section’. |
| 129 | |
| 130 | When called without any arguments, then just set the ‘content’ slot |
| 131 | of the object representing the section being inserted to a marker |
| 132 | at ‘point’. The section should only contain a single line when |
| 133 | this function is used like this. |
| 134 | |
| 135 | When called with arguments ARGS, which have to be strings, or |
| 136 | ‘nil’, then insert those strings at point. The section should not |
| 137 | contain any text before this happens and afterwards it should again |
| 138 | only contain a single line. If the ‘face’ property is set anywhere |
| 139 | inside any of these strings, then insert all of them unchanged. |
| 140 | Otherwise use the 'magit-section-heading' face for all inserted |
| 141 | text. |
| 142 | |
| 143 | The ‘content’ property of the section object is the end of the |
| 144 | heading (which lasts from ‘start’ to ‘content’) and the beginning |
| 145 | of the the body (which lasts from ‘content’ to ‘end’). If the |
| 146 | value of ‘content’ is ‘nil’, then the section has no heading and |
| 147 | its body cannot be collapsed. If a section does have a heading, |
| 148 | then its height must be exactly one line, including a trailing |
| 149 | newline character. This isn't enforced, you are responsible for |
| 150 | getting it right. The only exception is that this function does |
| 151 | insert a newline character if necessary. |
| 152 | |
| 153 | If provided, optional CHILD-COUNT must evaluate to an integer or |
| 154 | boolean. If ‘t’, then the count is determined once the children |
| 155 | have been inserted, using ‘magit-insert-child-count’ (which see). |
| 156 | For historic reasons, if the heading ends with ":", the count is |
| 157 | substituted for that, at this time as well. If |
| 158 | ‘magit-section-show-child-count’ is ‘nil’, no counts are inserted |
| 159 | |
| 160 | -- Macro: magit-insert-section-body &rest body |
| 161 | Use BODY to insert the section body, once the section is expanded. |
| 162 | If the section is expanded when it is created, then this is like |
| 163 | ‘progn’. Otherwise BODY isn't evaluated until the section is |
| 164 | explicitly expanded. |
| 165 | |
| 166 | -- Function: magit-cancel-section |
| 167 | Cancel inserting the section that is currently being inserted. |
| 168 | Remove all traces of that section. |
| 169 | |
| 170 | -- Function: magit-wash-sequence function |
| 171 | Repeatedly call FUNCTION until it returns ‘nil’ or the end of the |
| 172 | buffer is reached. FUNCTION has to move point forward or return |
| 173 | ‘nil’. |
| 174 | |
| 175 | You have to define some function that calls ‘magit-insert-section’ to |
| 176 | populate a buffer with sections. After doing so, that function also has |
| 177 | to call a few other functions, to put the sections in a good initial |
| 178 | state. You will likely need these lines: |
| 179 | |
| 180 | (let ((magit-section-cache-visibility nil)) |
| 181 | (magit-section-show magit-root-section)) |
| 182 | (magit-section-update-highlight) |
| 183 | (set-buffer-modified-p nil) |
| 184 | |
| 185 | Magit does that in ‘magit-refresh-buffer’. Look at that function for |
| 186 | inspiration, and also check out how that function is being used in in |
| 187 | ‘magit-mode.el’. The code in that library is to specialized to Magit's |
| 188 | needs to be made part of the ‘magit-section’ package, but a magit-like |
| 189 | package will likely have to perform mode and buffer setup in a similar |
| 190 | fashion. |
| 191 | |
| 192 | |
| 193 | File: magit-section.info, Node: Core Functions, Next: Matching Functions, Prev: Creating Sections, Up: Top |
| 194 | |
| 195 | 3 Core Functions |
| 196 | **************** |
| 197 | |
| 198 | -- Function: magit-current-section |
| 199 | Return the section at point or where the context menu was invoked. |
| 200 | When using the context menu, return the section that the user |
| 201 | clicked on, provided the current buffer is the buffer in which the |
| 202 | click occurred. Otherwise return the section at point. |
| 203 | |
| 204 | Function magit-section-at &optional position |
| 205 | Return the section at POSITION, defaulting to point. Default to |
| 206 | point even when the context menu is used. |
| 207 | |
| 208 | -- Function: magit-section-ident section |
| 209 | Return an unique identifier for SECTION. The return value has the |
| 210 | form ‘((TYPE . VALUE)...)’. |
| 211 | |
| 212 | -- Function: magit-section-ident-value value |
| 213 | Return a constant representation of VALUE. |
| 214 | |
| 215 | VALUE is the value of a ‘magit-section’ object. If that is an |
| 216 | object itself, then that is not suitable to be used to identify the |
| 217 | section because two objects may represent the same thing but not be |
| 218 | equal. If possible a method should be added for such objects, |
| 219 | which returns a value that is equal. Otherwise the catch-all |
| 220 | method is used, which just returns the argument itself. |
| 221 | |
| 222 | -- Function: magit-get-section ident &optional root |
| 223 | Return the section identified by IDENT. IDENT has to be a list as |
| 224 | returned by ‘magit-section-ident’. If optional ROOT is non-‘nil’, |
| 225 | then search in that section tree instead of in the one whose root |
| 226 | ‘magit-root-section’ is. |
| 227 | |
| 228 | -- Function: magit-section-lineage section &optional raw |
| 229 | Return the lineage of SECTION. If optional RAW is non-‘nil’, |
| 230 | return a list of section objects, beginning with SECTION, otherwise |
| 231 | return a list of section types. |
| 232 | |
| 233 | -- Function: magit-section-content-p section |
| 234 | Return non-‘nil’ if SECTION has content or an unused washer |
| 235 | function. |
| 236 | |
| 237 | The next two functions are replacements for the Emacs functions that |
| 238 | have the same name except for the ‘magit-’ prefix. Like |
| 239 | ‘magit-current-section’ they do not act on point, the cursors position, |
| 240 | but on the position where the user clicked to invoke the context menu. |
| 241 | |
| 242 | If your package provides a context menu and some of its commands act |
| 243 | on the "thing at point", even if just as a default, then use the |
| 244 | prefixed functions to teach them to instead use the click location when |
| 245 | appropriate. |
| 246 | |
| 247 | Function magit-point |
| 248 | Return point or the position where the context menu was invoked. |
| 249 | When using the context menu, return the position the user clicked |
| 250 | on, provided the current buffer is the buffer in which the click |
| 251 | occurred. Otherwise return the same value as ‘point’. |
| 252 | |
| 253 | Function magit-thing-at-point thing &optional no-properties |
| 254 | Return the THING at point or where the context menu was invoked. |
| 255 | When using the context menu, return the thing the user clicked on, |
| 256 | provided the current buffer is the buffer in which the click |
| 257 | occurred. Otherwise return the same value as ‘thing-at-point’. |
| 258 | For the meaning of THING and NO-PROPERTIES see that function. |
| 259 | |
| 260 | |
| 261 | File: magit-section.info, Node: Matching Functions, Prev: Core Functions, Up: Top |
| 262 | |
| 263 | 4 Matching Functions |
| 264 | ******************** |
| 265 | |
| 266 | -- Function: magit-section-match condition &optional (section |
| 267 | (magit-current-section)) |
| 268 | Return ‘t’ if SECTION matches CONDITION. |
| 269 | |
| 270 | SECTION defaults to the section at point. If SECTION is not |
| 271 | specified and there also is no section at point, then return ‘nil’. |
| 272 | |
| 273 | CONDITION can take the following forms: |
| 274 | |
| 275 | • ‘(CONDITION...)’ matches if any of the CONDITIONs matches. |
| 276 | • ‘[CLASS...]’ matches if the section's class is the same as the |
| 277 | first CLASS or a subclass of that; the section's parent class |
| 278 | matches the second CLASS; and so on. |
| 279 | |
| 280 | • ‘[* CLASS...]’ matches sections that match [CLASS...] and also |
| 281 | recursively all their child sections. |
| 282 | • ‘CLASS’ matches if the section's class is the same as CLASS or |
| 283 | a subclass of that; regardless of the classes of the parent |
| 284 | sections. |
| 285 | |
| 286 | Each CLASS should be a class symbol, identifying a class that |
| 287 | derives from ‘magit-section’. For backward compatibility CLASS can |
| 288 | also be a "type symbol". A section matches such a symbol if the |
| 289 | value of its ‘type’ slot is ‘eq’. If a type symbol has an entry in |
| 290 | ‘magit--section-type-alist’, then a section also matches that type |
| 291 | if its class is a subclass of the class that corresponds to the |
| 292 | type as per that alist. |
| 293 | |
| 294 | Note that it is not necessary to specify the complete section |
| 295 | lineage as printed by ‘magit-describe-section-briefly’, unless of |
| 296 | course you want to be that precise. |
| 297 | |
| 298 | -- Function: magit-section-value-if condition &optional section |
| 299 | If the section at point matches CONDITION, then return its value. |
| 300 | |
| 301 | If optional SECTION is non-‘nil’ then test whether that matches |
| 302 | instead. If there is no section at point and SECTION is ‘nil’, |
| 303 | then return ‘nil’. If the section does not match, then return |
| 304 | ‘nil’. |
| 305 | |
| 306 | See ‘magit-section-match’ for the forms CONDITION can take. |
| 307 | |
| 308 | -- Macro: magit-section-case &rest clauses |
| 309 | Choose among clauses on the type of the section at point. |
| 310 | |
| 311 | Each clause looks like ‘(CONDITION BODY...)’. The type of the |
| 312 | section is compared against each CONDITION; the BODY forms of the |
| 313 | first match are evaluated sequentially and the value of the last |
| 314 | form is returned. Inside BODY the symbol ‘it’ is bound to the |
| 315 | section at point. If no clause succeeds or if there is no section |
| 316 | at point, return ‘nil’. |
| 317 | |
| 318 | See ‘magit-section-match’ for the forms CONDITION can take. |
| 319 | Additionally a CONDITION of ‘t’ is allowed in the final clause, and |
| 320 | matches if no other CONDITION match, even if there is no section at |
| 321 | point. |
| 322 | |
| 323 | |
| 324 | |
| 325 | Tag Table: |
| 326 | Node: Top810 |
| 327 | Node: Introduction2111 |
| 328 | Node: Creating Sections2881 |
| 329 | Node: Core Functions8630 |
| 330 | Node: Matching Functions11805 |
| 331 | |
| 332 | End Tag Table |
| 333 | |
| 334 | |
| 335 | Local Variables: |
| 336 | coding: utf-8 |
| 337 | End: |