magit-section.info (13985B)
1 This is magit-section.info, produced by makeinfo version 6.8 from 2 magit-section.texi. 3 4 Copyright (C) 2015-2024 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 3.3.0.50-git. 38 39 Copyright (C) 2015-2024 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 default, 103 i.e., when first creating the section, but not when refreshing the 104 buffer. Else expand it by default. This can be overwritten using 105 ‘magit-section-set-visibility-hook’. When a section is recreated 106 during a refresh, then the visibility of predecessor is inherited 107 and HIDE is ignored (but the hook is still honored). 108 109 BODY is any number of forms that actually insert the section’s 110 heading and body. Optional NAME, if specified, has to be a symbol, 111 which is then bound to the object of the section being inserted. 112 113 Before BODY is evaluated the ‘start’ of the section object is set 114 to the value of ‘point’ and after BODY was evaluated its ‘end’ is 115 set to the new value of ‘point’; BODY is responsible for moving 116 ‘point’ forward. 117 118 If it turns out inside BODY that the section is empty, then 119 ‘magit-cancel-section’ can be used to abort and remove all traces 120 of the partially inserted section. This can happen when creating a 121 section by washing Git’s output and Git didn’t actually output 122 anything this time around. 123 124 -- Function: magit-insert-heading [child-count] &rest args 125 Insert the heading for the section currently being inserted. 126 127 This function should only be used inside ‘magit-insert-section’. 128 129 When called without any arguments, then just set the ‘content’ slot 130 of the object representing the section being inserted to a marker 131 at ‘point’. The section should only contain a single line when 132 this function is used like this. 133 134 When called with arguments ARGS, which have to be strings, or nil, 135 then insert those strings at point. The section should not contain 136 any text before this happens and afterwards it should again only 137 contain a single line. If the ‘face’ property is set anywhere 138 inside any of these strings, then insert all of them unchanged. 139 Otherwise use the ‘magit-section-heading’ face for all inserted 140 text. 141 142 The ‘content’ property of the section object is the end of the 143 heading (which lasts from ‘start’ to ‘content’) and the beginning 144 of the the body (which lasts from ‘content’ to ‘end’). If the 145 value of ‘content’ is nil, then the section has no heading and its 146 body cannot be collapsed. If a section does have a heading, then 147 its height must be exactly one line, including a trailing newline 148 character. This isn’t enforced, you are responsible for getting it 149 right. The only exception is that this function does insert a 150 newline character if necessary. 151 152 If provided, optional CHILD-COUNT must evaluate to an integer or 153 boolean. If t, then the count is determined once the children have 154 been inserted, using ‘magit-insert-child-count’ (which see). For 155 historic reasons, if the heading ends with ":", the count is 156 substituted for that, at this time as well. If 157 ‘magit-section-show-child-count’ is nil, no counts are inserted 158 159 -- Macro: magit-insert-section-body &rest body 160 Use BODY to insert the section body, once the section is expanded. 161 If the section is expanded when it is created, then this is like 162 ‘progn’. Otherwise BODY isn’t evaluated until the section is 163 explicitly expanded. 164 165 -- Function: magit-cancel-section 166 Cancel inserting the section that is currently being inserted. 167 Remove all traces of that section. 168 169 -- Function: magit-wash-sequence function 170 Repeatedly call FUNCTION until it returns ‘nil’ or the end of the 171 buffer is reached. FUNCTION has to move point forward or return 172 ‘nil’. 173 174 175 File: magit-section.info, Node: Core Functions, Next: Matching Functions, Prev: Creating Sections, Up: Top 176 177 3 Core Functions 178 **************** 179 180 -- Function: magit-current-section 181 Return the section at point or where the context menu was invoked. 182 When using the context menu, return the section that the user 183 clicked on, provided the current buffer is the buffer in which the 184 click occurred. Otherwise return the section at point. 185 186 Function magit-section-at &optional position 187 Return the section at POSITION, defaulting to point. Default to 188 point even when the context menu is used. 189 190 -- Function: magit-section-ident section 191 Return an unique identifier for SECTION. The return value has the 192 form ‘((TYPE . VALUE)...)’. 193 194 -- Function: magit-section-ident-value value 195 Return a constant representation of VALUE. 196 197 VALUE is the value of a ‘magit-section’ object. If that is an 198 object itself, then that is not suitable to be used to identify the 199 section because two objects may represent the same thing but not be 200 equal. If possible a method should be added for such objects, 201 which returns a value that is equal. Otherwise the catch-all 202 method is used, which just returns the argument itself. 203 204 -- Function: magit-get-section ident &optional root 205 Return the section identified by IDENT. IDENT has to be a list as 206 returned by ‘magit-section-ident’. If optional ROOT is non-nil, 207 then search in that section tree instead of in the one whose root 208 ‘magit-root-section’ is. 209 210 -- Function: magit-section-lineage section &optional raw 211 Return the lineage of SECTION. If optional RAW is non-nil, return 212 a list of section objects, beginning with SECTION, otherwise return 213 a list of section types. 214 215 -- Function: magit-section-content-p section 216 Return non-nil if SECTION has content or an unused washer function. 217 218 The next two functions are replacements for the Emacs functions that 219 have the same name except for the ‘magit-’ prefix. Like 220 ‘magit-current-section’ they do not act on point, the cursors position, 221 but on the position where the user clicked to invoke the context menu. 222 223 If your package provides a context menu and some of its commands act 224 on the "thing at point", even if just as a default, then use the 225 prefixed functions to teach them to instead use the click location when 226 appropriate. 227 228 Function magit-point 229 Return point or the position where the context menu was invoked. 230 When using the context menu, return the position the user clicked 231 on, provided the current buffer is the buffer in which the click 232 occurred. Otherwise return the same value as ‘point’. 233 234 Function magit-thing-at-point thing &optional no-properties 235 Return the THING at point or where the context menu was invoked. 236 When using the context menu, return the thing the user clicked on, 237 provided the current buffer is the buffer in which the click 238 occurred. Otherwise return the same value as ‘thing-at-point’. 239 For the meaning of THING and NO-PROPERTIES see that function. 240 241 242 File: magit-section.info, Node: Matching Functions, Prev: Core Functions, Up: Top 243 244 4 Matching Functions 245 ******************** 246 247 -- Function: magit-section-match condition &optional (section 248 (magit-current-section)) 249 Return t if SECTION matches CONDITION. 250 251 SECTION defaults to the section at point. If SECTION is not 252 specified and there also is no section at point, then return nil. 253 254 CONDITION can take the following forms: 255 256 • ‘(CONDITION...)’ matches if any of the CONDITIONs matches. 257 • ‘[CLASS...]’ matches if the section’s class is the same as the 258 first CLASS or a subclass of that; the section’s parent class 259 matches the second CLASS; and so on. 260 261 • ‘[* CLASS...]’ matches sections that match [CLASS...] and also 262 recursively all their child sections. 263 • ‘CLASS’ matches if the section’s class is the same as CLASS or 264 a subclass of that; regardless of the classes of the parent 265 sections. 266 267 Each CLASS should be a class symbol, identifying a class that 268 derives from ‘magit-section’. For backward compatibility CLASS can 269 also be a "type symbol". A section matches such a symbol if the 270 value of its ‘type’ slot is ‘eq’. If a type symbol has an entry in 271 ‘magit--section-type-alist’, then a section also matches that type 272 if its class is a subclass of the class that corresponds to the 273 type as per that alist. 274 275 Note that it is not necessary to specify the complete section 276 lineage as printed by ‘magit-describe-section-briefly’, unless of 277 course you want to be that precise. 278 279 -- Function: magit-section-value-if condition &optional section 280 If the section at point matches CONDITION, then return its value. 281 282 If optional SECTION is non-nil then test whether that matches 283 instead. If there is no section at point and SECTION is nil, then 284 return nil. If the section does not match, then return nil. 285 286 See ‘magit-section-match’ for the forms CONDITION can take. 287 288 -- Macro: magit-section-case &rest clauses 289 Choose among clauses on the type of the section at point. 290 291 Each clause looks like ‘(CONDITION BODY...)’. The type of the 292 section is compared against each CONDITION; the BODY forms of the 293 first match are evaluated sequentially and the value of the last 294 form is returned. Inside BODY the symbol ‘it’ is bound to the 295 section at point. If no clause succeeds or if there is no section 296 at point, return nil. 297 298 See ‘magit-section-match’ for the forms CONDITION can take. 299 Additionally a CONDITION of t is allowed in the final clause, and 300 matches if no other CONDITION match, even if there is no section at 301 point. 302 303 304 305 Tag Table: 306 Node: Top808 307 Node: Introduction2116 308 Node: Creating Sections2886 309 Node: Core Functions7819 310 Node: Matching Functions10971 311 312 End Tag Table 313 314 315 Local Variables: 316 coding: utf-8 317 End: