WIP: support regions in @includeCode

[shawninder]

WORK IN PROGRESS / DO NOT MERGE

This is a proof of concept for supporting regions in @includeCode tags, meaning you could insert part of a file as a code block by referencing a region of that file.

Example

sourceFile.ts

console.log("Code we don't want inserted")
// #region regionName
console.log('Code we want to insert')
// #endregion regionName
console.log("More code we don't want inserted")

documents/some-page.md

Here is an example:
{@includeCode src/sourceFile.ts#regionName}
This is useful for reasons.

output:

---

Here is an example:

console.log('Code we want to insert')

This is useful for reasons.

---

Notes

• Once merged, this would close Support regions and line numbers within @includeCode tag reference #2814

@Gerrit0 if this basic strategy seems OK, I would add the following to this PR before merging:

TO DO

• Get a simple example working with Typescript
• Use the appropriate region syntax for different languages as documented in the VS Code documentation for Folding
• Make sure small variants don't break things (like using //#region NAME instead of // #region NAME)
• Support regions for Markdown files in the @include tag as well
• Produce useful (translated) errors where appropriate:
  • when a region is specified but cannot be found
  • when a region is found but empty (perhaps just a warning for this one?)
  • when a region is found more than once in a file
• Add support for line-number syntax
• Add tests to validate success, error and warning paths related to these new features
• Document the above additions in site/tags/include.md
• Use these new features in the example app (/example)
• Add an entry in the Changelog describing the changes brought about by this PR

Thoughts? Questions? Advice?

[Gerrit0]

Yes, this seems reasonable. Might want to split the logic out into its own function at this point.

Add support for line-number syntax

Is there any case in which this would be a better option than using a region? It seems like an objectively worse UX to me...

[shawninder]

Might want to split the logic out into its own function at this point.

I'll probably be extracting a function to its own file for this, indeed.

Is there any case in which [line-number syntax] would be a better option than using a region? It seems like an objectively worse UX to me...

Agreed. I'm just thinking of the case where you want to include code from a file you don't control or in which you can't add comments to define regions (think JSON, for example, which does't support comments). In this case the line-numbers seem like the only text-based approach (as opposed to using a language-aware AST) that could work…

Can I let you decide if it's worth including?

[Gerrit0]

Ah, that's a very fair point, line numbers is probably worth it at some point