Feature request: API for managing folding area

[rebornix]

We are adding commands for fold/unfolding code in Vim and it turns out that Code's APIs are somewhat limited. All Vim's folding commands can be categorized as below.

Close/Open Folds (Done)

Vim allows users to open/close folds under cursor. Users can also decide how deep the folds are opened or closed.

These commands are partially supported, we have editor.fold, editor.unfold, editor.foldRecursively, etc and it's easy to map them to Vim commands. Besides, Code supports us to fold from level 1 to level 5 but level 6 and above is not supported and we don't have similar commands for unfold.

Vim even supports us to toggle Fold. We don't have this command in Code and we can't use editor.fold or editor.unfold to workaround as we have no idea whether we are inside a folding area.

executeCommand('editor.fold, {levels: 3});

executeCommand('editor.unfold, {levels: 3});

Fold creation/deletion

Vim allows users to create or delete folds manually. It's not possible here as Code is doing this for us.

Navigate through Folds

We can navigate to previous or next fold area through commands in Vim. If we want to implement this in Code, we need to know the info about all folds.

Fold options

We can configure max/min screen lines for a fold, max level for folds, etc in Vim. Again, we didn't expose them in Code.

---

There are about 20+ unique commands and 10+ options about folding and we can only implement 5 of them partially right now.

[aeschli]

Discussed with Sandeep. The goal is provide commands that let you implement the VIM requirements. Unless really needed, we try not to introduce the concept of the folding regions in the extension host API.

[rebornix]

@aeschli I'm Okay with hiding folding region info. If we can provide generic API to navigate/manage folding regions, then it would be perfect. If it turns out that we are adding too many Vim specific commands, maybe it can be a good time to introduce Fold.

[sandy081]

There are already existing commands supporting some folding functionalities / operations. So, we can add more if necessary or needed. True that we are adding them as Vim needs them, but we are making sure that they are generic enough for any extension to use.

[aminroosta]

Unless really needed, we try not to introduce the concept of the folding regions in the extension host API.

@aeschli
I think folding info is one of the basic things extensions should be able to query, just like cursor position or number of lines in a document.

The goal is provide commands that let you implement the VIM requirements.

I don't understand what's the reason behind your decision to hide these information from extensions. I get the feel that you trying to do the extension writer jobs. If you provide the basic info for folding regions then extension writers can implement anything on top of it.

@sandy081

True that we are adding them as Vim needs them, but we are making sure that they are generic enough for any extension to use.

I think wrapping folding info with generic enough apis is not realistic right now.
Because you don't know all the use cases future extensions will need.

Having information on folding areas gives extension writers more power on how to control the editor. we can easily implement cursorMove commands you implemented, toggleFold, moveToFoldEnd, moveToFoldBegin, and anything we can possibly find in vim documentation later.

[rebornix]

Vim allows us to create Fold area manually, by indentation, expression or syntax while Code is doing foding by indentation. But customizing the folding creation is not frequently used by Vim users so we should go with indentation first.

The first part is not folding command directly but they rely on folding info

• Moving cursor across folding area. Tracked by Cursor Up and Down should place the cursor at end of line if it's current state is end of line #9619

The second part is openning/closing folds and they only require fold information.

• za When on a closed fold: open it. When on an open fold: close it and set 'foldenable'.
• zA When on a closed fold: open it recursively. When on an open fold: close it recursively and set 'foldenable'.
• [z Move to the start of the current open fold.
• ]z Move to the end of the current open fold.
• zj Move downwards to the start of the next fold.
• zk Move upwards to the end of the previous fold.

The third part depends on option foldlevel. 'foldlevel' is a number option: The higher the more folded regions are open.

• zm Fold more: Subtract one from 'foldlevel'.
• zr Reduce folding: Add one to 'foldlevel'.
• zo Open one fold under the cursor.When a count is given, that many folds deep will be opened.
• zc Close one fold under the cursor. When a count is given, that many folds deep are closed.
• zv View cursor line: Open just enough folds to make the line in which the cursor is located not folded.
• zx Update folds: Undo manually opened and closed folds: re-apply 'foldlevel', then do "zv": View cursor line.

Others are folding area manual creation/deletion and Fold options but I don't think we need to take them into consideration before we handle all commands above.

[sandy081]

@aminroosta

Exposing folding regions (or any view regions) to the extensions is not helpful because they are based on internals. It will make difficult for extension developers to implement on top of them correctly. Instead, developing and exposing the commands will make it available to everybody and easier to use. I agree that it is not possible to develop commands / api that can meet everyone's requirements. Since it is an open community, it is always welcome to discuss/request/contribute them.

Again, just exposing folding regions will not be enough to implement commands likecursorMove, toggleFold etc... It needs enough information about editor internals.

[aminroosta]

@sandy081

It will make difficult for extension developers to implement on top of them correctly. Instead, developing and exposing the commands will make it available to everybody and easier to use.

With great power comes great responsibility!
Your argument is perfectly valid, it just reminds me of the same arguments Java developers use against C++ ones for accessing memory.

Exposing folding regions to the extensions is not helpful because they are based on internals.

I don't think querying the IndentRange[] array returned from computeRanges exposes editor internals.

export class IndentRange {
    _indentRangeBrand: void;
    startLineNumber:number;
    endLineNumber:number;
    indent:number;
       ....
}

Better yet just replace IndentRange[] with vscode.Range[].
And allow us to add or remove vscode.Range to the list of folding regions.

developing and exposing the commands will make it available to everybody and easier to use.

If you take the route of implementing apis with vim extensions in mind then you are doing the extension writers job, we will have future issues opening on vscode instead of the relative vim plugin repository.

That being said the commands @rebornix listed is all that i've ever used in vim and i think that's true for many many vim users and those who have used more than that will never switch from the original vim 😄