From 7d082d4816f1dcc9c0b3a6ed4323b9d827153de1 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Tue, 17 Dec 2024 08:22:19 +0800 Subject: [PATCH] vim-patch:3920bb4: runtime(doc): document how to minimize fold computation costs closes: vim/vim#16224 https://github.com/vim/vim/commit/3920bb4356aa7324a4be1071c87524a2f921d921 Co-authored-by: Konfekt --- runtime/doc/fold.txt | 41 ++++++++++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/runtime/doc/fold.txt b/runtime/doc/fold.txt index b844e0ed85..9798170dbc 100644 --- a/runtime/doc/fold.txt +++ b/runtime/doc/fold.txt @@ -82,9 +82,11 @@ The most efficient is to call a function without arguments: > 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: + +The result of foldexpr then determines the fold level as follows: value meaning ~ 0 the line is not in a fold 1, 2, .. the line is in a fold with this level @@ -99,6 +101,8 @@ These are the conditions with which the expression is evaluated: "<1", "<2", .. a fold with this level ends at this line ">1", ">2", .. a fold with this level starts at this line +The result values "=", "s" and "a" are more expensive, please see |fold-expr-slow|. + 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. @@ -112,12 +116,6 @@ 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 ||, then it is replaced with the script ID (|local-function|). Examples: > set foldexpr=s:MyFoldExpr() @@ -143,6 +141,35 @@ end in that line. It may happen that folds are not updated properly. You can use |zx| or |zX| to force updating folds. +Minimizing Computational Cost *fold-expr-slow* + +Due to its computational cost, this fold method can make Vim unresponsive, +especially when the fold level of all lines have to be initially computed. +Afterwards, after each change, Vim restricts the computation of foldlevels +to those lines whose fold level was affected by it (and reuses the known +foldlevels of all the others). + +The fold expression should therefore strive to minimize the number of dependent +lines needed for the computation of a given line: For example, try to avoid the +"=", "a" and "s" return values, because these will require the evaluation of the +fold levels on previous lines until an independent fold level is found. + +If this proves difficult, the next best thing could be to cache all fold levels +in a buffer-local variable (b:foldlevels) that is only updated on |b:changedtick|: +>vim + func MyFoldFunc() + if b:lasttick == b:changedtick + return b:foldlevels[v:lnum - 1] + endif + let b:lasttick = b:changedtick + let b:foldlevels = [] + " compute foldlevels ... + return b:foldlevels[v:lnum - 1] + enddef + set foldexpr=s:MyFoldFunc() +< +In above example further speedup was gained by using a function without +arguments (that must still use v:lnum). See |expr-option-function|. SYNTAX *fold-syntax*