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