Mercurial > vim
annotate runtime/doc/fold.txt @ 31133:cc0c4141fb73 v9.0.0901
patch 9.0.0901: setting w_leftcol and handling side effects is confusing
Commit: https://github.com/vim/vim/commit/0c34d562647f029faca40f7733ccfb7b5377672b
Author: Bram Moolenaar <Bram@vim.org>
Date: Fri Nov 18 14:07:20 2022 +0000
patch 9.0.0901: setting w_leftcol and handling side effects is confusing
Problem: Setting w_leftcol and handling side effects is confusing.
Solution: Use a function to set w_leftcol() and handle side effects.
| author | Bram Moolenaar <Bram@vim.org> |
|---|---|
| date | Fri, 18 Nov 2022 15:15:04 +0100 |
| parents | f68f43043842 |
| children | 15c80d8bc515 |
| rev | line source |
|---|---|
| 30634 | 1 *fold.txt* For Vim version 9.0. Last change: 2022 Oct 01 |
| 7 | 2 |
| 3 | |
| 4 VIM REFERENCE MANUAL by Bram Moolenaar | |
| 5 | |
| 6 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
7 Folding *Folding* *folding* *folds* |
| 7 | 8 |
| 9 You can find an introduction on folding in chapter 28 of the user manual. | |
| 10 |usr_28.txt| | |
| 11 | |
| 12 1. Fold methods |fold-methods| | |
| 13 2. Fold commands |fold-commands| | |
| 14 3. Fold options |fold-options| | |
| 15 4. Behavior of folds |fold-behavior| | |
| 16 | |
|
2570
71b56b4e7785
Make the references to features in the help more consistent. (Sylvain Hitier)
Bram Moolenaar <bram@vim.org>
parents:
2561
diff
changeset
|
17 {not available when compiled without the |+folding| feature} |
| 7 | 18 |
| 19 ============================================================================== | |
| 20 1. Fold methods *fold-methods* | |
| 21 | |
| 22 The folding method can be set with the 'foldmethod' option. | |
| 23 | |
| 24 When setting 'foldmethod' to a value other than "manual", all folds are | |
| 25 deleted and new ones created. Switching to the "manual" method doesn't remove | |
| 26 the existing folds. This can be used to first define the folds automatically | |
| 27 and then change them manually. | |
| 28 | |
| 29 There are six methods to select folds: | |
| 30 manual manually define folds | |
| 31 indent more indent means a higher fold level | |
| 32 expr specify an expression to define folds | |
| 33 syntax folds defined by syntax highlighting | |
| 34 diff folds for unchanged text | |
| 35 marker folds defined by markers in the text | |
| 36 | |
| 37 | |
| 38 MANUAL *fold-manual* | |
| 39 | |
| 40 Use commands to manually define the fold regions. This can also be used by a | |
| 41 script that parses text to find folds. | |
| 42 | |
| 43 The level of a fold is only defined by its nesting. To increase the fold | |
| 44 level of a fold for a range of lines, define a fold inside it that has the | |
| 45 same lines. | |
| 46 | |
| 47 The manual folds are lost when you abandon the file. To save the folds use | |
| 48 the |:mkview| command. The view can be restored later with |:loadview|. | |
| 49 | |
| 50 | |
| 51 INDENT *fold-indent* | |
| 52 | |
| 53 The folds are automatically defined by the indent of the lines. | |
| 54 | |
| 55 The foldlevel is computed from the indent of the line, divided by the | |
| 56 'shiftwidth' (rounded down). A sequence of lines with the same or higher fold | |
| 57 level form a fold, with the lines with a higher level forming a nested fold. | |
| 58 | |
| 59 The nesting of folds is limited with 'foldnestmax'. | |
| 60 | |
| 61 Some lines are ignored and get the fold level of the line above or below it, | |
| 2826 | 62 whichever is lower. These are empty or white lines and lines starting |
| 7 | 63 with a character in 'foldignore'. White space is skipped before checking for |
| 64 characters in 'foldignore'. For C use "#" to ignore preprocessor lines. | |
| 65 | |
| 11062 | 66 When you want to ignore lines in another way, use the "expr" method. The |
| 7 | 67 |indent()| function can be used in 'foldexpr' to get the indent of a line. |
| 68 | |
| 69 | |
| 70 EXPR *fold-expr* | |
| 71 | |
| 72 The folds are automatically defined by their foldlevel, like with the "indent" | |
| 73 method. The value of the 'foldexpr' option is evaluated to get the foldlevel | |
| 74 of a line. Examples: | |
| 1255 | 75 This will create a fold for all consecutive lines that start with a tab: > |
| 7 | 76 :set foldexpr=getline(v:lnum)[0]==\"\\t\" |
| 77 This will make a fold out of paragraphs separated by blank lines: > | |
| 78 :set foldexpr=getline(v:lnum)=~'^\\s*$'&&getline(v:lnum+1)=~'\\S'?'<1':1 | |
|
11229
146a1e213b60
Update runtime files. Add Rust support.
Christian Brabandt <cb@256bit.org>
parents:
11062
diff
changeset
|
79 This does the same: > |
| 7 | 80 :set foldexpr=getline(v:lnum-1)=~'^\\s*$'&&getline(v:lnum)=~'\\S'?'>1':1 |
| 81 | |
| 82 Note that backslashes must be used to escape characters that ":set" handles | |
| 83 differently (space, backslash, double quote, etc., see |option-backslash|). | |
| 84 | |
|
30594
586b5b3aacf9
patch 9.0.0632: calling a function from an "expr" option has overhead
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
85 The most efficient is to call a compiled function without arguments: > |
|
586b5b3aacf9
patch 9.0.0632: calling a function from an "expr" option has overhead
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
86 :set foldexpr=MyFoldLevel() |
|
586b5b3aacf9
patch 9.0.0632: calling a function from an "expr" option has overhead
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
87 The function must use v:lnum. See |expr-option-function|. |
|
586b5b3aacf9
patch 9.0.0632: calling a function from an "expr" option has overhead
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
88 |
| 7 | 89 These are the conditions with which the expression is evaluated: |
| 90 - The current buffer and window are set for the line. | |
| 91 - The variable "v:lnum" is set to the line number. | |
| 92 - The result is used for the fold level in this way: | |
| 93 value meaning ~ | |
| 94 0 the line is not in a fold | |
| 95 1, 2, .. the line is in a fold with this level | |
| 96 -1 the fold level is undefined, use the fold level of a | |
| 97 line before or after this line, whichever is the | |
| 98 lowest. | |
| 99 "=" use fold level from the previous line | |
| 100 "a1", "a2", .. add one, two, .. to the fold level of the previous | |
|
7272
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
101 line, use the result for the current line |
| 7 | 102 "s1", "s2", .. subtract one, two, .. from the fold level of the |
|
7272
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
103 previous line, use the result for the next line |
| 7 | 104 "<1", "<2", .. a fold with this level ends at this line |
| 105 ">1", ">2", .. a fold with this level starts at this line | |
| 106 | |
| 107 It is not required to mark the start (end) of a fold with ">1" ("<1"), a fold | |
| 108 will also start (end) when the fold level is higher (lower) than the fold | |
| 109 level of the previous line. | |
| 110 | |
| 111 There must be no side effects from the expression. The text in the buffer, | |
| 112 cursor position, the search patterns, options etc. must not be changed. | |
| 818 | 113 You can change and restore them if you are careful. |
| 7 | 114 |
| 115 If there is some error in the expression, or the resulting value isn't | |
| 116 recognized, there is no error message and the fold level will be zero. | |
| 117 For debugging the 'debug' option can be set to "msg", the error messages will | |
| 118 be visible then. | |
| 119 | |
| 120 Note: Since the expression has to be evaluated for every line, this fold | |
| 121 method can be very slow! | |
| 122 | |
| 123 Try to avoid the "=", "a" and "s" return values, since Vim often has to search | |
| 124 backwards for a line for which the fold level is defined. This can be slow. | |
| 125 | |
|
26743
c2c40cefc17b
patch 8.2.3900: it is not easy to use a script-local function for an option
Bram Moolenaar <Bram@vim.org>
parents:
25402
diff
changeset
|
126 If the 'foldexpr' expression starts with s: or |<SID>|, then it is replaced |
|
26759
31c23760d590
patch 8.2.3908: cannot use a script-local function for 'foldtext'
Bram Moolenaar <Bram@vim.org>
parents:
26743
diff
changeset
|
127 with the script ID (|local-function|). Examples: > |
|
26743
c2c40cefc17b
patch 8.2.3900: it is not easy to use a script-local function for an option
Bram Moolenaar <Bram@vim.org>
parents:
25402
diff
changeset
|
128 set foldexpr=s:MyFoldExpr() |
|
c2c40cefc17b
patch 8.2.3900: it is not easy to use a script-local function for an option
Bram Moolenaar <Bram@vim.org>
parents:
25402
diff
changeset
|
129 set foldexpr=<SID>SomeFoldExpr() |
|
c2c40cefc17b
patch 8.2.3900: it is not easy to use a script-local function for an option
Bram Moolenaar <Bram@vim.org>
parents:
25402
diff
changeset
|
130 < |
|
7272
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
131 An example of using "a1" and "s1": For a multi-line C comment, a line |
|
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
132 containing "/*" would return "a1" to start a fold, and a line containing "*/" |
|
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
133 would return "s1" to end the fold after that line: > |
|
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
134 if match(thisline, '/\*') >= 0 |
|
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
135 return 'a1' |
|
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
136 elseif match(thisline, '\*/') >= 0 |
|
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
137 return 's1' |
|
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
138 else |
|
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
139 return '=' |
|
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
140 endif |
|
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
141 However, this won't work for single line comments, strings, etc. |
|
17333ebd2bbd
commit https://github.com/vim/vim/commit/d042dc825c9b97dacd84d4728f88300da4d5b6b9
Christian Brabandt <cb@256bit.org>
parents:
6725
diff
changeset
|
142 |
| 7 | 143 |foldlevel()| can be useful to compute a fold level relative to a previous |
| 144 fold level. But note that foldlevel() may return -1 if the level is not known | |
| 145 yet. And it returns the level at the start of the line, while a fold might | |
| 146 end in that line. | |
| 147 | |
| 11062 | 148 It may happen that folds are not updated properly. You can use |zx| or |zX| |
| 2152 | 149 to force updating folds. |
| 150 | |
| 7 | 151 |
| 152 SYNTAX *fold-syntax* | |
| 153 | |
| 154 A fold is defined by syntax items that have the "fold" argument. |:syn-fold| | |
| 155 | |
| 156 The fold level is defined by nesting folds. The nesting of folds is limited | |
| 157 with 'foldnestmax'. | |
| 158 | |
| 159 Be careful to specify proper syntax syncing. If this is not done right, folds | |
| 160 may differ from the displayed highlighting. This is especially relevant when | |
| 161 using patterns that match more than one line. In case of doubt, try using | |
| 162 brute-force syncing: > | |
| 163 :syn sync fromstart | |
| 164 | |
| 165 | |
| 166 DIFF *fold-diff* | |
| 167 | |
| 168 The folds are automatically defined for text that is not part of a change or | |
| 169 close to a change. | |
| 170 | |
| 171 This method only works properly when the 'diff' option is set for the current | |
| 172 window and changes are being displayed. Otherwise the whole buffer will be | |
| 173 one big fold. | |
| 174 | |
| 175 The 'diffopt' option can be used to specify the context. That is, the number | |
| 176 of lines between the fold and a change that are not included in the fold. For | |
| 177 example, to use a context of 8 lines: > | |
| 178 :set diffopt=filler,context:8 | |
| 179 The default context is six lines. | |
| 180 | |
| 181 When 'scrollbind' is also set, Vim will attempt to keep the same folds open in | |
| 182 other diff windows, so that the same text is visible. | |
| 183 | |
| 184 | |
| 185 MARKER *fold-marker* | |
| 186 | |
| 187 Markers in the text tell where folds start and end. This allows you to | |
| 188 precisely specify the folds. This will allow deleting and putting a fold, | |
| 189 without the risk of including the wrong lines. The 'foldtext' option is | |
| 190 normally set such that the text before the marker shows up in the folded line. | |
| 191 This makes it possible to give a name to the fold. | |
| 192 | |
| 193 Markers can have a level included, or can use matching pairs. Including a | |
| 194 level is easier, you don't have to add end markers and avoid problems with | |
| 195 non-matching marker pairs. Example: > | |
| 196 /* global variables {{{1 */ | |
| 197 int varA, varB; | |
| 198 | |
| 199 /* functions {{{1 */ | |
| 200 /* funcA() {{{2 */ | |
| 201 void funcA() {} | |
| 202 | |
| 203 /* funcB() {{{2 */ | |
| 204 void funcB() {} | |
| 205 | |
| 206 A fold starts at a "{{{" marker. The following number specifies the fold | |
| 207 level. What happens depends on the difference between the current fold level | |
| 208 and the level given by the marker: | |
| 209 1. If a marker with the same fold level is encountered, the previous fold | |
| 210 ends and another fold with the same level starts. | |
| 211 2. If a marker with a higher fold level is found, a nested fold is started. | |
|
11229
146a1e213b60
Update runtime files. Add Rust support.
Christian Brabandt <cb@256bit.org>
parents:
11062
diff
changeset
|
212 3. If a marker with a lower fold level is found, all folds up to and including |
| 7 | 213 this level end and a fold with the specified level starts. |
| 214 | |
| 33 | 215 The number indicates the fold level. A zero cannot be used (a marker with |
| 216 level zero is ignored). You can use "}}}" with a digit to indicate the level | |
| 217 of the fold that ends. The fold level of the following line will be one less | |
| 218 than the indicated level. Note that Vim doesn't look back to the level of the | |
| 219 matching marker (that would take too much time). Example: > | |
| 7 | 220 |
| 221 {{{1 | |
| 222 fold level here is 1 | |
| 223 {{{3 | |
| 224 fold level here is 3 | |
| 225 }}}3 | |
| 226 fold level here is 2 | |
| 227 | |
| 228 You can also use matching pairs of "{{{" and "}}}" markers to define folds. | |
| 229 Each "{{{" increases the fold level by one, each "}}}" decreases the fold | |
| 230 level by one. Be careful to keep the markers matching! Example: > | |
| 231 | |
| 232 {{{ | |
| 233 fold level here is 1 | |
| 234 {{{ | |
| 235 fold level here is 2 | |
| 236 }}} | |
| 237 fold level here is 1 | |
| 238 | |
| 239 You can mix using markers with a number and without a number. A useful way of | |
| 240 doing this is to use numbered markers for large folds, and unnumbered markers | |
| 241 locally in a function. For example use level one folds for the sections of | |
| 242 your file like "structure definitions", "local variables" and "functions". | |
| 243 Use level 2 markers for each definition and function, Use unnumbered markers | |
| 244 inside functions. When you make changes in a function to split up folds, you | |
| 245 don't have to renumber the markers. | |
| 246 | |
| 247 The markers can be set with the 'foldmarker' option. It is recommended to | |
| 248 keep this at the default value of "{{{,}}}", so that files can be exchanged | |
| 249 between Vim users. Only change it when it is required for the file (e.g., it | |
| 250 contains markers from another folding editor, or the default markers cause | |
| 251 trouble for the language of the file). | |
| 252 | |
| 253 *fold-create-marker* | |
| 254 "zf" can be used to create a fold defined by markers. Vim will insert the | |
| 255 markers for you. Vim will append the start and end marker, as specified with | |
| 256 'foldmarker'. The markers are appended to the end of the line. | |
| 257 'commentstring' is used if it isn't empty. | |
| 258 This does not work properly when: | |
| 259 - The line already contains a marker with a level number. Vim then doesn't | |
| 260 know what to do. | |
| 261 - Folds nearby use a level number in their marker which gets in the way. | |
| 262 - The line is inside a comment, 'commentstring' isn't empty and nested | |
| 263 comments don't work. For example with C: adding /* {{{ */ inside a comment | |
| 264 will truncate the existing comment. Either put the marker before or after | |
| 265 the comment, or add the marker manually. | |
| 266 Generally it's not a good idea to let Vim create markers when you already have | |
| 267 markers with a level number. | |
| 268 | |
| 269 *fold-delete-marker* | |
| 270 "zd" can be used to delete a fold defined by markers. Vim will delete the | |
| 271 markers for you. Vim will search for the start and end markers, as specified | |
| 272 with 'foldmarker', at the start and end of the fold. When the text around the | |
| 273 marker matches with 'commentstring', that text is deleted as well. | |
| 274 This does not work properly when: | |
| 275 - A line contains more than one marker and one of them specifies a level. | |
| 276 Only the first one is removed, without checking if this will have the | |
| 277 desired effect of deleting the fold. | |
| 278 - The marker contains a level number and is used to start or end several folds | |
| 279 at the same time. | |
| 280 | |
| 281 ============================================================================== | |
| 282 2. Fold commands *fold-commands* *E490* | |
| 283 | |
| 284 All folding commands start with "z". Hint: the "z" looks like a folded piece | |
| 285 of paper, if you look at it from the side. | |
| 286 | |
| 287 | |
| 288 CREATING AND DELETING FOLDS ~ | |
| 289 *zf* *E350* | |
| 290 zf{motion} or | |
| 291 {Visual}zf Operator to create a fold. | |
| 292 This only works when 'foldmethod' is "manual" or "marker". | |
| 293 The new fold will be closed for the "manual" method. | |
| 294 'foldenable' will be set. | |
| 295 Also see |fold-create-marker|. | |
| 296 | |
| 297 *zF* | |
|
2098
3259c3923c1e
Updated runtime an documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
2033
diff
changeset
|
298 zF Create a fold for [count] lines. Works like "zf". |
| 7 | 299 |
| 300 :{range}fo[ld] *:fold* *:fo* | |
| 301 Create a fold for the lines in {range}. Works like "zf". | |
| 302 | |
| 303 *zd* *E351* | |
| 42 | 304 zd Delete one fold at the cursor. When the cursor is on a folded |
| 7 | 305 line, that fold is deleted. Nested folds are moved one level |
| 5555 | 306 up. In Visual mode one level of all folds (partially) in the |
| 307 selected area are deleted. | |
| 308 Careful: This easily deletes more folds than you expect and | |
| 309 there is no undo for manual folding. | |
| 7 | 310 This only works when 'foldmethod' is "manual" or "marker". |
| 311 Also see |fold-delete-marker|. | |
| 312 | |
| 313 *zD* | |
| 314 zD Delete folds recursively at the cursor. In Visual mode all | |
| 315 folds (partially) in the selected area and all nested folds in | |
| 316 them are deleted. | |
| 317 This only works when 'foldmethod' is "manual" or "marker". | |
| 318 Also see |fold-delete-marker|. | |
| 319 | |
| 320 *zE* *E352* | |
| 321 zE Eliminate all folds in the window. | |
| 322 This only works when 'foldmethod' is "manual" or "marker". | |
| 323 Also see |fold-delete-marker|. | |
| 324 | |
| 325 | |
| 326 OPENING AND CLOSING FOLDS ~ | |
| 327 | |
| 328 A fold smaller than 'foldminlines' will always be displayed like it was open. | |
| 329 Therefore the commands below may work differently on small folds. | |
| 330 | |
| 331 *zo* | |
| 332 zo Open one fold under the cursor. When a count is given, that | |
| 333 many folds deep will be opened. In Visual mode one level of | |
| 334 folds is opened for all lines in the selected area. | |
| 335 | |
| 336 *zO* | |
| 337 zO Open all folds under the cursor recursively. Folds that don't | |
| 338 contain the cursor line are unchanged. | |
| 339 In Visual mode it opens all folds that are in the selected | |
| 340 area, also those that are only partly selected. | |
| 341 | |
| 342 *zc* | |
| 343 zc Close one fold under the cursor. When a count is given, that | |
| 344 many folds deep are closed. In Visual mode one level of folds | |
| 345 is closed for all lines in the selected area. | |
| 346 'foldenable' will be set. | |
| 347 | |
| 348 *zC* | |
| 349 zC Close all folds under the cursor recursively. Folds that | |
| 350 don't contain the cursor line are unchanged. | |
| 351 In Visual mode it closes all folds that are in the selected | |
| 352 area, also those that are only partly selected. | |
| 353 'foldenable' will be set. | |
| 354 | |
| 355 *za* | |
| 236 | 356 za When on a closed fold: open it. When folds are nested, you |
| 7 | 357 may have to use "za" several times. When a count is given, |
| 358 that many closed folds are opened. | |
| 359 When on an open fold: close it and set 'foldenable'. This | |
| 360 will only close one level, since using "za" again will open | |
| 361 the fold. When a count is given that many folds will be | |
| 362 closed (that's not the same as repeating "za" that many | |
| 363 times). | |
| 364 | |
| 365 *zA* | |
| 366 zA When on a closed fold: open it recursively. | |
| 367 When on an open fold: close it recursively and set | |
| 368 'foldenable'. | |
| 369 | |
| 370 *zv* | |
| 371 zv View cursor line: Open just enough folds to make the line in | |
| 372 which the cursor is located not folded. | |
| 373 | |
| 374 *zx* | |
| 375 zx Update folds: Undo manually opened and closed folds: re-apply | |
| 376 'foldlevel', then do "zv": View cursor line. | |
| 2152 | 377 Also forces recomputing folds. This is useful when using |
| 378 'foldexpr' and the buffer is changed in a way that results in | |
| 379 folds not to be updated properly. | |
| 7 | 380 |
| 381 *zX* | |
| 382 zX Undo manually opened and closed folds: re-apply 'foldlevel'. | |
| 2152 | 383 Also forces recomputing folds, like |zx|. |
| 7 | 384 |
| 385 *zm* | |
| 6725 | 386 zm Fold more: Subtract |v:count1| from 'foldlevel'. If 'foldlevel' was |
| 7 | 387 already zero nothing happens. |
| 388 'foldenable' will be set. | |
| 389 | |
| 390 *zM* | |
| 391 zM Close all folds: set 'foldlevel' to 0. | |
| 392 'foldenable' will be set. | |
| 393 | |
| 394 *zr* | |
| 6725 | 395 zr Reduce folding: Add |v:count1| to 'foldlevel'. |
| 7 | 396 |
| 397 *zR* | |
| 398 zR Open all folds. This sets 'foldlevel' to highest fold level. | |
| 399 | |
| 400 *:foldo* *:foldopen* | |
| 401 :{range}foldo[pen][!] | |
| 402 Open folds in {range}. When [!] is added all folds are | |
| 403 opened. Useful to see all the text in {range}. Without [!] | |
| 404 one level of folds is opened. | |
| 405 | |
| 406 *:foldc* *:foldclose* | |
| 407 :{range}foldc[lose][!] | |
| 408 Close folds in {range}. When [!] is added all folds are | |
| 409 closed. Useful to hide all the text in {range}. Without [!] | |
| 410 one level of folds is closed. | |
| 411 | |
| 412 *zn* | |
| 413 zn Fold none: reset 'foldenable'. All folds will be open. | |
| 414 | |
| 415 *zN* | |
| 416 zN Fold normal: set 'foldenable'. All folds will be as they | |
| 417 were before. | |
| 418 | |
| 419 *zi* | |
| 420 zi Invert 'foldenable'. | |
| 421 | |
| 422 | |
| 423 MOVING OVER FOLDS ~ | |
| 424 *[z* | |
| 425 [z Move to the start of the current open fold. If already at the | |
| 426 start, move to the start of the fold that contains it. If | |
| 427 there is no containing fold, the command fails. | |
|
2098
3259c3923c1e
Updated runtime an documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
2033
diff
changeset
|
428 When a count is used, repeats the command [count] times. |
| 7 | 429 |
| 430 *]z* | |
| 431 ]z Move to the end of the current open fold. If already at the | |
| 432 end, move to the end of the fold that contains it. If there | |
| 433 is no containing fold, the command fails. | |
|
2098
3259c3923c1e
Updated runtime an documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
2033
diff
changeset
|
434 When a count is used, repeats the command [count] times. |
| 7 | 435 |
| 436 *zj* | |
| 437 zj Move downwards to the start of the next fold. A closed fold | |
| 438 is counted as one fold. | |
|
2098
3259c3923c1e
Updated runtime an documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
2033
diff
changeset
|
439 When a count is used, repeats the command [count] times. |
| 7 | 440 This command can be used after an |operator|. |
| 441 | |
| 442 *zk* | |
| 443 zk Move upwards to the end of the previous fold. A closed fold | |
| 444 is counted as one fold. | |
|
2098
3259c3923c1e
Updated runtime an documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
2033
diff
changeset
|
445 When a count is used, repeats the command [count] times. |
| 7 | 446 This command can be used after an |operator|. |
| 447 | |
| 448 | |
| 449 EXECUTING COMMANDS ON FOLDS ~ | |
| 450 | |
| 16944 | 451 :[range]foldd[oopen] {cmd} *:foldd* *:folddo* *:folddoopen* |
| 7 | 452 Execute {cmd} on all lines that are not in a closed fold. |
| 453 When [range] is given, only these lines are used. | |
| 454 Each time {cmd} is executed the cursor is positioned on the | |
| 455 line it is executed for. | |
| 456 This works like the ":global" command: First all lines that | |
| 457 are not in a closed fold are marked. Then the {cmd} is | |
| 458 executed for all marked lines. Thus when {cmd} changes the | |
| 459 folds, this has no influence on where it is executed (except | |
| 460 when lines are deleted, of course). | |
| 461 Example: > | |
| 462 :folddoopen s/end/loop_end/ge | |
| 463 < Note the use of the "e" flag to avoid getting an error message | |
| 464 where "end" doesn't match. | |
| 465 | |
| 466 :[range]folddoc[losed] {cmd} *:folddoc* *:folddoclosed* | |
| 467 Execute {cmd} on all lines that are in a closed fold. | |
| 468 Otherwise like ":folddoopen". | |
| 469 | |
| 470 ============================================================================== | |
| 471 3. Fold options *fold-options* | |
| 472 | |
| 473 COLORS *fold-colors* | |
| 474 | |
| 475 The colors of a closed fold are set with the Folded group |hl-Folded|. The | |
| 476 colors of the fold column are set with the FoldColumn group |hl-FoldColumn|. | |
| 477 Example to set the colors: > | |
| 478 | |
| 479 :highlight Folded guibg=grey guifg=blue | |
| 480 :highlight FoldColumn guibg=darkgrey guifg=white | |
| 481 | |
| 482 | |
| 483 FOLDLEVEL *fold-foldlevel* | |
| 484 | |
| 485 'foldlevel' is a number option: The higher the more folded regions are open. | |
| 486 When 'foldlevel' is 0, all folds are closed. | |
| 42 | 487 When 'foldlevel' is positive, some folds are closed. |
| 7 | 488 When 'foldlevel' is very high, all folds are open. |
| 489 'foldlevel' is applied when it is changed. After that manually folds can be | |
| 490 opened and closed. | |
| 491 When increased, folds above the new level are opened. No manually opened | |
| 492 folds will be closed. | |
| 493 When decreased, folds above the new level are closed. No manually closed | |
| 494 folds will be opened. | |
| 495 | |
| 496 | |
| 497 FOLDTEXT *fold-foldtext* | |
| 498 | |
| 499 'foldtext' is a string option that specifies an expression. This expression | |
| 500 is evaluated to obtain the text displayed for a closed fold. Example: > | |
| 501 | |
| 502 :set foldtext=v:folddashes.substitute(getline(v:foldstart),'/\\*\\\|\\*/\\\|{{{\\d\\=','','g') | |
| 503 | |
| 504 This shows the first line of the fold, with "/*", "*/" and "{{{" removed. | |
| 505 Note the use of backslashes to avoid some characters to be interpreted by the | |
| 30634 | 506 ":set" command. It is much simpler to define a function and call it: > |
| 7 | 507 |
| 508 :set foldtext=MyFoldText() | |
| 509 :function MyFoldText() | |
| 510 : let line = getline(v:foldstart) | |
| 511 : let sub = substitute(line, '/\*\|\*/\|{{{\d\=', '', 'g') | |
| 27903 | 512 : return v:folddashes .. sub |
| 7 | 513 :endfunction |
| 514 | |
| 30634 | 515 The advantage of using a function call without arguments is that it is faster, |
| 516 see |expr-option-function|. | |
| 517 | |
| 7 | 518 Evaluating 'foldtext' is done in the |sandbox|. The current window is set to |
| 27321 | 519 the window that displays the line. The context is set to the script where the |
| 520 option was last set. | |
| 521 | |
| 522 Errors are ignored. For debugging set the 'debug' option to "throw". | |
| 7 | 523 |
| 524 The default value is |foldtext()|. This returns a reasonable text for most | |
| 525 types of folding. If you don't like it, you can specify your own 'foldtext' | |
| 526 expression. It can use these special Vim variables: | |
| 527 v:foldstart line number of first line in the fold | |
| 528 v:foldend line number of last line in the fold | |
| 529 v:folddashes a string that contains dashes to represent the | |
| 530 foldlevel. | |
| 531 v:foldlevel the foldlevel of the fold | |
| 532 | |
| 533 In the result a TAB is replaced with a space and unprintable characters are | |
| 534 made into printable characters. | |
| 535 | |
| 536 The resulting line is truncated to fit in the window, it never wraps. | |
| 537 When there is room after the text, it is filled with the character specified | |
| 538 by 'fillchars'. | |
| 539 | |
|
26759
31c23760d590
patch 8.2.3908: cannot use a script-local function for 'foldtext'
Bram Moolenaar <Bram@vim.org>
parents:
26743
diff
changeset
|
540 If the 'foldtext' expression starts with s: or |<SID>|, then it is replaced |
|
31c23760d590
patch 8.2.3908: cannot use a script-local function for 'foldtext'
Bram Moolenaar <Bram@vim.org>
parents:
26743
diff
changeset
|
541 with the script ID (|local-function|). Examples: > |
|
31c23760d590
patch 8.2.3908: cannot use a script-local function for 'foldtext'
Bram Moolenaar <Bram@vim.org>
parents:
26743
diff
changeset
|
542 set foldtext=s:MyFoldText() |
|
31c23760d590
patch 8.2.3908: cannot use a script-local function for 'foldtext'
Bram Moolenaar <Bram@vim.org>
parents:
26743
diff
changeset
|
543 set foldtext=<SID>SomeFoldText() |
|
31c23760d590
patch 8.2.3908: cannot use a script-local function for 'foldtext'
Bram Moolenaar <Bram@vim.org>
parents:
26743
diff
changeset
|
544 < |
| 7 | 545 Note that backslashes need to be used for characters that the ":set" command |
| 546 handles differently: Space, backslash and double-quote. |option-backslash| | |
| 547 | |
| 548 | |
| 549 FOLDCOLUMN *fold-foldcolumn* | |
| 550 | |
| 551 'foldcolumn' is a number, which sets the width for a column on the side of the | |
| 552 window to indicate folds. When it is zero, there is no foldcolumn. A normal | |
| 519 | 553 value is 4 or 5. The minimal useful value is 2, although 1 still provides |
| 554 some information. The maximum is 12. | |
| 7 | 555 |
| 556 An open fold is indicated with a column that has a '-' at the top and '|' | |
| 557 characters below it. This column stops where the open fold stops. When folds | |
| 558 nest, the nested fold is one character right of the fold it's contained in. | |
| 559 | |
| 560 A closed fold is indicated with a '+'. | |
| 561 | |
| 25402 | 562 These characters can be changed with the 'fillchars' option. |
| 563 | |
| 7 | 564 Where the fold column is too narrow to display all nested folds, digits are |
| 565 shown to indicate the nesting level. | |
| 566 | |
| 567 The mouse can also be used to open and close folds by clicking in the | |
| 568 fold column: | |
| 569 - Click on a '+' to open the closed fold at this row. | |
| 570 - Click on any other non-blank character to close the open fold at this row. | |
| 571 | |
| 572 | |
| 573 OTHER OPTIONS | |
| 574 | |
| 575 'foldenable' 'fen': Open all folds while not set. | |
| 576 'foldexpr' 'fde': Expression used for "expr" folding. | |
| 577 'foldignore' 'fdi': Characters used for "indent" folding. | |
| 578 'foldmarker' 'fmr': Defined markers used for "marker" folding. | |
| 579 'foldmethod' 'fdm': Name of the current folding method. | |
| 580 'foldminlines' 'fml': Minimum number of screen lines for a fold to be | |
| 581 displayed closed. | |
| 582 'foldnestmax' 'fdn': Maximum nesting for "indent" and "syntax" folding. | |
| 583 'foldopen' 'fdo': Which kinds of commands open closed folds. | |
| 584 'foldclose' 'fcl': When the folds not under the cursor are closed. | |
| 585 | |
| 586 ============================================================================== | |
| 587 4. Behavior of folds *fold-behavior* | |
| 588 | |
| 589 When moving the cursor upwards or downwards and when scrolling, the cursor | |
| 590 will move to the first line of a sequence of folded lines. When the cursor is | |
| 591 already on a folded line, it moves to the next unfolded line or the next | |
| 592 closed fold. | |
| 593 | |
| 594 While the cursor is on folded lines, the cursor is always displayed in the | |
| 595 first column. The ruler does show the actual cursor position, but since the | |
| 596 line is folded, it cannot be displayed there. | |
| 597 | |
| 598 Many movement commands handle a sequence of folded lines like an empty line. | |
| 599 For example, the "w" command stops once in the first column. | |
| 600 | |
| 601 When in Insert mode, the cursor line is never folded. That allows you to see | |
| 602 what you type! | |
| 603 | |
| 604 When using an operator, a closed fold is included as a whole. Thus "dl" | |
| 605 deletes the whole closed fold under the cursor. | |
| 606 | |
|
7465
71e2aca45b81
commit https://github.com/vim/vim/commit/a3306958dcb9aadff1e1e8521d908d86b10ac99a
Christian Brabandt <cb@256bit.org>
parents:
7272
diff
changeset
|
607 For Ex commands that work on buffer lines the range is adjusted to always |
|
71e2aca45b81
commit https://github.com/vim/vim/commit/a3306958dcb9aadff1e1e8521d908d86b10ac99a
Christian Brabandt <cb@256bit.org>
parents:
7272
diff
changeset
|
608 start at the first line of a closed fold and end at the last line of a closed |
|
71e2aca45b81
commit https://github.com/vim/vim/commit/a3306958dcb9aadff1e1e8521d908d86b10ac99a
Christian Brabandt <cb@256bit.org>
parents:
7272
diff
changeset
|
609 fold. Thus this command: > |
| 7 | 610 :s/foo/bar/g |
| 611 when used with the cursor on a closed fold, will replace "foo" with "bar" in | |
| 612 all lines of the fold. | |
| 613 This does not happen for |:folddoopen| and |:folddoclosed|. | |
| 614 | |
| 615 When editing a buffer that has been edited before, the last used folding | |
| 616 settings are used again. For manual folding the defined folds are restored. | |
| 617 For all folding methods the manually opened and closed folds are restored. | |
| 618 If this buffer has been edited in this window, the values from back then are | |
| 619 used. Otherwise the values from the window where the buffer was edited last | |
| 620 are used. | |
| 621 | |
| 622 ============================================================================== | |
| 14421 | 623 vim:tw=78:ts=8:noet:ft=help:norl: |