Wikia

Vim Tips Wiki

Changes: Folding

Edit

Back to page

(Change <tt> to <code>, perhaps also minor tweak.)
Line 18: Line 18:
 
To activate folding in your text, you will need to set the 'foldmethod' option.
 
To activate folding in your text, you will need to set the 'foldmethod' option.
   
The <tt>'foldmethod'</tt> option (abbreviated to <tt>'fdm'</tt>) is local to each window. It determines what kind of folding applies in the current window. Commonly used values are:
+
The <code>'foldmethod'</code> option (abbreviated to <code>'fdm'</code>) is local to each window. It determines what kind of folding applies in the current window. Commonly used values are:
*<tt>manual</tt> – folds must be defined by entering commands (such as {{help|prefix=no|zf}})
+
*<code>manual</code> – folds must be defined by entering commands (such as {{help|prefix=no|zf}})
*<tt>indent</tt> – groups of lines with the same indent form a fold
+
*<code>indent</code> – groups of lines with the same indent form a fold
*<tt>syntax</tt> – folds are defined by syntax highlighting
+
*<code>syntax</code> – folds are defined by syntax highlighting
*<tt>expr</tt> – folds are defined by a user-defined expression
+
*<code>expr</code> – folds are defined by a user-defined expression
   
In addition, <tt>'foldmethod'</tt> may have values:
+
In addition, <code>'foldmethod'</code> may have values:
*<tt>marker</tt> – special characters can be manually or automatically added to your text to flag the start and end of folds
+
*<code>marker</code> – special characters can be manually or automatically added to your text to flag the start and end of folds
*<tt>diff</tt> – used to fold unchanged text when viewing differences (automatically set in diff mode)
+
*<code>diff</code> – used to fold unchanged text when viewing differences (automatically set in diff mode)
   
 
===Manual folding===
 
===Manual folding===
Normally it is best to use an automatic folding method, but manual folding is simple and useful for dealing with small folds. It is easy to fold an arbitrary block from visual mode by pressing '<tt>v{motion}zf</tt>'. Alternatively, this can be used in normal mode, after <tt>zf'a</tt> for example will fold from the current line to wherever the mark a has been set, or <tt>zf3j</tt> will fold the next 3 lines. This allows you to see the section you've selected before you fold it. If you just want to enter a few folds in a program that uses braces around blocks (<tt>{...}</tt>), you can use the command <tt>va}zf</tt> to create a fold for the block containing the cursor. Use <tt>zd</tt> to delete a fold (no text is deleted; the fold at the cursor is removed). A quicker way to create a block is with <tt>zf{motion}</tt>, so the example fold mentioned earlier could also be typed <tt>zfa}</tt>.
+
Normally it is best to use an automatic folding method, but manual folding is simple and useful for dealing with small folds. It is easy to fold an arbitrary block from visual mode by pressing '<code>v{motion}zf</code>'. Alternatively, this can be used in normal mode, after <code>zf'a</code> for example will fold from the current line to wherever the mark a has been set, or <code>zf3j</code> will fold the next 3 lines. This allows you to see the section you've selected before you fold it. If you just want to enter a few folds in a program that uses braces around blocks (<code>{...}</code>), you can use the command <code>va}zf</code> to create a fold for the block containing the cursor. Use <code>zd</code> to delete a fold (no text is deleted; the fold at the cursor is removed). A quicker way to create a block is with <code>zf{motion}</code>, so the example fold mentioned earlier could also be typed <code>zfa}</code>.
   
 
===Indent folding===
 
===Indent folding===
Line 35: Line 35:
   
 
===Syntax folding===
 
===Syntax folding===
Try setting <tt>foldmethod=syntax</tt>. Many syntax files define folding based on the language syntax, although you may need to enable it by [[VimTip1534|setting syntax file options]]. If a specific syntax file doesn't define folding, you can [[Syntax folding of Vim scripts|define your own]].
+
Try setting <code>foldmethod=syntax</code>. Many syntax files define folding based on the language syntax, although you may need to enable it by [[VimTip1534|setting syntax file options]]. If a specific syntax file doesn't define folding, you can [[Syntax folding of Vim scripts|define your own]].
   
 
Note that this particular fold method especially may define too many folds for your liking. You can change this using the {{help|prefix=no|'foldnestmax'}} option, by setting it to a value low enough for your liking.
 
Note that this particular fold method especially may define too many folds for your liking. You can change this using the {{help|prefix=no|'foldnestmax'}} option, by setting it to a value low enough for your liking.
Line 48: Line 48:
 
