magit-section.info (13460B)
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 204 Return the lineage of SECTION. The return value has the form 205 ‘(TYPE...)’. 206 207 -- Function: magit-section-content-p section 208 Return non-nil if SECTION has content or an unused washer function. 209 210 The next two functions are replacements for the Emacs functions that 211 have the same name except for the ‘magit-’ prefix. Like 212 ‘magit-current-section’ they do not act on point, the cursors position, 213 but on the position where the user clicked to invoke the context menu. 214 215 If your package provides a context menu and some of its commands act 216 on the "thing at point", even if just as a default, then use the 217 prefixed functions to teach them to instead use the click location when 218 appropriate. 219 220 Function magit-point 221 Return point or the position where the context menu was invoked. 222 When using the context menu, return the position the user clicked 223 on, provided the current buffer is the buffer in which the click 224 occurred. Otherwise return the same value as ‘point’. 225 226 Function magit-thing-at-point thing &optional no-properties 227 Return the THING at point or where the context menu was invoked. 228 When using the context menu, return the thing the user clicked on, 229 provided the current buffer is the buffer in which the click 230 occurred. Otherwise return the same value as ‘thing-at-point’. 231 For the meaning of THING and NO-PROPERTIES see that function. 232 233 234 File: magit-section.info, Node: Matching Functions, Prev: Core Functions, Up: Top 235 236 4 Matching Functions 237 ******************** 238 239 -- Function: magit-section-match condition &optional (section 240 (magit-current-section)) 241 Return t if SECTION matches CONDITION. 242 243 SECTION defaults to the section at point. If SECTION is not 244 specified and there also is no section at point, then return nil. 245 246 CONDITION can take the following forms: 247 248 • ‘(CONDITION...)’ matches if any of the CONDITIONs matches. 249 • ‘[CLASS...]’ matches if the section’s class is the same as the 250 first CLASS or a subclass of that; the section’s parent class 251 matches the second CLASS; and so on. 252 253 • ‘[* CLASS...]’ matches sections that match [CLASS...] and also 254 recursively all their child sections. 255 • ‘CLASS’ matches if the section’s class is the same as CLASS or 256 a subclass of that; regardless of the classes of the parent 257 sections. 258 259 Each CLASS should be a class symbol, identifying a class that 260 derives from ‘magit-section’. For backward compatibility CLASS can 261 also be a "type symbol". A section matches such a symbol if the 262 value of its ‘type’ slot is ‘eq’. If a type symbol has an entry in 263 ‘magit--section-type-alist’, then a section also matches that type 264 if its class is a subclass of the class that corresponds to the 265 type as per that alist. 266 267 Note that it is not necessary to specify the complete section 268 lineage as printed by ‘magit-describe-section-briefly’, unless of 269 course you want to be that precise. 270 271 -- Function: magit-section-value-if condition &optional section 272 If the section at point matches CONDITION, then return its value. 273 274 If optional SECTION is non-nil then test whether that matches 275 instead. If there is no section at point and SECTION is nil, then 276 return nil. If the section does not match, then return nil. 277 278 See ‘magit-section-match’ for the forms CONDITION can take. 279 280 -- Macro: magit-section-case &rest clauses 281 Choose among clauses on the type of the section at point. 282 283 Each clause looks like ‘(CONDITION BODY...)’. The type of the 284 section is compared against each CONDITION; the BODY forms of the 285 first match are evaluated sequentially and the value of the last 286 form is returned. Inside BODY the symbol ‘it’ is bound to the 287 section at point. If no clause succeeds or if there is no section 288 at point, return nil. 289 290 See ‘magit-section-match’ for the forms CONDITION can take. 291 Additionally a CONDITION of t is allowed in the final clause, and 292 matches if no other CONDITION match, even if there is no section at 293 point. 294 295 296 297 Tag Table: 298 Node: Top808 299 Node: Introduction2116 300 Node: Creating Sections2886 301 Node: Core Functions7394 302 Node: Matching Functions10446 303 304 End Tag Table 305 306 307 Local Variables: 308 coding: utf-8 309 End: