Explicit Folding

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:

• begin/end
• begin/continuation
• begin/while
• while
• separator
• indentation

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": "<(?!area|base|br|col|embed|hr|img|input|link|menuitem|meta|param|source|track|wbr)([a-zA-Z0-9]+)[^>\/]*>", "endRegex": "<\\/\\1>" } ] }
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:

	ko-fi.com/daiyam
	liberapay.com/daiyam/donate
	paypal.me/daiyam99

Enjoy!