Mercurial > vim
annotate runtime/doc/fold.txt @ 33399:95db67c7b754 v9.0.1958
patch 9.0.1958: cannot complete option values
Commit: https://github.com/vim/vim/commit/900894b09a95398dfc75599e9f0aa2ea25723384
Author: Yee Cheng Chin <ychin.git@gmail.com>
Date: Fri Sep 29 20:42:32 2023 +0200
patch 9.0.1958: cannot complete option values
Problem: cannot complete option values
Solution: Add completion functions for several options
Add cmdline tab-completion for setting string options
Add tab-completion for setting string options on the cmdline using
`:set=` (along with `:set+=` and `:set-=`).
The existing tab completion for setting options currently only works
when nothing is typed yet, and it only fills in with the existing value,
e.g. when the user does `:set diffopt=<Tab>` it will be completed to
`set diffopt=internal,filler,closeoff` and nothing else. This isn't too
useful as a user usually wants auto-complete to suggest all the possible
values, such as 'iblank', or 'algorithm:patience'.
For set= and set+=, this adds a new optional callback function for each
option that can be invoked when doing completion. This allows for each
option to have control over how completion works. For example, in
'diffopt', it will suggest the default enumeration, but if `algorithm:`
is selected, it will further suggest different algorithm types like
'meyers' and 'patience'. When using set=, the existing option value will
be filled in as the first choice to preserve the existing behavior. When
using set+= this won't happen as it doesn't make sense.
For flag list options (e.g. 'mouse' and 'guioptions'), completion will
take into account existing typed values (and in the case of set+=, the
existing option value) to make sure it doesn't suggest duplicates.
For set-=, there is a new `ExpandSettingSubtract` function which will
handle flag list and comma-separated options smartly, by only suggesting
values that currently exist in the option.
Note that Vim has some existing code that adds special handling for
'filetype', 'syntax', and misc dir options like 'backupdir'. This change
preserves them as they already work, instead of converting to the new
callback API for each option.
closes: #13182
Signed-off-by: Christian Brabandt <cb@256bit.org>
Co-authored-by: Yee Cheng Chin <ychin.git@gmail.com>
| author | Christian Brabandt <cb@256bit.org> |
|---|---|
| date | Fri, 29 Sep 2023 20:45:04 +0200 |
| parents | b2e8663e6dcc |
| children | 4635e43f2c6f |
| rev | line source |
|---|---|
| 32294 | 1 *fold.txt* For Vim version 9.0. Last change: 2023 Mar 24 |
| 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() {} | |
| 31885 | 205 < *{{{* *}}}* |
| 7 | 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* | |
| 32294 | 356 za Summary: Toggle the fold under the cursor. |
| 357 When on a closed fold: open it. When folds are nested, you | |
| 7 | 358 may have to use "za" several times. When a count is given, |
| 359 that many closed folds are opened. | |
| 360 When on an open fold: close it and set 'foldenable'. This | |
| 361 will only close one level, since using "za" again will open | |
| 362 the fold. When a count is given that many folds will be | |
| 363 closed (that's not the same as repeating "za" that many | |
| 364 times). | |
| 365 | |
| 366 *zA* | |
| 367 zA When on a closed fold: open it recursively. | |
| 368 When on an open fold: close it recursively and set | |
| 369 'foldenable'. | |
| 370 | |
| 371 *zv* | |
| 372 zv View cursor line: Open just enough folds to make the line in | |
| 373 which the cursor is located not folded. | |
| 374 | |
| 375 *zx* | |
| 376 zx Update folds: Undo manually opened and closed folds: re-apply | |
| 377 'foldlevel', then do "zv": View cursor line. | |
| 2152 | 378 Also forces recomputing folds. This is useful when using |
| 379 'foldexpr' and the buffer is changed in a way that results in | |
| 380 folds not to be updated properly. | |
| 7 | 381 |
| 382 *zX* | |
| 383 zX Undo manually opened and closed folds: re-apply 'foldlevel'. | |
| 2152 | 384 Also forces recomputing folds, like |zx|. |
| 7 | 385 |
| 386 *zm* | |
| 6725 | 387 zm Fold more: Subtract |v:count1| from 'foldlevel'. If 'foldlevel' was |
| 7 | 388 already zero nothing happens. |
| 389 'foldenable' will be set. | |
| 390 | |
| 391 *zM* | |
| 392 zM Close all folds: set 'foldlevel' to 0. | |
| 393 'foldenable' will be set. | |
| 394 | |
| 395 *zr* | |
| 6725 | 396 zr Reduce folding: Add |v:count1| to 'foldlevel'. |
| 7 | 397 |
| 398 *zR* | |
| 399 zR Open all folds. This sets 'foldlevel' to highest fold level. | |
| 400 | |
| 401 *:foldo* *:foldopen* | |
| 402 :{range}foldo[pen][!] | |
| 403 Open folds in {range}. When [!] is added all folds are | |
| 404 opened. Useful to see all the text in {range}. Without [!] | |
| 405 one level of folds is opened. | |
| 406 | |
| 407 *:foldc* *:foldclose* | |
| 408 :{range}foldc[lose][!] | |
| 409 Close folds in {range}. When [!] is added all folds are | |
| 410 closed. Useful to hide all the text in {range}. Without [!] | |
| 411 one level of folds is closed. | |
| 412 | |
| 413 *zn* | |
| 414 zn Fold none: reset 'foldenable'. All folds will be open. | |
| 415 | |
| 416 *zN* | |
| 417 zN Fold normal: set 'foldenable'. All folds will be as they | |
| 418 were before. | |
| 419 | |
| 420 *zi* | |
| 421 zi Invert 'foldenable'. | |
| 422 | |
| 423 | |
| 424 MOVING OVER FOLDS ~ | |
| 425 *[z* | |
| 426 [z Move to the start of the current open fold. If already at the | |
| 427 start, move to the start of the fold that contains it. If | |
| 428 there is no containing fold, the command fails. | |
|
2098
3259c3923c1e
Updated runtime an documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
2033
diff
changeset
|
429 When a count is used, repeats the command [count] times. |
| 7 | 430 |
| 431 *]z* | |
| 432 ]z Move to the end of the current open fold. If already at the | |
| 433 end, move to the end of the fold that contains it. If there | |
| 434 is no containing fold, the command fails. | |
|
2098
3259c3923c1e
Updated runtime an documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
2033
diff
changeset
|
435 When a count is used, repeats the command [count] times. |
| 7 | 436 |
| 437 *zj* | |
| 438 zj Move downwards to the start of the next fold. A closed fold | |
| 439 is counted as one fold. | |
|
2098
3259c3923c1e
Updated runtime an documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
2033
diff
changeset
|
440 When a count is used, repeats the command [count] times. |
| 7 | 441 This command can be used after an |operator|. |
| 442 | |
| 443 *zk* | |
| 444 zk Move upwards to the end of the previous fold. A closed fold | |
| 445 is counted as one fold. | |
|
2098
3259c3923c1e
Updated runtime an documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
2033
diff
changeset
|
446 When a count is used, repeats the command [count] times. |
| 7 | 447 This command can be used after an |operator|. |
| 448 | |
| 449 | |
| 450 EXECUTING COMMANDS ON FOLDS ~ | |
| 451 | |
| 16944 | 452 :[range]foldd[oopen] {cmd} *:foldd* *:folddo* *:folddoopen* |
| 7 | 453 Execute {cmd} on all lines that are not in a closed fold. |
| 454 When [range] is given, only these lines are used. | |
| 455 Each time {cmd} is executed the cursor is positioned on the | |
| 456 line it is executed for. | |
| 457 This works like the ":global" command: First all lines that | |
| 458 are not in a closed fold are marked. Then the {cmd} is | |
| 459 executed for all marked lines. Thus when {cmd} changes the | |
| 460 folds, this has no influence on where it is executed (except | |
| 461 when lines are deleted, of course). | |
| 462 Example: > | |
| 463 :folddoopen s/end/loop_end/ge | |
| 464 < Note the use of the "e" flag to avoid getting an error message | |
| 465 where "end" doesn't match. | |
| 466 | |
| 467 :[range]folddoc[losed] {cmd} *:folddoc* *:folddoclosed* | |
| 468 Execute {cmd} on all lines that are in a closed fold. | |
| 469 Otherwise like ":folddoopen". | |
| 470 | |
| 471 ============================================================================== | |
| 472 3. Fold options *fold-options* | |
| 473 | |
| 474 COLORS *fold-colors* | |
| 475 | |
| 476 The colors of a closed fold are set with the Folded group |hl-Folded|. The | |
| 477 colors of the fold column are set with the FoldColumn group |hl-FoldColumn|. | |
| 478 Example to set the colors: > | |
| 479 | |
| 480 :highlight Folded guibg=grey guifg=blue | |
| 481 :highlight FoldColumn guibg=darkgrey guifg=white | |
| 482 | |
| 483 | |
| 484 FOLDLEVEL *fold-foldlevel* | |
| 485 | |
| 486 'foldlevel' is a number option: The higher the more folded regions are open. | |
| 487 When 'foldlevel' is 0, all folds are closed. | |
| 42 | 488 When 'foldlevel' is positive, some folds are closed. |
| 7 | 489 When 'foldlevel' is very high, all folds are open. |
| 490 'foldlevel' is applied when it is changed. After that manually folds can be | |
| 491 opened and closed. | |
| 492 When increased, folds above the new level are opened. No manually opened | |
| 493 folds will be closed. | |
| 494 When decreased, folds above the new level are closed. No manually closed | |
| 495 folds will be opened. | |
| 496 | |
| 497 | |
| 498 FOLDTEXT *fold-foldtext* | |
| 499 | |
| 500 'foldtext' is a string option that specifies an expression. This expression | |
| 501 is evaluated to obtain the text displayed for a closed fold. Example: > | |
| 502 | |
| 503 :set foldtext=v:folddashes.substitute(getline(v:foldstart),'/\\*\\\|\\*/\\\|{{{\\d\\=','','g') | |
| 504 | |
| 505 This shows the first line of the fold, with "/*", "*/" and "{{{" removed. | |
| 506 Note the use of backslashes to avoid some characters to be interpreted by the | |
| 30634 | 507 ":set" command. It is much simpler to define a function and call it: > |
| 7 | 508 |
| 509 :set foldtext=MyFoldText() | |
| 510 :function MyFoldText() | |
| 511 : let line = getline(v:foldstart) | |
| 512 : let sub = substitute(line, '/\*\|\*/\|{{{\d\=', '', 'g') | |
| 27903 | 513 : return v:folddashes .. sub |
| 7 | 514 :endfunction |
| 515 | |
| 30634 | 516 The advantage of using a function call without arguments is that it is faster, |
| 517 see |expr-option-function|. | |
| 518 | |
| 7 | 519 Evaluating 'foldtext' is done in the |sandbox|. The current window is set to |
| 27321 | 520 the window that displays the line. The context is set to the script where the |
| 521 option was last set. | |
| 522 | |
| 523 Errors are ignored. For debugging set the 'debug' option to "throw". | |
| 7 | 524 |
| 525 The default value is |foldtext()|. This returns a reasonable text for most | |
| 526 types of folding. If you don't like it, you can specify your own 'foldtext' | |
| 527 expression. It can use these special Vim variables: | |
| 528 v:foldstart line number of first line in the fold | |
| 529 v:foldend line number of last line in the fold | |
| 530 v:folddashes a string that contains dashes to represent the | |
| 531 foldlevel. | |
| 532 v:foldlevel the foldlevel of the fold | |
| 533 | |
| 534 In the result a TAB is replaced with a space and unprintable characters are | |
| 535 made into printable characters. | |
| 536 | |
| 537 The resulting line is truncated to fit in the window, it never wraps. | |
| 538 When there is room after the text, it is filled with the character specified | |
| 539 by 'fillchars'. | |
| 540 | |
|
26759
31c23760d590
patch 8.2.3908: cannot use a script-local function for 'foldtext'
Bram Moolenaar <Bram@vim.org>
parents:
26743
diff
changeset
|
541 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
|
542 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
|
543 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
|
544 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
|
545 < |
| 7 | 546 Note that backslashes need to be used for characters that the ":set" command |
| 547 handles differently: Space, backslash and double-quote. |option-backslash| | |
| 548 | |
| 549 | |
| 550 FOLDCOLUMN *fold-foldcolumn* | |
| 551 | |
| 552 'foldcolumn' is a number, which sets the width for a column on the side of the | |
| 553 window to indicate folds. When it is zero, there is no foldcolumn. A normal | |
| 519 | 554 value is 4 or 5. The minimal useful value is 2, although 1 still provides |
| 555 some information. The maximum is 12. | |
| 7 | 556 |
| 557 An open fold is indicated with a column that has a '-' at the top and '|' | |
| 558 characters below it. This column stops where the open fold stops. When folds | |
| 559 nest, the nested fold is one character right of the fold it's contained in. | |
| 560 | |
| 561 A closed fold is indicated with a '+'. | |
| 562 | |
| 25402 | 563 These characters can be changed with the 'fillchars' option. |
| 564 | |
| 7 | 565 Where the fold column is too narrow to display all nested folds, digits are |
| 566 shown to indicate the nesting level. | |
| 567 | |
| 568 The mouse can also be used to open and close folds by clicking in the | |
| 569 fold column: | |
| 570 - Click on a '+' to open the closed fold at this row. | |
| 571 - Click on any other non-blank character to close the open fold at this row. | |
| 572 | |
| 573 | |
| 574 OTHER OPTIONS | |
| 575 | |
| 576 'foldenable' 'fen': Open all folds while not set. | |
| 577 'foldexpr' 'fde': Expression used for "expr" folding. | |
| 578 'foldignore' 'fdi': Characters used for "indent" folding. | |
| 579 'foldmarker' 'fmr': Defined markers used for "marker" folding. | |
| 580 'foldmethod' 'fdm': Name of the current folding method. | |
| 581 'foldminlines' 'fml': Minimum number of screen lines for a fold to be | |
| 582 displayed closed. | |
| 583 'foldnestmax' 'fdn': Maximum nesting for "indent" and "syntax" folding. | |
| 584 'foldopen' 'fdo': Which kinds of commands open closed folds. | |
| 585 'foldclose' 'fcl': When the folds not under the cursor are closed. | |
| 586 | |
| 587 ============================================================================== | |
| 588 4. Behavior of folds *fold-behavior* | |
| 589 | |
| 590 When moving the cursor upwards or downwards and when scrolling, the cursor | |
| 591 will move to the first line of a sequence of folded lines. When the cursor is | |
| 592 already on a folded line, it moves to the next unfolded line or the next | |
| 593 closed fold. | |
| 594 | |
| 595 While the cursor is on folded lines, the cursor is always displayed in the | |
| 596 first column. The ruler does show the actual cursor position, but since the | |
| 597 line is folded, it cannot be displayed there. | |
| 598 | |
| 599 Many movement commands handle a sequence of folded lines like an empty line. | |
| 600 For example, the "w" command stops once in the first column. | |
| 601 | |
| 31383 | 602 When starting a search in a closed fold it will not find a match in the |
| 603 current fold. It's like a forward search always starts from the end of the | |
| 604 closed fold, while a backwards search starts from the start of the closed | |
| 605 fold. | |
| 606 | |
| 7 | 607 When in Insert mode, the cursor line is never folded. That allows you to see |
| 608 what you type! | |
| 609 | |
| 610 When using an operator, a closed fold is included as a whole. Thus "dl" | |
| 611 deletes the whole closed fold under the cursor. | |
| 612 | |
|
7465
71e2aca45b81
commit https://github.com/vim/vim/commit/a3306958dcb9aadff1e1e8521d908d86b10ac99a
Christian Brabandt <cb@256bit.org>
parents:
7272
diff
changeset
|
613 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
|
614 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
|
615 fold. Thus this command: > |
| 7 | 616 :s/foo/bar/g |
| 617 when used with the cursor on a closed fold, will replace "foo" with "bar" in | |
| 618 all lines of the fold. | |
| 619 This does not happen for |:folddoopen| and |:folddoclosed|. | |
| 620 | |
| 621 When editing a buffer that has been edited before, the last used folding | |
| 622 settings are used again. For manual folding the defined folds are restored. | |
| 623 For all folding methods the manually opened and closed folds are restored. | |
| 624 If this buffer has been edited in this window, the values from back then are | |
| 625 used. Otherwise the values from the window where the buffer was edited last | |
| 626 are used. | |
| 627 | |
| 628 ============================================================================== | |
| 14421 | 629 vim:tw=78:ts=8:noet:ft=help:norl: |