</pre>
 
</pre>
   
The first autocommand sets <tt>'indent'</tt> as the fold method before a file is loaded, so that indent-based folds will be defined. The second one allows you to manually create folds while editing. It's executed after the modeline is read, so it won't change the fold method if the modeline set the fold method to something else like <tt>'marker'</tt> or <tt>'syntax'</tt>.
+
The first autocommand sets <code>'indent'</code> as the fold method before a file is loaded, so that indent-based folds will be defined. The second one allows you to manually create folds while editing. It's executed after the modeline is read, so it won't change the fold method if the modeline set the fold method to something else like <code>'marker'</code> or <code>'syntax'</code>.
   
 
===Folding by expression===
 
===Folding by expression===
Line 60: Line 60:
   
 
==Opening and closing folds==
 
==Opening and closing folds==
The command <tt>zc</tt> will close a fold (if the cursor is in an open fold), and <tt>zo</tt> will open a fold (if the cursor is in a closed fold). It's easier to just use <tt>za</tt> which will toggle the current fold (close it if it was open, or open it if it was closed).
+
The command <code>zc</code> will close a fold (if the cursor is in an open fold), and <code>zo</code> will open a fold (if the cursor is in a closed fold). It's easier to just use <code>za</code> which will toggle the current fold (close it if it was open, or open it if it was closed).
   
The commands <tt>zc</tt> (close), <tt>zo</tt> (open), and <tt>za</tt> (toggle) operate on one level of folding, at the cursor. The commands <tt>zC</tt>, <tt>zO</tt> and <tt>zA</tt> are similar, but operate on all folding levels (for example, the cursor line may be in an open fold, which is inside another open fold; typing <tt>zC</tt> would close all folds at the cursor).
+
The commands <code>zc</code> (close), <code>zo</code> (open), and <code>za</code> (toggle) operate on one level of folding, at the cursor. The commands <code>zC</code>, <code>zO</code> and <code>zA</code> are similar, but operate on all folding levels (for example, the cursor line may be in an open fold, which is inside another open fold; typing <code>zC</code> would close all folds at the cursor).
   
The command <tt>zr</tt> reduces folding by opening one more level of folds throughout the whole buffer (the cursor position is not relevant). Use <tt>zR</tt> to open all folds.
+
The command <code>zr</code> reduces folding by opening one more level of folds throughout the whole buffer (the cursor position is not relevant). Use <code>zR</code> to open all folds.
   
The command <tt>zm</tt> gives more folding by closing one more level of folds throughout the whole buffer. Use <tt>zM</tt> to close all folds.
+
The command <code>zm</code> gives more folding by closing one more level of folds throughout the whole buffer. Use <code>zM</code> to close all folds.
   
 
===Mappings to toggle folds===
 
===Mappings to toggle folds===
With the following in your [[vimrc]], you can toggle folds open/closed by pressing F9. In addition, if you have <tt>:set&nbsp;foldmethod=manual</tt>, you can visually select some lines, then press F9 to create a fold.
+
With the following in your [[vimrc]], you can toggle folds open/closed by pressing F9. In addition, if you have <code>:set&nbsp;foldmethod=manual</code>, you can visually select some lines, then press F9 to create a fold.
 
<pre>
 
<pre>
 
inoremap <F9> <C-O>za
 
inoremap <F9> <C-O>za
Line 77: Line 77:
 
</pre>
 
</pre>
   
Here is an alternative procedure: In normal mode, press Space to toggle the current fold open/closed. However, if the cursor is not in a fold, move to the right (the default behavior). In addition, with the <tt>manual</tt> fold method, you can create a fold by visually selecting some lines, then pressing Space.
+
Here is an alternative procedure: In normal mode, press Space to toggle the current fold open/closed. However, if the cursor is not in a fold, move to the right (the default behavior). In addition, with the <code>manual</code> fold method, you can create a fold by visually selecting some lines, then pressing Space.
 
<pre>
 
<pre>
 
nnoremap <silent> <Space> @=(foldlevel('.')?'za':"\<Space>")<CR>
 
nnoremap <silent> <Space> @=(foldlevel('.')?'za':"\<Space>")<CR>
Line 83: Line 83:
 
</pre>
 
</pre>
   
