Mercurial > vim

comparison runtime/doc/fold.txt @ 7:3fc0f57ecb91 v7.0001

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