Code section support

[renkun-ken]

Closes #160
Closes REditorSupport/vscode-R#76
Closes REditorSupport/vscode-R#193

This PR is a simple support of code section using DocumentSymbolProvider. It matches all comment lines that starts with # and ends with at least four #, +, -, = and show the string in-between as symbol.

This also addresses the comment at REditorSupport/vscode-R#76 (comment) by using unified document symbol provider (all in languageserver), and the symbol information of each code section starts from the first line and ends before the next code section so that a hierarchy of code section containing symbol definitions can be presented.

Following is a screenshot in VSCode:

[randy3k]

We will need to check if the client has the hierarchicalDocumentSymbolSupport capability.

See: https://github.com/REditorSupport/languageserver/blob/master/R/languageserver.R#L29

[renkun-ken]

If the client does not have hierarchicalDocumentSymbolSupport, is there anything we should do about it?

[randy3k]

For section titles, perhaps it makes sense to keep the leading #'s to distinguish them from regular symbols. We also need to remove the location values and replace them with range values.

[randy3k]

Or simply ignore all the section titles.

[mik3y64]

As requested, this is the previous comment from [Feature request] Support for code sections #76

@renkun-ken Thank you very much for implementing this pull request. Coming from RStudio, I have been missing this feature badly. Navigating large file without code sections is a nightmare for me. I can't you tell how much I really appreciate this feature!

First question

In Code section support #163, I see it supports one level of nested hierarchy.

# section 1----
fun1 <- function() {...}
fun2 <- function() {...}

does it support nested hierarchy with multiple levels? A common use case

# section 1----

fun1 <- function() {...}

fun2 <- function() {
    # case A----
    if 
    # case b----
    else if
    # case c----
    else
}

Second question

Is it possible to also support R-friendly heading sections for Rmarkdown (*.rmd)?

This format shows no outline at all.

# Rmarkdown heading

```{r}
plot(iris)
# ```    <- annotate "triple backticks" by commenting it out because it won't show up in Github markdown format

With the same code, and in settings.json, associate Rmarkdown with markdown file extension with "files associations": {"*.rmd": "markdown"}, this format shows markdown heading but it totally breaks R language server support. No syntax highlight, no completion, and whatsoever.

Additionally, can the hash sign # be stripped off? In RStudio, the hash sign # is stripped off so instead of showing # Rmarkdown heading, Rmarkdown heading is shown. The outline view of Visual Studio Code already has built-in support of indentation and collapsible sections, the hash sign # is not necessary. For many levels of headings, the hash signs mess up the outlines and taking out a lot of real estate in the outline view. It would then also be consistent with code sections of *.r files.

[renkun-ken]

@mik3y64 Thanks for posting your question here.

does it support nested hierarchy with multiple levels

It's not hard to support two-level sections like the following:

# section1 ####
fun1 <- function(x, y) {
  cat(x, "\n")
  # subsection 1 ####
  x + y

  # subsection 2 ####
  x + y
}

# section 2 ####
fun2 <- function(x, y) {
  cat(x, "\n")
  # subsection 3 ####
  x + y

  # subsection 4 ####
  x + y

  res <- local({
    x + y
    # subsubsection 5 ####

    x + y
  })

  x + y
}

which has the following outline:

I think is it's good enough for me. In this case, it is sections and subsections. The range of sections span to the next section while the range of subsections only spans a single line or otherwise the range can be hardly determined without relying on parsed document.

Do you view subsection support is a positive addition, @randy3k?

Is it possible to also support R-friendly heading sections for Rmarkdown (*.rmd)?

Currently, I don't handle the Rmd case, which I believe requires special handling in symbol provider which should extract markdown titles instead of such comments. Maybe we should file another PR for this later.

[renkun-ken]

As for the fact that some clients may not have hierarchicalDocumentSymbolSupport, I think the only impact is that the outline shows as a plain list view instead of an expandable hierarchical structure. Seems that we don't have to do anything about it. In this case, it would probably be more clear if the leading #s are preserved in the section titles, as @randy3k suggests.

But if client has hierarchicalDocumentSymbolSupport, including leading #s is consistent with current vscode markdown extension behavior but inconsistent with RStudio behavior and many other markdown editor outline. Since we use SymbolKind.String to distinguish it from function definitions, I think it clear enough to signal it as section titles rather than function definitions in document.

[mik3y64]

It looks great! Subsection support will help navigating complex functions and large files. Two levels cover most of the use cases in R-programming. Well done. Thank you very much! (For the edge cases, if needed, it can always be improved later. It is still early days for R-lsp)

Yes, Rmarkdown sections is more complicated because the leading # heading is the same as leading # used for comments. It makes sense to file another PR.

[randy3k]

We still cannot merge this because some editors might not have hierarchicalDocumentSymbolSupport.

[renkun-ken]

I'm not sure about what the outline might look like if the editor does not have hierarchicalDocumentSymbolSupport but we still provide the section symbols as if it did.

If the editor does not have hierarchicalDocumentSymbolSupport, should we disable the whole feature (not providing section symbols at all) or provide section symbols with only single-line ranges?

[randy3k]

I am okay with ignoring the section symbols if an editor does have hierarchicalDocumentSymbolSupport.

[renkun-ken]

Now section symbols are provided only if client has hierarchicalDocumentSymbolSupport.