In the first mapping for Space, <tt>@=</tt> refers to the expression register ({{help|1=@=}}). The following expression is evaluated when Enter is pressed (<tt><CR></tt>). The value of <tt>foldlevel('.')</tt> is determined (the fold level at the current line, or zero if the current line is not in a fold). If the result is nonzero (true), the result is <tt>'za'</tt> (toggle fold); otherwise it is <tt>"\<Space>"</tt>, which evaluates back to the default behaviour of the <Space> key (move forward by one character). {{help|expr1}}
+
In the first mapping for Space, <code>@=</code> refers to the expression register ({{help|1=@=}}). The following expression is evaluated when Enter is pressed (<code><CR></code>). The value of <code>foldlevel('.')</code> is determined (the fold level at the current line, or zero if the current line is not in a fold). If the result is nonzero (true), the result is <code>'za'</code> (toggle fold); otherwise it is <code>"\<Space>"</code>, which evaluates back to the default behaviour of the <Space> key (move forward by one character). {{help|expr1}}
   
 
==Saving folds before closing the vim==
 
==Saving folds before closing the vim==
Vim provide a good mechanism called <tt>view</tt>. You can use it to saving a fold. See [[VimTip991|Make views automatic]]. You may also want to use plugin {{script|id=4021|text=restore_view.vim}}.
+
Vim provide a good mechanism called <code>view</code>. You can use it to saving a fold. See [[VimTip991|Make views automatic]]. You may also want to use plugin {{script|id=4021|text=restore_view.vim}}.
   
 
==Commands over folds==
 
==Commands over folds==
Folds can be created using one of the methods described above. Then, all the folds can be closed using <tt>zM</tt>. Now, commands can be executed on each line that is folded, using <tt>:folddoc <command></tt>. Reopen the folds using <tt>zR</tt> to see the results.
+
Folds can be created using one of the methods described above. Then, all the folds can be closed using <code>zM</code>. Now, commands can be executed on each line that is folded, using <code>:folddoc <command></code>. Reopen the folds using <code>zR</code> to see the results.
 
::Todo: Explain how a command stored in a register can be executed this way. Ctrl-r, followed by the register name does not appear to execute the set of keystrokes for each line that is folded?
 
::Todo: Explain how a command stored in a register can be executed this way. Ctrl-r, followed by the register name does not appear to execute the set of keystrokes for each line that is folded?
   
 
==See also==
 
