Session watcher options

[renkun-ken]

This PR addresses #358 and contains a major rewriting of init.R with several options added to customize the functionality of session watcher and it also makes it easier for user to call viewer functions.

New options

• Plot created by plot functions:
  • options(vsc.plot = FALSE) to disable session watcher plot device (Close Disable show plot  #277)
  • options(vsc.plot = "Active" | "Besides" | "Two") to customize plot ViewColumn (Close Suggestion: allow plots from session watcher to share editing pane #331)
  • options(vsc.dev.args = list(width = 800, height = 600)) (previously unannounced options(dev.args)) to customize session watcher png device arguments.
• browser webview created by shiny, R help, httpgd, etc.
  • options(vsc.browser = FALSE) to browse URL in external web browser
  • options(vsc.browser = "Active" | "Besides" | ...) to customize browser WebView ViewColumn: R graphics device with HTTP access. #329 (comment) (Close How do you open webview in new window automatically? #243, Close utils::browseURL #166)
• viewer and page_viewer webview created by htmlwidgets, profvis, etc.
  • options(vsc.viewer = FALSE) to show viewer page (e.g. shiny app) in external web browser
  • options(vsc.page_viewer = FALSE) to show page viewer page (e.g. profvis) in external web browser
  • options(vsc.viewer = "Active" | "Besides" | ...) and options(vsc.page_viewer = "Active" | "Besides" | ...) to customize the ViewColumn of viewer and page_viewer (Close How do you open webview in new window automatically? #243)
• Data webview created by View()
  • options(vsc.view = "Active" | "Besides" | ...) to customize ViewColumn of View (Close How do you open webview in new window automatically? #243)

Public functions

This PR also attaches tools:vscode to make public the following functions in user search path instead of putting everything in an option (getOption("vscodeR")):

• .vsc.attach()
• .vsc.view(..., viewer)
• .vsc.browser(url, title, ..., viewer)
• .vsc.viewer(url, title, ..., viewer)
• .vsc.page_viewer(url, title, ..., viewer)

Now r.attachActive command sends .vsc.attach() to the terminal.

The viewer functions got an argument viewer to specify the ViewColumn to show the WebView or file or use external web browser. These viewer functions are also made to support the use cases like the following:

• Show htmlwidget with customized title and viewer position

.vsc.viewer(DT::datatable(mtcars), "some data", viewer = "Beside")

• Render Rmarkdown document and show the HTML file in the viewer

.vsc.viewer(rmarkdown::render("doc1.Rmd"))

We could make it a shortcut to render Rmd and view the output file, e.g.

{
    "key": "ctrl+shift+r",
    "command": "r.runCommandWithEditorPath",
    "when": "editorTextFocus && editorLangId == 'rmd'",
    "args": ".vsc.viewer(rmarkdown::render(\"$$\", output_format = rmarkdown::html_document()))"
}

Better support of customized plot device

With this PR, user could use, for example, the following code to customize session watcher behavior in .Rprofile:

For example, we could use httpgd as the plot device (if installed) and opens a WebView to show the plot beside the active document when the device is created.

if ("httpgd" %in% .packages(all.available = TRUE)) {
  options(vsc.plot = FALSE)
  options(device = function(...) {
    httpgd::httpgd()
    .vsc.browser(httpgd::httpgdURL(), viewer = "Beside")
  })
}

For advanced users who prefer self-managed sessions:

if (interactive() && Sys.getenv("RSTUDIO") == "") {
  Sys.setenv(TERM_PROGRAM = "vscode")
  if ("httpgd" %in% .packages(all.available = TRUE)) {
    options(vsc.plot = FALSE)
    options(device = function(...) {
      httpgd::httpgd()
      .vsc.browser(httpgd::httpgdURL(), viewer = "Beside")
    })
  }  
  source(file.path(Sys.getenv(if (.Platform$OS.type == "windows") "USERPROFILE" else "HOME"), ".vscode-R", "init.R"))
}

To recover the closed plot view, we could add the following shortcut:

{
        "key": "ctrl+alt+p",
        "command": "r.runCommand",
        "when": "editorTextFocus && editorLangId == 'r'",
        "args": ".vsc.browser(httpgd::httpgdURL(), viewer = \"Beside\")"
}

Other changes

The modification of .Platform is removed since when .Platform$GUI is modified, options(vsc.plot = FALSE) will fallback to pdf devices rather than X11 plot window on Linux and macOS.

For existing persistent R sessions

If the extension is upgraded and user needs to work with existing self-managed, persistent R sessions, user has to manually source init.R before attaching.

[Ikuyadeu]

Thank you for much functional work.

It's been improved by many of your recent contributions, but I'm writing a new PR to make the code more maintainable.

[renkun-ken]

Thanks very much for your review! Your improvement of code is always appreciated!

[renkun-ken]

Also in the changelog of next release, would you mind adding the following for users who upgrade the extension but tries to work with existing R session which still sourced the old init.R:

To work with existing self-managed, persistent R sessions as the extension is upgraded,
source the `init.R` again before attaching.

source(file.path(Sys.getenv(if (.Platform$OS.type == "windows") "USERPROFILE" else "HOME"), ".vscode-R", "init.R"))

[pholck]

Noob here, but wondering if this functionality can be used to pipe a function's html output directly to an external browser (like Hmisc::html(), which generates HTML as output and displays nicely in RStudio). Likely I'm missing something and that ability already exists? Thanks

[renkun-ken]

@pholck Do you mean previewing user generated html in a viewer tab? When sesssion watcher is enabled, the following code will open a viewer:

html <- htmltools::HTML("<b>hello</b>")
htmltools::html_print(html)

[pholck]

@renkun-ken Of course. Very simple. Thank you very much.