Mercurial > vim
annotate runtime/doc/usr_28.txt @ 2320:966a5609669e vim73
Added Lua interfae. (Luis Carvalho)
| author | Bram Moolenaar <bram@vim.org> |
|---|---|
| date | Wed, 14 Jul 2010 23:23:17 +0200 |
| parents | 7e1bd501306d |
| children | 12b829477c60 |
| rev | line source |
|---|---|
|
2154
7c8c7c95a865
First step in the Vim 7.3 branch. Changed version numbers.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1 *usr_28.txt* For Vim version 7.3a. 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 | |
|
2283
7e1bd501306d
Mainly documentation updates.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
392 All these possibilities make you wonder which method you should choose. |
| 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: |