==See also==
* [[Syntax folding of Vim scripts]] discusses folding for files in the [[:Category:VimL|Vim script]] language
+
*[[Syntax folding of Vim scripts]] discusses folding for files in the [[:Category:VimL|Vim script]] language
* [[Auto-fold Perl subs]] discusses folding for the [[:Category:Perl|Perl]] language
+
*[[Auto-fold Perl subs]] discusses folding for the [[:Category:Perl|Perl]] language
* [[Dosini_files#Folding_sections|Dosini files]] includes information about folding in DOS-style <tt>.ini</tt> files
+
*[[Dosini_files#Folding_sections|Dosini files]] includes information about folding in DOS-style <code>.ini</code> files
   
 
==References==
 
==References==

Revision as of 07:48, July 11, 2012

Tip 108 Printable Monobook Previous Next

created 2001 · complexity basic · version 6.0


It is convenient to temporarily fold away (hide) parts of your file, leaving only an outline of the major parts visible. This tip presents an overview of using folding.

Many programming languages have a syntax file that supports folding. Typically, each function is regarded as a fold that can be opened or closed. With all folds closed, you see only the first line of each function for an overview of the program.

Folding methods

To activate folding in your text, you will need to set the 'foldmethod' option.

The 'foldmethod' option (abbreviated to 'fdm') is local to each window. It determines what kind of folding applies in the current window. Commonly used values are:

  • manual – folds must be defined by entering commands (such as zf)
  • indent – groups of lines with the same indent form a fold
  • syntax – folds are defined by syntax highlighting
  • expr – folds are defined by a user-defined expression

In addition, 'foldmethod' may have values:

  • marker – special characters can be manually or automatically added to your text to flag the start and end of folds
  • diff – used to fold unchanged text when viewing differences (automatically set in diff mode)

Manual folding

Normally it is best to use an automatic folding method, but manual folding is simple and useful for dealing with small folds. It is easy to fold an arbitrary block from visual mode by pressing 'v{motion}zf'. Alternatively, this can be used in normal mode, after zf'a for example will fold from the current line to wherever the mark a has been set, or zf3j will fold the next 3 lines. This allows you to see the section you've selected before you fold it. If you just want to enter a few folds in a program that uses braces around blocks ({...}), you can use the command va}zf to create a fold for the block containing the cursor. Use zd to delete a fold (no text is deleted; the fold at the cursor is removed). A quicker way to create a block is with zf{motion}, so the example fold mentioned earlier could also be typed zfa}.

Indent folding

In the vimrc, set the foldcolumn and foldlevel to the depth of folds you want displayed. A sidebar will appear showing which lines in the file can be folded, or are already folded.

Syntax folding

Try setting foldmethod=syntax. Many syntax files define folding based on the language syntax, although you may need to enable it by setting syntax file options. If a specific syntax file doesn't define folding, you can define your own.

Note that this particular fold method especially may define too many folds for your liking. You can change this using the 'foldnestmax' option, by setting it to a value low enough for your liking.

Indent folding with manual folds

If you like the convenience of having Vim define folds automatically by indent level, but would also like to create folds manually, you can get both by putting this in your vimrc:

augroup vimrc
  au BufReadPre * setlocal foldmethod=indent
  au BufWinEnter * if &fdm == 'indent' | setlocal foldmethod=manual | endif
augroup END

The first autocommand sets 'indent' as the fold method before a file is loaded, so that indent-based folds will be defined. The second one allows you to manually create folds while editing. It's executed after the modeline is read, so it won't change the fold method if the modeline set the fold method to something else like 'marker' or 'syntax'.

Folding by expression

This is the most complicated, but also the most powerful fold method. You can use it to fold in pretty much any way you desire. For example, you could fold away text not matching a regular expression. See :help 'foldexpr' for details.

Folding with markers

Setting foldmethod to "marker" is similar to manual folding, because you can use zf and zd to add/remove folds, and all folds are defined manually. However, it works by adding special markers to your buffer text so that the same folds can be loaded by anyone opening the file in Vim. This method is mostly useful when the other options don't give satisfactory results, either because a syntax file does not define folding, you want to break up a file into logical portions instead of syntactical constructs, or you are folding plain text in some way.

Diff folding

This foldmethod should never be set manually without very good reason. It is the default fold method when using Vim in diff mode. Simply running any of the commands to put Vim in diff mode will set this option for you. It works by folding away lines that do not differ between the buffers in the diff, so that you can focus on the lines with differences. Note that you can tweak the number of lines to leave unfolded, using the 'diffopt' option.

Opening and closing folds

The command zc will close a fold (if the cursor is in an open fold), and zo will open a fold (if the cursor is in a closed fold). It's easier to just use za which will toggle the current fold (close it if it was open, or open it if it was closed).

The commands zc (close), zo (open), and za (toggle) operate on one level of folding, at the cursor. The commands zC, zO and zA are similar, but operate on all folding levels (for example, the cursor line may be in an open fold, which is inside another open fold; typing zC would close all folds at the cursor).

The command zr reduces folding by opening one more level of folds throughout the whole buffer (the cursor position is not relevant). Use zR to open all folds.

The command zm gives more folding by closing one more level of folds throughout the whole buffer. Use zM to close all folds.

Mappings to toggle folds

With the following in your vimrc, you can toggle folds open/closed by pressing F9. In addition, if you have :set foldmethod=manual, you can visually select some lines, then press F9 to create a fold.

inoremap <F9> <C-O>za
nnoremap <F9> za
onoremap <F9> <C-C>za
vnoremap <F9> zf

Here is an alternative procedure: In normal mode, press Space to toggle the current fold open/closed. However, if the cursor is not in a fold, move to the right (the default behavior). In addition, with the manual fold method, you can create a fold by visually selecting some lines, then pressing Space.

nnoremap <silent> <Space> @=(foldlevel('.')?'za':"\<Space>")<CR>
vnoremap <Space> zf

In the first mapping for Space, @= refers to the expression register (:help @=). The following expression is evaluated when Enter is pressed (<CR>). The value of foldlevel('.') is determined (the fold level at the current line, or zero if the current line is not in a fold). If the result is nonzero (true), the result is 'za' (toggle fold); otherwise it is "\<Space>", which evaluates back to the default behaviour of the <Space> key (move forward by one character). :help expr1

Saving folds before closing the vim

Vim provide a good mechanism called view. You can use it to saving a fold. See Make views automatic. You may also want to use plugin restore_view.vim.

Commands over folds

Folds can be created using one of the methods described above. Then, all the folds can be closed using zM. Now, commands can be executed on each line that is folded, using :folddoc <command>. Reopen the folds using zR to see the results.

Todo: Explain how a command stored in a register can be executed this way. Ctrl-r, followed by the register name does not appear to execute the set of keystrokes for each line that is folded?

See also

References

Comments

Around Wikia's network

Random Wiki