F.A.Q. section in `README.md` is unclear about multi-line `regex`

[OCRenkist]

The suggested answer regarding why \n does not work, mentions that $ must be used, but provides no example of how to do that using the Mozilla regex syntax. Likewise, Mozilla-provided documentation is unclear to me regarding this use case.

[daiyam]

Since The document parser is line-based., multi-lines regexes won't work.

I know you are trying to fold Lua but can you give me an example of what you want to fold (function, if, for, comment or ???)

You can look at the discussions to see how some users have successfully used the extension.

[OCRenkist]

Examples for Lua

I have prepared these code-folding examples at your request. 😊 (And much gratitude for how you are matching my style of keyword highlighting.)

💡 Main idea: When folded, I want to hide the end statements as well as the contents of the blocks they end.

Single-Level Blocks

The simple case is a single, top-level block with an end statement.

The block:

➖ if conditions then
   actions
  end

Should fold to:

➕ if conditions then

Blocks Implied by Indentation

Though Lua is not a language with whitespace-defined blocks the way, e.g. Python is, for managing complex code constructs, it his highly advantageous to offer the developer an opportunity to fold the trailing lines.

A typical example for where this would be needed, is within multi-line comments.

The statement:

➖ --[[ some header description
   some list item
   some list item
   some list item
  ]]

Folds to:

➕ --[[ some header description

Multi-Level Blocks

Blocks with other blocks defined as nested within them must allow the nested blocks to be folded without having to fold the parent block(s).

The blocks:

➖ for conditions do
➖  if conditions then
    actions
➖  else
    actions
   end
  end

Sould fold to:

➖ for conditions do
➖  if conditions then
    actions
➕  else
   end
  end

⚠️ NOTICE: A nested block which is folded should not hide the end statement for its parent block, even if the nested block has no end statement of its own according to Lua syntax.

And then to:

➖ for conditions do
➕  if conditions then
  end

And finaly:

➕ for conditions do

Blocks Defined on Multiple Lines

When dealing with blocks where the opening statements span multiple lines, place the folding toggle on the first line.

The block:

➖ if conditions
  then
   actions
  end

Should fold to:

➕ if conditions

💡 Or consider the typical case from C-like languages:

The block:

public static void main()
{
  continue;
}

Should not appear as:

  public static void main()
➖ {
   continue;
  }

But rather:

➖ public static void main()
  {
   continue;
  }

And folds to:

➕ public static void main()

Bonus Feature

Some of the currently-supported languages already hide trailing blank lines when folding blocks, and this is greatly appreciated! 💯 In so doing, the debate over whether to use blank lines is rendered moot. 👍

[daiyam]

I will use https://github.com/lcpz/lain/blob/master/layout/termfair.lua as my test file since it contains most of the cases.

[daiyam]

For Lua, here the config that I used:

"[lua]": {
  "explicitFolding.debug": true,
  "explicitFolding.rules": [
    {
      "begin": "--[[",
      "end": "--]]",
      "nested": false,
      "kind": "comment",
    },
    {
      "begin": "--",
      "continuation": "\\",
      "nested": false,
      "kind": "comment",
    },
    {
      "begin": "\"",
      "end": "\"",
      "nested": false,
    },
    {
      "beginRegex": "\\b(?:for|function|if)\\b",
      "middleRegex": "\\belse(?:if)?\\b",
      "endRegex": "\\bend\\b",
    },
  ],
},

For C, you should look at https://github.com/zokugun/vscode-explicit-folding/discussions/44

[daiyam]

Were the configs helpful?