|
1702
|
1 *usr_28.txt* For Vim version 7.2. Last change: 2008 Jun 14
|
|
7
|
2
|
|
|
3 VIM USER MANUAL - by Bram Moolenaar
|
|
|
4
|
|
|
5 Folding
|
|
|
6
|
|
|
7
|
|
|
8 Structured text can be separated in sections. And sections in sub-sections.
|
|
|
9 Folding allows you to display a section as one line, providing an overview.
|
|
|
10 This chapter explains the different ways this can be done.
|
|
|
11
|
|
|
12 |28.1| What is folding?
|
|
|
13 |28.2| Manual folding
|
|
|
14 |28.3| Working with folds
|
|
|
15 |28.4| Saving and restoring folds
|
|
|
16 |28.5| Folding by indent
|
|
|
17 |28.6| Folding with markers
|
|
|
18 |28.7| Folding by syntax
|
|
|
19 |28.8| Folding by expression
|
|
|
20 |28.9| Folding unchanged lines
|
|
|
21 |28.10| Which fold method to use?
|
|
|
22
|
|
|
23 Next chapter: |usr_29.txt| Moving through programs
|
|
|
24 Previous chapter: |usr_27.txt| Search commands and patterns
|
|
|
25 Table of contents: |usr_toc.txt|
|
|
|
26
|
|
|
27 ==============================================================================
|
|
|
28 *28.1* What is folding?
|
|
|
29
|
|
|
30 Folding is used to show a range of lines in the buffer as a single line on the
|
|
|
31 screen. Like a piece of paper which is folded to make it shorter:
|
|
|
32
|
|
|
33 +------------------------+
|
|
|
34 | line 1 |
|
|
|
35 | line 2 |
|
|
|
36 | line 3 |
|
|
|
37 |_______________________ |
|
|
|
38 \ \
|
|
|
39 \________________________\
|
|
|
40 / folded lines /
|
|
|
41 /________________________/
|
|
|
42 | line 12 |
|
|
|
43 | line 13 |
|
|
|
44 | line 14 |
|
|
|
45 +------------------------+
|
|
|
46
|
|
|
47 The text is still in the buffer, unchanged. Only the way lines are displayed
|
|
|
48 is affected by folding.
|
|
|
49
|
|
|
50 The advantage of folding is that you can get a better overview of the
|
|
|
51 structure of text, by folding lines of a section and replacing it with a line
|
|
|
52 that indicates that there is a section.
|
|
|
53
|
|
|
54 ==============================================================================
|
|
|
55 *28.2* Manual folding
|
|
|
56
|
|
|
57 Try it out: Position the cursor in a paragraph and type: >
|
|
|
58
|
|
|
59 zfap
|
|
|
60
|
|
|
61 You will see that the paragraph is replaced by a highlighted line. You have
|
|
|
62 created a fold. |zf| is an operator and |ap| a text object selection. You
|
|
|
63 can use the |zf| operator with any movement command to create a fold for the
|
|
|
64 text that it moved over. |zf| also works in Visual mode.
|
|
|
65
|
|
|
66 To view the text again, open the fold by typing: >
|
|
|
67
|
|
|
68 zo
|
|
|
69
|
|
|
70 And you can close the fold again with: >
|
|
|
71
|
|
|
72 zc
|
|
|
73
|
|
|
74 All the folding commands start with "z". With some fantasy, this looks like a
|
|
|
75 folded piece of paper, seen from the side. The letter after the "z" has a
|
|
|
76 mnemonic meaning to make it easier to remember the commands:
|
|
|
77
|
|
|
78 zf F-old creation
|
|
|
79 zo O-pen a fold
|
|
|
80 zc C-lose a fold
|
|
|
81
|
|
|
82 Folds can be nested: A region of text that contains folds can be folded
|
|
|
83 again. For example, you can fold each paragraph in this section, and then
|
|
|
84 fold all the sections in this chapter. Try it out. You will notice that
|
|
|
85 opening the fold for the whole chapter will restore the nested folds as they
|
|
|
86 were, some may be open and some may be closed.
|
|
|
87
|
|
|
88 Suppose you have created several folds, and now want to view all the text.
|
|
|
89 You could go to each fold and type "zo". To do this faster, use this command: >
|
|
|
90
|
|
|
91 zr
|
|
|
92
|
|
|
93 This will R-educe the folding. The opposite is: >
|
|
|
94
|
|
|
95 zm
|
|
|
96
|
|
|
97 This folds M-ore. You can repeat "zr" and "zm" to open and close nested folds
|
|
|
98 of several levels.
|
|
|
99
|
|
|
100 If you have nested several levels deep, you can open all of them with: >
|
|
|
101
|
|
|
102 zR
|
|
|
103
|
|
|
104 This R-educes folds until there are none left. And you can close all folds
|
|
|
105 with: >
|
|
|
106
|
|
|
107 zM
|
|
|
108
|
|
|
109 This folds M-ore and M-ore.
|
|
|
110
|
|
|
111 You can quickly disable the folding with the |zn| command. Then |zN| brings
|
|
|
112 back the folding as it was. |zi| toggles between the two. This is a useful
|
|
|
113 way of working:
|
|
|
114 - create folds to get overview on your file
|
|
|
115 - move around to where you want to do your work
|
|
|
116 - do |zi| to look at the text and edit it
|
|
|
117 - do |zi| again to go back to moving around
|
|
|
118
|
|
|
119 More about manual folding in the reference manual: |fold-manual|
|
|
|
120
|
|
|
121 ==============================================================================
|
|
|
122 *28.3* Working with folds
|
|
|
123
|
|
|
124 When some folds are closed, movement commands like "j" and "k" move over a
|
|
|
125 fold like it was a single, empty line. This allows you to quickly move around
|
|
|
126 over folded text.
|
|
|
127
|
|
|
128 You can yank, delete and put folds as if it was a single line. This is very
|
|
|
129 useful if you want to reorder functions in a program. First make sure that
|
|
|
130 each fold contains a whole function (or a bit less) by selecting the right
|
|
|
131 'foldmethod'. Then delete the function with "dd", move the cursor and put it
|
|
|
132 with "p". If some lines of the function are above or below the fold, you can
|
|
|
133 use Visual selection:
|
|
|
134 - put the cursor on the first line to be moved
|
|
|
135 - hit "V" to start Visual mode
|
|
|
136 - put the cursor on the last line to be moved
|
|
|
137 - hit "d" to delete the selected lines.
|
|
|
138 - move the cursor to the new position and "p"ut the lines there.
|
|
|
139
|
|
|
140 It is sometimes difficult to see or remember where a fold is located, thus
|
|
|
141 where a |zo| command would actually work. To see the defined folds: >
|
|
|
142
|
|
|
143 :set foldcolumn=4
|
|
|
144
|
|
|
145 This will show a small column on the left of the window to indicate folds.
|
|
|
146 A "+" is shown for a closed fold. A "-" is shown at the start of each open
|
|
|
147 fold and "|" at following lines of the fold.
|
|
|
148
|
|
|
149 You can use the mouse to open a fold by clicking on the "+" in the foldcolumn.
|
|
|
150 Clicking on the "-" or a "|" below it will close an open fold.
|
|
|
151
|
|
|
152 To open all folds at the cursor line use |zO|.
|
|
|
153 To close all folds at the cursor line use |zC|.
|
|
|
154 To delete a fold at the cursor line use |zd|.
|
|
|
155 To delete all folds at the cursor line use |zD|.
|
|
|
156
|
|
|
157 When in Insert mode, the fold at the cursor line is never closed. That allows
|
|
|
158 you to see what you type!
|
|
|
159
|
|
|
160 Folds are opened automatically when jumping around or moving the cursor left
|
|
|
161 or right. For example, the "0" command opens the fold under the cursor
|
|
|
162 (if 'foldopen' contains "hor", which is the default). The 'foldopen' option
|
|
|
163 can be changed to open folds for specific commands. If you want the line
|
|
|
164 under the cursor always to be open, do this: >
|
|
|
165
|
|
|
166 :set foldopen=all
|
|
|
167
|
|
|
168 Warning: You won't be able to move onto a closed fold then. You might want to
|
|
|
169 use this only temporarily and then set it back to the default: >
|
|
|
170
|
|
|
171 :set foldopen&
|
|
|
172
|
|
|
173 You can make folds close automatically when you move out of it: >
|
|
|
174
|
|
|
175 :set foldclose=all
|
|
|
176
|
|
|
177 This will re-apply 'foldlevel' to all folds that don't contain the cursor.
|
|
|
178 You have to try it out if you like how this feels. Use |zm| to fold more and
|
|
|
179 |zr| to fold less (reduce folds).
|
|
|
180
|
|
|
181 The folding is local to the window. This allows you to open two windows on
|
|
|
182 the same buffer, one with folds and one without folds. Or one with all folds
|
|
|
183 closed and one with all folds open.
|
|
|
184
|
|
|
185 ==============================================================================
|
|
|
186 *28.4* Saving and restoring folds
|
|
|
187
|
|
|
188 When you abandon a file (starting to edit another one), the state of the folds
|
|
|
189 is lost. If you come back to the same file later, all manually opened and
|
|
|
190 closed folds are back to their default. When folds have been created
|
|
|
191 manually, all folds are gone! To save the folds use the |:mkview| command: >
|
|
|
192
|
|
|
193 :mkview
|
|
|
194
|
|
|
195 This will store the settings and other things that influence the view on the
|
|
|
196 file. You can change what is stored with the 'viewoptions' option.
|
|
|
197 When you come back to the same file later, you can load the view again: >
|
|
|
198
|
|
|
199 :loadview
|
|
|
200
|
|
|
201 You can store up to ten views on one file. For example, to save the current
|
|
|
202 setup as the third view and load the second view: >
|
|
|
203
|
|
|
204 :mkview 3
|
|
|
205 :loadview 2
|
|
|
206
|
|
|
207 Note that when you insert or delete lines the views might become invalid.
|
|
|
208 Also check out the 'viewdir' option, which specifies where the views are
|
|
|
209 stored. You might want to delete old views now and then.
|
|
|
210
|
|
|
211 ==============================================================================
|
|
|
212 *28.5* Folding by indent
|
|
|
213
|
|
|
214 Defining folds with |zf| is a lot of work. If your text is structured by
|
|
|
215 giving lower level items a larger indent, you can use the indent folding
|
|
|
216 method. This will create folds for every sequence of lines with the same
|
|
|
217 indent. Lines with a larger indent will become nested folds. This works well
|
|
|
218 with many programming languages.
|
|
|
219
|
|
|
220 Try this by setting the 'foldmethod' option: >
|
|
|
221
|
|
|
222 :set foldmethod=indent
|
|
|
223
|
|
|
224 Then you can use the |zm| and |zr| commands to fold more and reduce folding.
|
|
|
225 It's easy to see on this example text:
|
|
|
226
|
|
|
227 This line is not indented
|
|
|
228 This line is indented once
|
|
|
229 This line is indented twice
|
|
|
230 This line is indented twice
|
|
|
231 This line is indented once
|
|
|
232 This line is not indented
|
|
|
233 This line is indented once
|
|
|
234 This line is indented once
|
|
|
235
|
|
|
236 Note that the relation between the amount of indent and the fold depth depends
|
|
|
237 on the 'shiftwidth' option. Each 'shiftwidth' worth of indent adds one to the
|
|
|
238 depth of the fold. This is called a fold level.
|
|
|
239
|
|
|
240 When you use the |zr| and |zm| commands you actually increase or decrease the
|
|
|
241 'foldlevel' option. You could also set it directly: >
|
|
|
242
|
|
|
243 :set foldlevel=3
|
|
|
244
|
|
|
245 This means that all folds with three times a 'shiftwidth' indent or more will
|
|
|
246 be closed. The lower the foldlevel, the more folds will be closed. When
|
|
|
247 'foldlevel' is zero, all folds are closed. |zM| does set 'foldlevel' to zero.
|
|
|
248 The opposite command |zR| sets 'foldlevel' to the deepest fold level that is
|
|
|
249 present in the file.
|
|
|
250
|
|
|
251 Thus there are two ways to open and close the folds:
|
|
|
252 (A) By setting the fold level.
|
|
|
253 This gives a very quick way of "zooming out" to view the structure of the
|
|
|
254 text, move the cursor, and "zoom in" on the text again.
|
|
|
255
|
|
|
256 (B) By using |zo| and |zc| commands to open or close specific folds.
|
|
|
257 This allows opening only those folds that you want to be open, while other
|
|
|
258 folds remain closed.
|
|
|
259
|
|
|
260 This can be combined: You can first close most folds by using |zm| a few times
|
|
|
261 and then open a specific fold with |zo|. Or open all folds with |zR| and
|
|
|
262 then close specific folds with |zc|.
|
|
|
263
|
|
|
264 But you cannot manually define folds when 'foldmethod' is "indent", as that
|
|
|
265 would conflict with the relation between the indent and the fold level.
|
|
|
266
|
|
|
267 More about folding by indent in the reference manual: |fold-indent|
|
|
|
268
|
|
|
269 ==============================================================================
|
|
|
270 *28.6* Folding with markers
|
|
|
271
|
|
|
272 Markers in the text are used to specify the start and end of a fold region.
|
|
|
273 This gives precise control over which lines are included in a fold. The
|
|
|
274 disadvantage is that the text needs to be modified.
|
|
|
275
|
|
|
276 Try it: >
|
|
|
277
|
|
|
278 :set foldmethod=marker
|
|
|
279
|
|
|
280 Example text, as it could appear in a C program:
|
|
|
281
|
|
|
282 /* foobar () {{{ */
|
|
|
283 int foobar()
|
|
|
284 {
|
|
|
285 /* return a value {{{ */
|
|
|
286 return 42;
|
|
|
287 /* }}} */
|
|
|
288 }
|
|
|
289 /* }}} */
|
|
|
290
|
|
|
291 Notice that the folded line will display the text before the marker. This is
|
|
|
292 very useful to tell what the fold contains.
|
|
|
293
|
|
|
294 It's quite annoying when the markers don't pair up correctly after moving some
|
|
|
295 lines around. This can be avoided by using numbered markers. Example:
|
|
|
296
|
|
|
297 /* global variables {{{1 */
|
|
|
298 int varA, varB;
|
|
|
299
|
|
|
300 /* functions {{{1 */
|
|
|
301 /* funcA() {{{2 */
|
|
|
302 void funcA() {}
|
|
|
303
|
|
|
304 /* funcB() {{{2 */
|
|
|
305 void funcB() {}
|
|
|
306 /* }}}1 */
|
|
|
307
|
|
|
308 At every numbered marker a fold at the specified level begins. This will make
|
|
|
309 any fold at a higher level stop here. You can just use numbered start markers
|
|
|
310 to define all folds. Only when you want to explicitly stop a fold before
|
|
|
311 another starts you need to add an end marker.
|
|
|
312
|
|
|
313 More about folding with markers in the reference manual: |fold-marker|
|
|
|
314
|
|
|
315 ==============================================================================
|
|
|
316 *28.7* Folding by syntax
|
|
|
317
|
|
|
318 For each language Vim uses a different syntax file. This defines the colors
|
|
|
319 for various items in the file. If you are reading this in Vim, in a terminal
|
|
|
320 that supports colors, the colors you see are made with the "help" syntax file.
|
|
|
321 In the syntax files it is possible to add syntax items that have the "fold"
|
|
|
322 argument. These define a fold region. This requires writing a syntax file
|
|
|
323 and adding these items in it. That's not so easy to do. But once it's done,
|
|
|
324 all folding happens automatically.
|
|
|
325 Here we'll assume you are using an existing syntax file. Then there is
|
|
|
326 nothing more to explain. You can open and close folds as explained above.
|
|
|
327 The folds will be created and deleted automatically when you edit the file.
|
|
|
328
|
|
|
329 More about folding by syntax in the reference manual: |fold-syntax|
|
|
|
330
|
|
|
331 ==============================================================================
|
|
|
332 *28.8* Folding by expression
|
|
|
333
|
|
|
334 This is similar to folding by indent, but instead of using the indent of a
|
|
|
335 line a user function is called to compute the fold level of a line. You can
|
|
|
336 use this for text where something in the text indicates which lines belong
|
|
|
337 together. An example is an e-mail message where the quoted text is indicated
|
|
|
338 by a ">" before the line. To fold these quotes use this: >
|
|
|
339
|
|
|
340 :set foldmethod=expr
|
|
|
341 :set foldexpr=strlen(substitute(substitute(getline(v:lnum),'\\s','',\"g\"),'[^>].*','',''))
|
|
|
342
|
|
|
343 You can try it out on this text:
|
|
|
344
|
|
|
345 > quoted text he wrote
|
|
|
346 > quoted text he wrote
|
|
|
347 > > double quoted text I wrote
|
|
|
348 > > double quoted text I wrote
|
|
|
349
|
|
|
350 Explanation for the 'foldexpr' used in the example (inside out):
|
|
|
351 getline(v:lnum) gets the current line
|
|
|
352 substitute(...,'\\s','','g') removes all white space from the line
|
|
237
|
353 substitute(...,'[^>].*','','') removes everything after leading '>'s
|
|
7
|
354 strlen(...) counts the length of the string, which
|
|
|
355 is the number of '>'s found
|
|
|
356
|
|
|
357 Note that a backslash must be inserted before every space, double quote and
|
|
|
358 backslash for the ":set" command. If this confuses you, do >
|
|
|
359
|
|
|
360 :set foldexpr
|
|
|
361
|
|
|
362 to check the actual resulting value. To correct a complicated expression, use
|
|
|
363 the command-line completion: >
|
|
|
364
|
|
|
365 :set foldexpr=<Tab>
|
|
|
366
|
|
|
367 Where <Tab> is a real Tab. Vim will fill in the previous value, which you can
|
|
|
368 then edit.
|
|
|
369
|
|
|
370 When the expression gets more complicated you should put it in a function and
|
|
|
371 set 'foldexpr' to call that function.
|
|
|
372
|
|
|
373 More about folding by expression in the reference manual: |fold-expr|
|
|
|
374
|
|
|
375 ==============================================================================
|
|
|
376 *28.9* Folding unchanged lines
|
|
|
377
|
|
|
378 This is useful when you set the 'diff' option in the same window. The
|
|
|
379 |vimdiff| command does this for you. Example: >
|
|
|
380
|
|
1622
|
381 :setlocal diff foldmethod=diff scrollbind nowrap foldlevel=1
|
|
7
|
382
|
|
|
383 Do this in every window that shows a different version of the same file. You
|
|
|
384 will clearly see the differences between the files, while the text that didn't
|
|
|
385 change is folded.
|
|
|
386
|
|
|
387 For more details see |fold-diff|.
|
|
|
388
|
|
|
389 ==============================================================================
|
|
|
390 *28.10* Which fold method to use?
|
|
|
391
|
|
1622
|
392 All these possibilities make you wonder which method you should chose.
|
|
7
|
393 Unfortunately, there is no golden rule. Here are some hints.
|
|
|
394
|
|
|
395 If there is a syntax file with folding for the language you are editing, that
|
|
|
396 is probably the best choice. If there isn't one, you might try to write it.
|
|
|
397 This requires a good knowledge of search patterns. It's not easy, but when
|
|
|
398 it's working you will not have to define folds manually.
|
|
|
399
|
|
|
400 Typing commands to manually fold regions can be used for unstructured text.
|
|
|
401 Then use the |:mkview| command to save and restore your folds.
|
|
|
402
|
|
|
403 The marker method requires you to change the file. If you are sharing the
|
|
|
404 files with other people or you have to meet company standards, you might not
|
|
|
405 be allowed to add them.
|
|
|
406 The main advantage of markers is that you can put them exactly where you
|
|
|
407 want them. That avoids that a few lines are missed when you cut and paste
|
|
|
408 folds. And you can add a comment about what is contained in the fold.
|
|
|
409
|
|
|
410 Folding by indent is something that works in many files, but not always very
|
|
|
411 well. Use it when you can't use one of the other methods. However, it is
|
|
|
412 very useful for outlining. Then you specifically use one 'shiftwidth' for
|
|
|
413 each nesting level.
|
|
|
414
|
|
|
415 Folding with expressions can make folds in almost any structured text. It is
|
|
|
416 quite simple to specify, especially if the start and end of a fold can easily
|
|
|
417 be recognized.
|
|
|
418 If you use the "expr" method to define folds, but they are not exactly how
|
|
|
419 you want them, you could switch to the "manual" method. This will not remove
|
|
|
420 the defined folds. Then you can delete or add folds manually.
|
|
|
421
|
|
|
422 ==============================================================================
|
|
|
423
|
|
|
424 Next chapter: |usr_29.txt| Moving through programs
|
|
|
425
|
|
|
426 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:
|
