magit-section.info (13560B)
1 This is magit-section.info, produced by makeinfo version 6.7 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 &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 -- Macro: magit-insert-section-body &rest body 153 Use BODY to insert the section body, once the section is expanded. 154 If the section is expanded when it is created, then this is like 155 ‘progn’. Otherwise BODY isn’t evaluated until the section is 156 explicitly expanded. 157 158 -- Function: magit-cancel-section 159 Cancel inserting the section that is currently being inserted. 160 Remove all traces of that section. 161 162 -- Function: magit-wash-sequence function 163 Repeatedly call FUNCTION until it returns ‘nil’ or the end of the 164 buffer is reached. FUNCTION has to move point forward or return 165 ‘nil’. 166 167 168 File: magit-section.info, Node: Core Functions, Next: Matching Functions, Prev: Creating Sections, Up: Top 169 170 3 Core Functions 171 **************** 172 173 -- Function: magit-current-section 174 Return the section at point or where the context menu was invoked. 175 When using the context menu, return the section that the user 176 clicked on, provided the current buffer is the buffer in which the 177 click occurred. Otherwise return the section at point. 178 179 Function magit-section-at &optional position 180 Return the section at POSITION, defaulting to point. Default to 181 point even when the context menu is used. 182 183 -- Function: magit-section-ident section 184 Return an unique identifier for SECTION. The return value has the 185 form ‘((TYPE . VALUE)...)’. 186 187 -- Function: magit-section-ident-value value 188 Return a constant representation of VALUE. 189 190 VALUE is the value of a ‘magit-section’ object. If that is an 191 object itself, then that is not suitable to be used to identify the 192 section because two objects may represent the same thing but not be 193 equal. If possible a method should be added for such objects, 194 which returns a value that is equal. Otherwise the catch-all 195 method is used, which just returns the argument itself. 196 197 -- Function: magit-get-section ident &optional root 198 Return the section identified by IDENT. IDENT has to be a list as 199 returned by ‘magit-section-ident’. If optional ROOT is non-nil, 200 then search in that section tree instead of in the one whose root 201 ‘magit-root-section’ is. 202 203 -- Function: magit-section-lineage section &optional raw 204 Return the lineage of SECTION. If optional RAW is non-nil, return 205 a list of section objects, beginning with SECTION, otherwise return 206 a list of section types. 207 208 -- Function: magit-section-content-p section 209 Return non-nil if SECTION has content or an unused washer function. 210 211 The next two functions are replacements for the Emacs functions that 212 have the same name except for the ‘magit-’ prefix. Like 213 ‘magit-current-section’ they do not act on point, the cursors position, 214 but on the position where the user clicked to invoke the context menu. 215 216 If your package provides a context menu and some of its commands act 217 on the "thing at point", even if just as a default, then use the 218 prefixed functions to teach them to instead use the click location when 219 appropriate. 220 221 Function magit-point 222 Return point or the position where the context menu was invoked. 223 When using the context menu, return the position the user clicked 224 on, provided the current buffer is the buffer in which the click 225 occurred. Otherwise return the same value as ‘point’. 226 227 Function magit-thing-at-point thing &optional no-properties 228 Return the THING at point or where the context menu was invoked. 229 When using the context menu, return the thing the user clicked on, 230 provided the current buffer is the buffer in which the click 231 occurred. Otherwise return the same value as ‘thing-at-point’. 232 For the meaning of THING and NO-PROPERTIES see that function. 233 234 235 File: magit-section.info, Node: Matching Functions, Prev: Core Functions, Up: Top 236 237 4 Matching Functions 238 ******************** 239 240 -- Function: magit-section-match condition &optional (section 241 (magit-current-section)) 242 Return t if SECTION matches CONDITION. 243 244 SECTION defaults to the section at point. If SECTION is not 245 specified and there also is no section at point, then return nil. 246 247 CONDITION can take the following forms: 248 249 • ‘(CONDITION...)’ matches if any of the CONDITIONs matches. 250 • ‘[CLASS...]’ matches if the section’s class is the same as the 251 first CLASS or a subclass of that; the section’s parent class 252 matches the second CLASS; and so on. 253 254 • ‘[* CLASS...]’ matches sections that match [CLASS...] and also 255 recursively all their child sections. 256 • ‘CLASS’ matches if the section’s class is the same as CLASS or 257 a subclass of that; regardless of the classes of the parent 258 sections. 259 260 Each CLASS should be a class symbol, identifying a class that 261 derives from ‘magit-section’. For backward compatibility CLASS can 262 also be a "type symbol". A section matches such a symbol if the 263 value of its ‘type’ slot is ‘eq’. If a type symbol has an entry in 264 ‘magit--section-type-alist’, then a section also matches that type 265 if its class is a subclass of the class that corresponds to the 266 type as per that alist. 267 268 Note that it is not necessary to specify the complete section 269 lineage as printed by ‘magit-describe-section-briefly’, unless of 270 course you want to be that precise. 271 272 -- Function: magit-section-value-if condition &optional section 273 If the section at point matches CONDITION, then return its value. 274 275 If optional SECTION is non-nil then test whether that matches 276 instead. If there is no section at point and SECTION is nil, then 277 return nil. If the section does not match, then return nil. 278 279 See ‘magit-section-match’ for the forms CONDITION can take. 280 281 -- Macro: magit-section-case &rest clauses 282 Choose among clauses on the type of the section at point. 283 284 Each clause looks like ‘(CONDITION BODY...)’. The type of the 285 section is compared against each CONDITION; the BODY forms of the 286 first match are evaluated sequentially and the value of the last 287 form is returned. Inside BODY the symbol ‘it’ is bound to the 288 section at point. If no clause succeeds or if there is no section 289 at point, return nil. 290 291 See ‘magit-section-match’ for the forms CONDITION can take. 292 Additionally a CONDITION of t is allowed in the final clause, and 293 matches if no other CONDITION match, even if there is no section at 294 point. 295 296 297 298 Tag Table: 299 Node: Top808 300 Node: Introduction2116 301 Node: Creating Sections2886 302 Node: Core Functions7394 303 Node: Matching Functions10546 304 305 End Tag Table 306 307 308 Local Variables: 309 coding: utf-8 310 End: