(GH-1336) Add syntax folding for comments

This commit adds syntax aware folding for comment regions

* Contiguous blocks of line comments `# ....`

* Function defintion blocks `<# ... #>`

* Region bound comments `# region ...  # endregion`

Author: glennsarti

src/features/Folding.ts

@@ -207,6 +207,114 @@ export class FoldingProvider implements vscode.FoldingRangeProvider {
         return result;
     }
 
+    // Given a zero based offset, find the line text preceeding it in the document
+    private preceedingText(offset: number,
+                           document: vscode.TextDocument): string {
+        const endPos = document.positionAt(offset);
+        const startPos = endPos.translate(0, -endPos.character);
+
+        return document.getText(new vscode.Range(startPos, endPos));
+    }
+
+    // Given a zero based offset, return the line number in the document
+    private lineAtOffest(offset: number,
+                         document: vscode.TextDocument): number {
+        return document.positionAt(offset).line;
+    }
+
+    // Finding blocks of comment tokens is more complicated as the newline characters are not
+    // classed as comments.  To workaround this we search for the comment character `#` scope name
+    // "punctuation.definition.comment.powershell" and then determine contiguous line numbers from there
+    private matchBlockCommentScopeElements(tokens,
+                                           document: vscode.TextDocument) {
+        const result = [];
+
+        const emptyLine = new RegExp("^[\\s]+$");
+
+        let startLine: number = -1;
+        let nextLine: number = -1;
+
+        tokens.forEach((token, index) => {
+            if (token.scopes.includes("punctuation.definition.comment.powershell")) {
+                // The punctuation.definition.comment.powershell token matches new-line comments
+                // and inline comments e.g. `$x = 'foo' # inline comment`.  We are only interested
+                // in comments which begin the line i.e. no preceeding text
+                if (emptyLine.test(this.preceedingText(token.startIndex, document))) {
+                    const lineNum = this.lineAtOffest(token.startIndex, document);
+                    // A simple pattern for keeping track of contiguous numbers in a known
+                    // sorted array
+                    if (startLine === -1) {
+                        startLine = lineNum;
+                        nextLine = lineNum + 1;
+                    } else {
+                        if (lineNum === nextLine) {
+                            nextLine = lineNum + 1;
+                        } else {
+                            result.push(new MatchedToken(null,
+                                                         null,
+                                                         startLine,
+                                                         nextLine - 1,
+                                                         MatchType.Comment,
+                                                         document));
+                            startLine = lineNum;
+                            nextLine = lineNum + 1;
+                        }
+                    }
+                }
+            }
+        });
+
+        // If we exist the token array and we're still processing comment lines, then the
+        // comment block simply ends at the end of document
+        if (startLine !== -1) {
+            result.push(new MatchedToken(null, null, startLine, nextLine - 1, MatchType.Comment, document));
+        }
+
+        return result;
+    }
+
+    // Given a zero based offset, find the line text after it in the document
+    private subsequentText(offset: number,
+                           document: vscode.TextDocument): string {
+        const startPos = document.positionAt(offset);
+        // We don't know how long the line is so just return a really long one.
+        const endPos = startPos.translate(0, 1000);
+        return document.getText(new vscode.Range(startPos, endPos));
+    }
+
+    // Create a new token object with an appended scopeName
+    private addTokenScope(token,
+                          scopeName: string) {
+        // Only a shallow clone is required
+        const tokenClone = Object.assign({}, token);
+        tokenClone.scopes.push(scopeName);
+        return tokenClone;
+    }
+
+    // Given a list of grammar tokens, find the tokens that are comments and
+    // the comment text is either `# region` or `# endregion`.  Return a new list of tokens
+    // with custom scope names added, "custom.start.region" and "custom.end.region" respectively
+    private extractRegionScopeElements(tokens,
+                                       document: vscode.TextDocument) {
+        const result = [];
+
+        const emptyLine = new RegExp("^[\\s]+$");
+        const startRegionText = new RegExp("^#\\s*region\\b");
+        const endRegionText = new RegExp("^#\\s*endregion\\b");
+
+        tokens.forEach( (token, index) => {
+          if (token.scopes.includes("punctuation.definition.comment.powershell")) {
+            if (emptyLine.test(this.preceedingText(token.startIndex, document))) {
+              const commentText = this.subsequentText(token.startIndex, document);
+
+              if (startRegionText.test(commentText)) { result.push(this.addTokenScope(token, "custom.start.region")); }
+              if (endRegionText.test(commentText)) { result.push(this.addTokenScope(token, "custom.end.region")); }
+            }
+          }
+        });
+        return result;
+    }
+
     // Given a list of tokens, return a list of matched tokens/line numbers regions
     private matchGrammarTokens(tokens, document: vscode.TextDocument): IMatchedTokenList {
         const matchedTokens = [];
@@ -237,6 +345,23 @@ export class FoldingProvider implements vscode.FoldingRangeProvider {
                                           MatchType.Region, document)
             .forEach((x) => { matchedTokens.push(x); });
 
+        // Find matching Braces   #region -> #endregion
+        this.matchScopeElements(this.extractRegionScopeElements(tokens, document),
+                                "custom.start.region",
+                                "custom.end.region",
+                                MatchType.Region, document)
+            .forEach( (x) => { matchedTokens.push(x); });
+
+        // Find blocks of line comments   # comment1\n# comment2\n...
+        this.matchBlockCommentScopeElements(tokens, document).forEach((x) => { matchedTokens.push(x); });
+
+        // Find matching function definitions   <# -> #>
+        this.matchScopeElements(tokens,
+                                "punctuation.definition.comment.block.begin.powershell",
+                                "punctuation.definition.comment.block.end.powershell",
+                                MatchType.Comment, document)
+            .forEach( (x) => { matchedTokens.push(x); });
+
         return matchedTokens;
     }