magit-section.info (11697B)
1 This is magit-section.info, produced by makeinfo version 6.7 from 2 magit-section.texi. 3 4 Copyright (C) 2015-2021 Jonas Bernoulli <jonas@bernoul.li> 5 6 You can redistribute this document and/or modify it under the terms 7 of the GNU General Public License as published by the Free Software 8 Foundation, either version 3 of the License, or (at your option) 9 any later version. 10 11 This document is distributed in the hope that it will be useful, 12 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 General Public License for more details. 15 16 INFO-DIR-SECTION Emacs 17 START-INFO-DIR-ENTRY 18 * Magit-Section: (magit-section). Use Magit sections in your own packages. 19 END-INFO-DIR-ENTRY 20 21 22 File: magit-section.info, Node: Top, Next: Introduction, Up: (dir) 23 24 Magit-Section Developer Manual 25 ****************************** 26 27 This package implements the main user interface of Magit — the 28 collapsible sections that make up its buffers. This package used to be 29 distributed as part of Magit but how it can also be used by other 30 packages that have nothing to do with Magit or Git. 31 32 To learn more about the section abstraction and available commands 33 and user options see *note (magit)Sections::. This manual documents how 34 you can use sections in your own packages. 35 36 This manual is for Magit-Section version 3.3.0. 37 38 Copyright (C) 2015-2021 Jonas Bernoulli <jonas@bernoul.li> 39 40 You can redistribute this document and/or modify it under the terms 41 of the GNU General Public License as published by the Free Software 42 Foundation, either version 3 of the License, or (at your option) 43 any later version. 44 45 This document is distributed in the hope that it will be useful, 46 but WITHOUT ANY WARRANTY; without even the implied warranty of 47 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 48 General Public License for more details. 49 50 * Menu: 51 52 * Introduction:: 53 * Creating Sections:: 54 * Core Functions:: 55 * Matching Functions:: 56 57 58 File: magit-section.info, Node: Introduction, Next: Creating Sections, Prev: Top, Up: Top 59 60 1 Introduction 61 ************** 62 63 This package implements the main user interface of Magit — the 64 collapsible sections that make up its buffers. This package used to be 65 distributed as part of Magit but how it can also be used by other 66 packages that have nothing to do with Magit or Git. 67 68 To learn more about the section abstraction and available commands 69 and user options see *note (magit)Sections::. This manual documents how 70 you can use sections in your own packages. 71 72 When the documentation leaves something unaddressed, then please 73 consider that Magit uses this library extensively and search its source 74 for suitable examples before asking me for help. Thanks! 75 76 77 File: magit-section.info, Node: Creating Sections, Next: Core Functions, Prev: Introduction, Up: Top 78 79 2 Creating Sections 80 ******************* 81 82 -- Macro: magit-insert-section [name] (type &optional value hide) &rest 83 body 84 85 Create a section object of type CLASS, storing VALUE in its ‘value’ 86 slot, and insert the section at point. CLASS is a subclass of 87 ‘magit-section’ or has the form ‘(eval FORM)’, in which case FORM 88 is evaluated at runtime and should return a subclass. In other 89 places a sections class is oftern referred to as its "type". 90 91 Many commands behave differently depending on the class of the 92 current section and sections of a certain class can have their own 93 keymap, which is specified using the ‘keymap’ class slot. The 94 value of that slot should be a variable whose value is a keymap. 95 96 For historic reasons Magit and Forge in most cases use symbols as 97 CLASS that don’t actually identify a class and that lack the 98 appropriate package prefix. This works due to some undocumented 99 kludges, which are not available to other packages. 100 101 When optional HIDE is non-nil collapse the section body by default, 102 i.e. when first creating the section, but not when refreshing the 103 buffer. Else expand it by default. This can be overwritten using 104 ‘magit-section-set-visibility-hook’. When a section is recreated 105 during a refresh, then the visibility of predecessor is inherited 106 and HIDE is ignored (but the hook is still honored). 107 108 BODY is any number of forms that actually insert the section’s 109 heading and body. Optional NAME, if specified, has to be a symbol, 110 which is then bound to the object of the section being inserted. 111 112 Before BODY is evaluated the ‘start’ of the section object is set 113 to the value of ‘point’ and after BODY was evaluated its ‘end’ is 114 set to the new value of ‘point’; BODY is responsible for moving 115 ‘point’ forward. 116 117 If it turns out inside BODY that the section is empty, then 118 ‘magit-cancel-section’ can be used to abort and remove all traces 119 of the partially inserted section. This can happen when creating a 120 section by washing Git’s output and Git didn’t actually output 121 anything this time around. 122 123 -- Function: magit-insert-heading &rest args 124 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 154 Use BODY to insert the section body, once the section is expanded. 155 If the section is expanded when it is created, then this is like 156 ‘progn’. Otherwise BODY isn’t evaluated until the section is 157 explicitly expanded. 158 159 -- Function: magit-cancel-section 160 161 Cancel inserting the section that is currently being inserted. 162 Remove all traces of that section. 163 164 -- Function: magit-wash-sequence function 165 166 Repeatedly call FUNCTION until it returns ‘nil’ or the end of the 167 buffer is reached. FUNCTION has to move point forward or return 168 ‘nil’. 169 170 171 File: magit-section.info, Node: Core Functions, Next: Matching Functions, Prev: Creating Sections, Up: Top 172 173 3 Core Functions 174 **************** 175 176 -- Function: magit-current-section 177 178 Return the section at point. 179 180 -- Function: magit-section-ident section 181 182 Return an unique identifier for SECTION. The return value has the 183 form ‘((TYPE . VALUE)...)’. 184 185 -- Function: magit-section-ident-value value 186 187 Return a constant representation of VALUE. 188 189 VALUE is the value of a ‘magit-section’ object. If that is an 190 object itself, then that is not suitable to be used to identify the 191 section because two objects may represent the same thing but not be 192 equal. If possible a method should be added for such objects, 193 which returns a value that is equal. Otherwise the catch-all 194 method is used, which just returns the argument itself. 195 196 -- Function: magit-get-section ident &optional root 197 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 205 Return the lineage of SECTION. The return value has the form 206 ‘(TYPE...)’. 207 208 209 File: magit-section.info, Node: Matching Functions, Prev: Core Functions, Up: Top 210 211 4 Matching Functions 212 ******************** 213 214 -- Function: magit-section-match condition &optional (section 215 (magit-current-section)) 216 217 Return t if SECTION matches CONDITION. 218 219 SECTION defaults to the section at point. If SECTION is not 220 specified and there also is no section at point, then return nil. 221 222 CONDITION can take the following forms: 223 224 • ‘(CONDITION...)’ matches if any of the CONDITIONs matches. 225 226 • ‘[CLASS...]’ matches if the section’s class is the same as the 227 first CLASS or a subclass of that; the section’s parent class 228 matches the second CLASS; and so on. 229 230 • ‘[* CLASS...]’ matches sections that match [CLASS...] and also 231 recursively all their child sections. 232 233 • ‘CLASS’ matches if the section’s class is the same as CLASS or 234 a subclass of that; regardless of the classes of the parent 235 sections. 236 237 Each CLASS should be a class symbol, identifying a class that 238 derives from ‘magit-section’. For backward compatibility CLASS can 239 also be a "type symbol". A section matches such a symbol if the 240 value of its ‘type’ slot is ‘eq’. If a type symbol has an entry in 241 ‘magit--section-type-alist’, then a section also matches that type 242 if its class is a subclass of the class that corresponds to the 243 type as per that alist. 244 245 Note that it is not necessary to specify the complete section 246 lineage as printed by ‘magit-describe-section-briefly’, unless of 247 course you want to be that precise. 248 249 -- Function: magit-section-value-if condition &optional section 250 251 If the section at point matches CONDITION, then return its value. 252 253 If optional SECTION is non-nil then test whether that matches 254 instead. If there is no section at point and SECTION is nil, then 255 return nil. If the section does not match, then return nil. 256 257 See ‘magit-section-match’ for the forms CONDITION can take. 258 259 -- Macro: magit-section-case &rest clauses 260 261 Choose among clauses on the type of the section at point. 262 263 Each clause looks like ‘(CONDITION BODY...)’. The type of the 264 section is compared against each CONDITION; the BODY forms of the 265 first match are evaluated sequentially and the value of the last 266 form is returned. Inside BODY the symbol ‘it’ is bound to the 267 section at point. If no clause succeeds or if there is no section 268 at point, return nil. 269 270 See ‘magit-section-match’ for the forms CONDITION can take. 271 Additionally a CONDITION of t is allowed in the final clause, and 272 matches if no other CONDITION match, even if there is no section at 273 point. 274 275 276 277 Tag Table: 278 Node: Top788 279 Node: Introduction2069 280 Node: Creating Sections2839 281 Node: Core Functions7353 282 Node: Matching Functions8679 283 284 End Tag Table 285 286 287 Local Variables: 288 coding: utf-8 289 End: