Explicit Folding
This extension lets you manually control how and where to fold your code.
Configuration
In your settings:
"editor.foldingStrategy": "auto",
// only if you want the folding ranges from only this extension
"editor.defaultFoldingRangeProvider": "zokugun.explicit-folding",
"explicitFolding.rules": {
"*": {
"begin": "{{{",
"end": "}}}"
}
},
"[javascriptreact]": {
"explicitFolding.rules": [
{
"begin": "{/*",
"end": "*/}"
},
{
"begin": "<",
"end": "/>"
}
]
}
Rules
The property explicitFolding.rules defines how to fold the code.
Here the list of possible rules:
Global Scope
When used in the global scope, the rules must be grouped by language.
"explicitFolding.rules": {
"cpp": [
{
"beginRegex": "#if(?:n?def)?",
"middleRegex": "#el(?:se|if)",
"endRegex": "#endif"
}
]
}
Language Scope
"[cpp]": {
"explicitFolding.rules": [
{
"beginRegex": "#if(?:n?def)?",
"middleRegex": "#el(?:se|if)",
"endRegex": "#endif"
}
]
}
Regex Syntax
Via VSCode's editor, the extension supports ES2018 regexes (except \n).
The document parser is line-based. So \n and multi-lines regexes aren't supported.
The end of a line can be matched with $.
Additionally, the following aspects of PCRE2 syntax are supported:
(?i)x: x becomes case insensitive(?i:x)y: only x is case insensitive
editor.defaultFoldingRangeProvider
Since VSCode v1.73.0, it's hightly recommanded to use the following settings:
"editor.foldingStrategy": "auto",
"editor.defaultFoldingRangeProvider": "zokugun.explicit-folding",
Wildcard Exclusions
By default, the wildcard rule, like the following, are applied to all languages.
"explicitFolding.rules": {
"*": {
"begin": "{{{",
"end": "}}}"
}
}
But, for languages which are using the indentation to define foldable blocks of code (such as in Python syntax), the wildcard rule will prevent the use of the indentation provider.
To avoid that, you need to add an exclusion:
"explicitFolding.wildcardExclusions": ["python"]
Per Files
You can define a complete new set of rules for specific files with the property explicitFolding.perFiles.
"[javascript]": {
"explicitFolding.rules": [...],
"explicitFolding.perFiles": {
"*.special.js": [...]
}
},
"[xml]": {
"explicitFolding.rules": [...],
"explicitFolding.perFiles": {
"*.config.xml": [...]
}
}
minimatch is used to determine if a filename is matching the pattern or not.
Language List
The root explicitFolding.rules allows a list of languages as a language identifier. The rules will be applied to all the specified language.
"explicitFolding.rules": {
"javascript,snippets": [
{
"begin": "{",
"end" : "}",
"foldLastLine": true,
},
{
"begin": "`",
"end" : "`",
"foldLastLine": true,
},
],
},
Include Rule
The include rule allows to include the rules from another language.
"explicitFolding.rules": {
"#region": [
{
"beginRegex": "#[\\s]*region[\\s]+([\\w]+)",
"endRegex": "#[\\s]*endregion",
},
],
},
"[shellscript]": {
"explicitFolding.rules": [
{ "include": "#region" },
],
},
"[dockerfile]": {
"explicitFolding.rules": [
{ "include": "shellscript" },
],
},
#region isn't a valid language identifier so it won't be matched to any files.
But it can be used as a group of language features that can be included by different languages.
It needs to defined in the root explicitFolding.rules.
Auto Fold
You can define the automatic folding of the ranges with the property explicitFolding.autoFold (an enum, none by default).
Each rule can overwrite that property with its own property autoFold (a boolean, false by default).
So you can auto fold only the imports with:
"[javascript]": {
"explicitFolding.rules": [
{
"beginRegex": "^import\\b",
"whileRegex": "^(?:import\\b|\\/\\/)",
"autoFold": true
}
],
"explicitFolding.autoFold": "none"
}
enum values
Debugging
If the property explicitFolding.debug (false by default) is true, the extension will print out debug information into the channel Folding of the panel Output (menu: View / Output).
Priority/Delay
It's only used when editor.defaultFoldingRangeProvider isn't set to zokugun.explicit-folding.
VSCode is scoring each folding providers based on the scheme and language. When the scores are identical, the providers which have been registered the most recently, receive a higher priority.
When starting up, VSCode loads the installed extensions. When reading a file, VSCode will load the folding provider of the file's language (only once per language).
The property explicitFolding.delay (measured in milliseconds, and set to 1000 by default) is used so that this extension's folding provider has a higher priority than that of the language provider.
Notification
The property explicitFolding.notification (minor by default) indicates when to show the update notification.
Usages
| Language |
Config |
| Emacs |
"explicitFolding.rules": {
"*": {
"begin": "{{{",
"end": "}}}"
}
}
|
| C/C++ |
"[cpp]": {
"explicitFolding.rules": [
{
"beginRegex": "#if(?:n?def)?",
"middleRegex": "#el(?:se|if)",
"endRegex": "#endif"
},
{
"begin": "/*",
"end": "*/",
"nested": false
},
{
"begin": "//",
"continuation": "\\",
"nested": false
}
]
}
|
| HTML |
"[html]": {
"explicitFolding.rules": [
{
"beginRegex": "\/]*>",
"endRegex": ""
}
]
}
|
| Nim |
"[nim]": {
"explicitFolding.rules": {
"indentation": true,
"offSide": true,
"beginRegex": "^\\s*(?:proc|template)"
}
}
|
| PHP |
"[php]": {
"explicitFolding.rules": [
{
"beginRegex": "(?:case|default)[^:]*:",
"endRegex": "break;|(.)(?=case|default|\\})",
"foldLastLine": [true, false]
},
{
"beginRegex": "\\{",
"middleRegex": "\\}[^}]+\\{",
"endRegex": "\\}"
}
]
}
|
| Python |
"[python]": {
"explicitFolding.rules": [
{
"beginRegex": "\"\"\"",
"endRegex": "\"\"\""
},
{
"indentation": true,
"offSide": true
}
]
}
|
| SASS |
"[scss]": {
"explicitFolding.rules": [
{
"beginRegex": " \\{\\s*$",
"endRegex": "^\\s*\\}"
}
]
}
|
FAQ
Q: Why don't I see the foldings?
A: Firstly, make sure you have the setting "editor.showFoldingControls": "always" defined, and that you don't have "editor.foldingStrategy": "indentation" defined. Then, verify your configuration. 😉
Q: Why doesn't \n work?
A: The document parser is line-based. So in order to match the end of a line, you need to use $.
Donations
Support this project by becoming a financial contributor, using any of the following methods:
Enjoy!
