diff options
Diffstat (limited to 'runtime/doc/fold.txt')
| -rw-r--r-- | runtime/doc/fold.txt | 628 |
1 files changed, 628 insertions, 0 deletions
diff --git a/runtime/doc/fold.txt b/runtime/doc/fold.txt new file mode 100644 index 0000000..bb1dcb6 --- /dev/null +++ b/runtime/doc/fold.txt @@ -0,0 +1,628 @@ +*fold.txt* For Vim version 9.0. Last change: 2023 Jan 29 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Folding *Folding* *folding* *folds* + +You can find an introduction on folding in chapter 28 of the user manual. +|usr_28.txt| + +1. Fold methods |fold-methods| +2. Fold commands |fold-commands| +3. Fold options |fold-options| +4. Behavior of folds |fold-behavior| + +{not available when compiled without the |+folding| feature} + +============================================================================== +1. Fold methods *fold-methods* + +The folding method can be set with the 'foldmethod' option. + +When setting 'foldmethod' to a value other than "manual", all folds are +deleted and new ones created. Switching to the "manual" method doesn't remove +the existing folds. This can be used to first define the folds automatically +and then change them manually. + +There are six methods to select folds: + manual manually define folds + indent more indent means a higher fold level + expr specify an expression to define folds + syntax folds defined by syntax highlighting + diff folds for unchanged text + marker folds defined by markers in the text + + +MANUAL *fold-manual* + +Use commands to manually define the fold regions. This can also be used by a +script that parses text to find folds. + +The level of a fold is only defined by its nesting. To increase the fold +level of a fold for a range of lines, define a fold inside it that has the +same lines. + +The manual folds are lost when you abandon the file. To save the folds use +the |:mkview| command. The view can be restored later with |:loadview|. + + +INDENT *fold-indent* + +The folds are automatically defined by the indent of the lines. + +The foldlevel is computed from the indent of the line, divided by the +'shiftwidth' (rounded down). A sequence of lines with the same or higher fold +level form a fold, with the lines with a higher level forming a nested fold. + +The nesting of folds is limited with 'foldnestmax'. + +Some lines are ignored and get the fold level of the line above or below it, +whichever is lower. These are empty or white lines and lines starting +with a character in 'foldignore'. White space is skipped before checking for +characters in 'foldignore'. For C use "#" to ignore preprocessor lines. + +When you want to ignore lines in another way, use the "expr" method. The +|indent()| function can be used in 'foldexpr' to get the indent of a line. + + +EXPR *fold-expr* + +The folds are automatically defined by their foldlevel, like with the "indent" +method. The value of the 'foldexpr' option is evaluated to get the foldlevel +of a line. Examples: +This will create a fold for all consecutive lines that start with a tab: > + :set foldexpr=getline(v:lnum)[0]==\"\\t\" +This will make a fold out of paragraphs separated by blank lines: > + :set foldexpr=getline(v:lnum)=~'^\\s*$'&&getline(v:lnum+1)=~'\\S'?'<1':1 +This does the same: > + :set foldexpr=getline(v:lnum-1)=~'^\\s*$'&&getline(v:lnum)=~'\\S'?'>1':1 + +Note that backslashes must be used to escape characters that ":set" handles +differently (space, backslash, double quote, etc., see |option-backslash|). + +The most efficient is to call a compiled function without arguments: > + :set foldexpr=MyFoldLevel() +The function must use v:lnum. See |expr-option-function|. + +These are the conditions with which the expression is evaluated: +- The current buffer and window are set for the line. +- The variable "v:lnum" is set to the line number. +- The result is used for the fold level in this way: + value meaning ~ + 0 the line is not in a fold + 1, 2, .. the line is in a fold with this level + -1 the fold level is undefined, use the fold level of a + line before or after this line, whichever is the + lowest. + "=" use fold level from the previous line + "a1", "a2", .. add one, two, .. to the fold level of the previous + line, use the result for the current line + "s1", "s2", .. subtract one, two, .. from the fold level of the + previous line, use the result for the next line + "<1", "<2", .. a fold with this level ends at this line + ">1", ">2", .. a fold with this level starts at this line + +It is not required to mark the start (end) of a fold with ">1" ("<1"), a fold +will also start (end) when the fold level is higher (lower) than the fold +level of the previous line. + +There must be no side effects from the expression. The text in the buffer, +cursor position, the search patterns, options etc. must not be changed. +You can change and restore them if you are careful. + +If there is some error in the expression, or the resulting value isn't +recognized, there is no error message and the fold level will be zero. +For debugging the 'debug' option can be set to "msg", the error messages will +be visible then. + +Note: Since the expression has to be evaluated for every line, this fold +method can be very slow! + +Try to avoid the "=", "a" and "s" return values, since Vim often has to search +backwards for a line for which the fold level is defined. This can be slow. + +If the 'foldexpr' expression starts with s: or |<SID>|, then it is replaced +with the script ID (|local-function|). Examples: > + set foldexpr=s:MyFoldExpr() + set foldexpr=<SID>SomeFoldExpr() +< +An example of using "a1" and "s1": For a multi-line C comment, a line +containing "/*" would return "a1" to start a fold, and a line containing "*/" +would return "s1" to end the fold after that line: > + if match(thisline, '/\*') >= 0 + return 'a1' + elseif match(thisline, '\*/') >= 0 + return 's1' + else + return '=' + endif +However, this won't work for single line comments, strings, etc. + +|foldlevel()| can be useful to compute a fold level relative to a previous +fold level. But note that foldlevel() may return -1 if the level is not known +yet. And it returns the level at the start of the line, while a fold might +end in that line. + +It may happen that folds are not updated properly. You can use |zx| or |zX| +to force updating folds. + + +SYNTAX *fold-syntax* + +A fold is defined by syntax items that have the "fold" argument. |:syn-fold| + +The fold level is defined by nesting folds. The nesting of folds is limited +with 'foldnestmax'. + +Be careful to specify proper syntax syncing. If this is not done right, folds +may differ from the displayed highlighting. This is especially relevant when +using patterns that match more than one line. In case of doubt, try using +brute-force syncing: > + :syn sync fromstart + + +DIFF *fold-diff* + +The folds are automatically defined for text that is not part of a change or +close to a change. + +This method only works properly when the 'diff' option is set for the current +window and changes are being displayed. Otherwise the whole buffer will be +one big fold. + +The 'diffopt' option can be used to specify the context. That is, the number +of lines between the fold and a change that are not included in the fold. For +example, to use a context of 8 lines: > + :set diffopt=filler,context:8 +The default context is six lines. + +When 'scrollbind' is also set, Vim will attempt to keep the same folds open in +other diff windows, so that the same text is visible. + + +MARKER *fold-marker* + +Markers in the text tell where folds start and end. This allows you to +precisely specify the folds. This will allow deleting and putting a fold, +without the risk of including the wrong lines. The 'foldtext' option is +normally set such that the text before the marker shows up in the folded line. +This makes it possible to give a name to the fold. + +Markers can have a level included, or can use matching pairs. Including a +level is easier, you don't have to add end markers and avoid problems with +non-matching marker pairs. Example: > + /* global variables {{{1 */ + int varA, varB; + + /* functions {{{1 */ + /* funcA() {{{2 */ + void funcA() {} + + /* funcB() {{{2 */ + void funcB() {} +< *{{{* *}}}* +A fold starts at a "{{{" marker. The following number specifies the fold +level. What happens depends on the difference between the current fold level +and the level given by the marker: +1. If a marker with the same fold level is encountered, the previous fold + ends and another fold with the same level starts. +2. If a marker with a higher fold level is found, a nested fold is started. +3. If a marker with a lower fold level is found, all folds up to and including + this level end and a fold with the specified level starts. + +The number indicates the fold level. A zero cannot be used (a marker with +level zero is ignored). You can use "}}}" with a digit to indicate the level +of the fold that ends. The fold level of the following line will be one less +than the indicated level. Note that Vim doesn't look back to the level of the +matching marker (that would take too much time). Example: > + + {{{1 + fold level here is 1 + {{{3 + fold level here is 3 + }}}3 + fold level here is 2 + +You can also use matching pairs of "{{{" and "}}}" markers to define folds. +Each "{{{" increases the fold level by one, each "}}}" decreases the fold +level by one. Be careful to keep the markers matching! Example: > + + {{{ + fold level here is 1 + {{{ + fold level here is 2 + }}} + fold level here is 1 + +You can mix using markers with a number and without a number. A useful way of +doing this is to use numbered markers for large folds, and unnumbered markers +locally in a function. For example use level one folds for the sections of +your file like "structure definitions", "local variables" and "functions". +Use level 2 markers for each definition and function, Use unnumbered markers +inside functions. When you make changes in a function to split up folds, you +don't have to renumber the markers. + +The markers can be set with the 'foldmarker' option. It is recommended to +keep this at the default value of "{{{,}}}", so that files can be exchanged +between Vim users. Only change it when it is required for the file (e.g., it +contains markers from another folding editor, or the default markers cause +trouble for the language of the file). + + *fold-create-marker* +"zf" can be used to create a fold defined by markers. Vim will insert the +markers for you. Vim will append the start and end marker, as specified with +'foldmarker'. The markers are appended to the end of the line. +'commentstring' is used if it isn't empty. +This does not work properly when: +- The line already contains a marker with a level number. Vim then doesn't + know what to do. +- Folds nearby use a level number in their marker which gets in the way. +- The line is inside a comment, 'commentstring' isn't empty and nested + comments don't work. For example with C: adding /* {{{ */ inside a comment + will truncate the existing comment. Either put the marker before or after + the comment, or add the marker manually. +Generally it's not a good idea to let Vim create markers when you already have +markers with a level number. + + *fold-delete-marker* +"zd" can be used to delete a fold defined by markers. Vim will delete the +markers for you. Vim will search for the start and end markers, as specified +with 'foldmarker', at the start and end of the fold. When the text around the +marker matches with 'commentstring', that text is deleted as well. +This does not work properly when: +- A line contains more than one marker and one of them specifies a level. + Only the first one is removed, without checking if this will have the + desired effect of deleting the fold. +- The marker contains a level number and is used to start or end several folds + at the same time. + +============================================================================== +2. Fold commands *fold-commands* *E490* + +All folding commands start with "z". Hint: the "z" looks like a folded piece +of paper, if you look at it from the side. + + +CREATING AND DELETING FOLDS ~ + *zf* *E350* +zf{motion} or +{Visual}zf Operator to create a fold. + This only works when 'foldmethod' is "manual" or "marker". + The new fold will be closed for the "manual" method. + 'foldenable' will be set. + Also see |fold-create-marker|. + + *zF* +zF Create a fold for [count] lines. Works like "zf". + +:{range}fo[ld] *:fold* *:fo* + Create a fold for the lines in {range}. Works like "zf". + + *zd* *E351* +zd Delete one fold at the cursor. When the cursor is on a folded + line, that fold is deleted. Nested folds are moved one level + up. In Visual mode one level of all folds (partially) in the + selected area are deleted. + Careful: This easily deletes more folds than you expect and + there is no undo for manual folding. + This only works when 'foldmethod' is "manual" or "marker". + Also see |fold-delete-marker|. + + *zD* +zD Delete folds recursively at the cursor. In Visual mode all + folds (partially) in the selected area and all nested folds in + them are deleted. + This only works when 'foldmethod' is "manual" or "marker". + Also see |fold-delete-marker|. + + *zE* *E352* +zE Eliminate all folds in the window. + This only works when 'foldmethod' is "manual" or "marker". + Also see |fold-delete-marker|. + + +OPENING AND CLOSING FOLDS ~ + +A fold smaller than 'foldminlines' will always be displayed like it was open. +Therefore the commands below may work differently on small folds. + + *zo* +zo Open one fold under the cursor. When a count is given, that + many folds deep will be opened. In Visual mode one level of + folds is opened for all lines in the selected area. + + *zO* +zO Open all folds under the cursor recursively. Folds that don't + contain the cursor line are unchanged. + In Visual mode it opens all folds that are in the selected + area, also those that are only partly selected. + + *zc* +zc Close one fold under the cursor. When a count is given, that + many folds deep are closed. In Visual mode one level of folds + is closed for all lines in the selected area. + 'foldenable' will be set. + + *zC* +zC Close all folds under the cursor recursively. Folds that + don't contain the cursor line are unchanged. + In Visual mode it closes all folds that are in the selected + area, also those that are only partly selected. + 'foldenable' will be set. + + *za* +za When on a closed fold: open it. When folds are nested, you + may have to use "za" several times. When a count is given, + that many closed folds are opened. + When on an open fold: close it and set 'foldenable'. This + will only close one level, since using "za" again will open + the fold. When a count is given that many folds will be + closed (that's not the same as repeating "za" that many + times). + + *zA* +zA When on a closed fold: open it recursively. + When on an open fold: close it recursively and set + 'foldenable'. + + *zv* +zv View cursor line: Open just enough folds to make the line in + which the cursor is located not folded. + + *zx* +zx Update folds: Undo manually opened and closed folds: re-apply + 'foldlevel', then do "zv": View cursor line. + Also forces recomputing folds. This is useful when using + 'foldexpr' and the buffer is changed in a way that results in + folds not to be updated properly. + + *zX* +zX Undo manually opened and closed folds: re-apply 'foldlevel'. + Also forces recomputing folds, like |zx|. + + *zm* +zm Fold more: Subtract |v:count1| from 'foldlevel'. If 'foldlevel' was + already zero nothing happens. + 'foldenable' will be set. + + *zM* +zM Close all folds: set 'foldlevel' to 0. + 'foldenable' will be set. + + *zr* +zr Reduce folding: Add |v:count1| to 'foldlevel'. + + *zR* +zR Open all folds. This sets 'foldlevel' to highest fold level. + + *:foldo* *:foldopen* +:{range}foldo[pen][!] + Open folds in {range}. When [!] is added all folds are + opened. Useful to see all the text in {range}. Without [!] + one level of folds is opened. + + *:foldc* *:foldclose* +:{range}foldc[lose][!] + Close folds in {range}. When [!] is added all folds are + closed. Useful to hide all the text in {range}. Without [!] + one level of folds is closed. + + *zn* +zn Fold none: reset 'foldenable'. All folds will be open. + + *zN* +zN Fold normal: set 'foldenable'. All folds will be as they + were before. + + *zi* +zi Invert 'foldenable'. + + +MOVING OVER FOLDS ~ + *[z* +[z Move to the start of the current open fold. If already at the + start, move to the start of the fold that contains it. If + there is no containing fold, the command fails. + When a count is used, repeats the command [count] times. + + *]z* +]z Move to the end of the current open fold. If already at the + end, move to the end of the fold that contains it. If there + is no containing fold, the command fails. + When a count is used, repeats the command [count] times. + + *zj* +zj Move downwards to the start of the next fold. A closed fold + is counted as one fold. + When a count is used, repeats the command [count] times. + This command can be used after an |operator|. + + *zk* +zk Move upwards to the end of the previous fold. A closed fold + is counted as one fold. + When a count is used, repeats the command [count] times. + This command can be used after an |operator|. + + +EXECUTING COMMANDS ON FOLDS ~ + +:[range]foldd[oopen] {cmd} *:foldd* *:folddo* *:folddoopen* + Execute {cmd} on all lines that are not in a closed fold. + When [range] is given, only these lines are used. + Each time {cmd} is executed the cursor is positioned on the + line it is executed for. + This works like the ":global" command: First all lines that + are not in a closed fold are marked. Then the {cmd} is + executed for all marked lines. Thus when {cmd} changes the + folds, this has no influence on where it is executed (except + when lines are deleted, of course). + Example: > + :folddoopen s/end/loop_end/ge +< Note the use of the "e" flag to avoid getting an error message + where "end" doesn't match. + +:[range]folddoc[losed] {cmd} *:folddoc* *:folddoclosed* + Execute {cmd} on all lines that are in a closed fold. + Otherwise like ":folddoopen". + +============================================================================== +3. Fold options *fold-options* + +COLORS *fold-colors* + +The colors of a closed fold are set with the Folded group |hl-Folded|. The +colors of the fold column are set with the FoldColumn group |hl-FoldColumn|. +Example to set the colors: > + + :highlight Folded guibg=grey guifg=blue + :highlight FoldColumn guibg=darkgrey guifg=white + + +FOLDLEVEL *fold-foldlevel* + +'foldlevel' is a number option: The higher the more folded regions are open. +When 'foldlevel' is 0, all folds are closed. +When 'foldlevel' is positive, some folds are closed. +When 'foldlevel' is very high, all folds are open. +'foldlevel' is applied when it is changed. After that manually folds can be +opened and closed. +When increased, folds above the new level are opened. No manually opened +folds will be closed. +When decreased, folds above the new level are closed. No manually closed +folds will be opened. + + +FOLDTEXT *fold-foldtext* + +'foldtext' is a string option that specifies an expression. This expression +is evaluated to obtain the text displayed for a closed fold. Example: > + + :set foldtext=v:folddashes.substitute(getline(v:foldstart),'/\\*\\\|\\*/\\\|{{{\\d\\=','','g') + +This shows the first line of the fold, with "/*", "*/" and "{{{" removed. +Note the use of backslashes to avoid some characters to be interpreted by the +":set" command. It is much simpler to define a function and call it: > + + :set foldtext=MyFoldText() + :function MyFoldText() + : let line = getline(v:foldstart) + : let sub = substitute(line, '/\*\|\*/\|{{{\d\=', '', 'g') + : return v:folddashes .. sub + :endfunction + +The advantage of using a function call without arguments is that it is faster, +see |expr-option-function|. + +Evaluating 'foldtext' is done in the |sandbox|. The current window is set to +the window that displays the line. The context is set to the script where the +option was last set. + +Errors are ignored. For debugging set the 'debug' option to "throw". + +The default value is |foldtext()|. This returns a reasonable text for most +types of folding. If you don't like it, you can specify your own 'foldtext' +expression. It can use these special Vim variables: + v:foldstart line number of first line in the fold + v:foldend line number of last line in the fold + v:folddashes a string that contains dashes to represent the + foldlevel. + v:foldlevel the foldlevel of the fold + +In the result a TAB is replaced with a space and unprintable characters are +made into printable characters. + +The resulting line is truncated to fit in the window, it never wraps. +When there is room after the text, it is filled with the character specified +by 'fillchars'. + +If the 'foldtext' expression starts with s: or |<SID>|, then it is replaced +with the script ID (|local-function|). Examples: > + set foldtext=s:MyFoldText() + set foldtext=<SID>SomeFoldText() +< +Note that backslashes need to be used for characters that the ":set" command +handles differently: Space, backslash and double-quote. |option-backslash| + + +FOLDCOLUMN *fold-foldcolumn* + +'foldcolumn' is a number, which sets the width for a column on the side of the +window to indicate folds. When it is zero, there is no foldcolumn. A normal +value is 4 or 5. The minimal useful value is 2, although 1 still provides +some information. The maximum is 12. + +An open fold is indicated with a column that has a '-' at the top and '|' +characters below it. This column stops where the open fold stops. When folds +nest, the nested fold is one character right of the fold it's contained in. + +A closed fold is indicated with a '+'. + +These characters can be changed with the 'fillchars' option. + +Where the fold column is too narrow to display all nested folds, digits are +shown to indicate the nesting level. + +The mouse can also be used to open and close folds by clicking in the +fold column: +- Click on a '+' to open the closed fold at this row. +- Click on any other non-blank character to close the open fold at this row. + + +OTHER OPTIONS + +'foldenable' 'fen': Open all folds while not set. +'foldexpr' 'fde': Expression used for "expr" folding. +'foldignore' 'fdi': Characters used for "indent" folding. +'foldmarker' 'fmr': Defined markers used for "marker" folding. +'foldmethod' 'fdm': Name of the current folding method. +'foldminlines' 'fml': Minimum number of screen lines for a fold to be + displayed closed. +'foldnestmax' 'fdn': Maximum nesting for "indent" and "syntax" folding. +'foldopen' 'fdo': Which kinds of commands open closed folds. +'foldclose' 'fcl': When the folds not under the cursor are closed. + +============================================================================== +4. Behavior of folds *fold-behavior* + +When moving the cursor upwards or downwards and when scrolling, the cursor +will move to the first line of a sequence of folded lines. When the cursor is +already on a folded line, it moves to the next unfolded line or the next +closed fold. + +While the cursor is on folded lines, the cursor is always displayed in the +first column. The ruler does show the actual cursor position, but since the +line is folded, it cannot be displayed there. + +Many movement commands handle a sequence of folded lines like an empty line. +For example, the "w" command stops once in the first column. + +When starting a search in a closed fold it will not find a match in the +current fold. It's like a forward search always starts from the end of the +closed fold, while a backwards search starts from the start of the closed +fold. + +When in Insert mode, the cursor line is never folded. That allows you to see +what you type! + +When using an operator, a closed fold is included as a whole. Thus "dl" +deletes the whole closed fold under the cursor. + +For Ex commands that work on buffer lines the range is adjusted to always +start at the first line of a closed fold and end at the last line of a closed +fold. Thus this command: > + :s/foo/bar/g +when used with the cursor on a closed fold, will replace "foo" with "bar" in +all lines of the fold. +This does not happen for |:folddoopen| and |:folddoclosed|. + +When editing a buffer that has been edited before, the last used folding +settings are used again. For manual folding the defined folds are restored. +For all folding methods the manually opened and closed folds are restored. +If this buffer has been edited in this window, the values from back then are +used. Otherwise the values from the window where the buffer was edited last +are used. + +============================================================================== + vim:tw=78:ts=8:noet:ft=help:norl: |