implement support for requesting document context by id

NEWS.md

@@ -1,6 +1,9 @@
 
 # rstudioapi 0.14 (UNRELEASED)
 
+* `getSourceEditorContext()` gains the `id` argument, to be used to request
+  the editor context for a document with an already-known ID. (#251)
+
 * Added `documentOpen()`, for opening a document in RStudio and optionally
   navigating the cursor to a particular point in the file. The method is
   synchronous and returns the document ID upon completion.
@@ -12,10 +15,12 @@
   `unregisterCommandCallback`, used to execute a callback after an IDE command
   is executed.
 
+
 # rstudioapi 0.13
 
 * Fixed an issue where `rstudioapi::insertText()` would fail. (#208)
 
+
 # rstudioapi 0.12
 
 * Fixed an issue where remote `rstudioapi` calls would erroneously use
@@ -27,6 +32,7 @@
 * Added `registerChunkExecCallback` and `unregisterChunkExecCallback`, used to
   execute a callback after a chunk is ran.
 
+
 # rstudioapi 0.11
 
 * `rstudioapi::launcherResourceLimit()` now properly delegates the type
@@ -50,16 +56,19 @@
 * Added `userIdentity` and `systemUsername`, used to retrieve information about
   the current user.
 
+
 # rstudioapi 0.10
 
 * Added the parameters `echo` and `focus` to `sendToConsole()`.
 
+
 # rstudioapi 0.9
 
 * Added functions for displaying jobs in RStudio's Jobs pane: `jobAdd()`, `jobRemove()`, etc.
 
 * Added `translateLocalUrl()`, for translating localhost URLs to externally addressable ones on RStudio Server.
 
+
 # rstudioapi 0.8
 
 * Added functions for installing + using build tools:
@@ -91,33 +100,38 @@
   `terminalRunning()`, `terminalKill()`, `terminalSend()`, `terminalExecute()`,
   and `terminalExitCode()`.
 
+
 # rstudioapi 0.6
 
 * Add sendToConsole function
 
 * Add APIs for setting cursor position in document
 
+
 # rstudioapi 0.5
 
 * Add askForPassword function
 
 * Add getActiveProject function
 
+
 # rstudioapi 0.4
 
 * Add API methods for interacting with a document open in RStudio: 'insertText()', 'modifyRange()' and 'getActiveDocumentContext()'.
 
+
 # rstudioapi 0.3
 
 * Add stub and documentation for sourceMarker function
 
+
 # rstudioapi 0.2
 
 * Compatibility with calling conventions for RStudio v0.99
 
 * Stubs and documentation for versionInfo, previewRd, and viewer functions
 
-# rstudioapi 0.1
 
-Initial release to CRAN
+# rstudioapi 0.1
 
+* Initial release to CRAN

R/document-api.R

@@ -198,6 +198,9 @@ documentSaveAll <- function() {
 #' \code{contents} \tab The contents of the document.\cr
 #' \code{selection} \tab A \code{list} of selections. See \bold{Details} for more information.\cr
 #' }
+#' 
+#' @param id The ID of a particular document, as retrieved by `documentId()`
+#'   or similar. Supported in RStudio 2022.06.0 or newer.
 #'
 #' @rdname rstudio-editors
 #' @name rstudio-editors
@@ -208,8 +211,8 @@ getActiveDocumentContext <- function() {
 
 #' @name rstudio-editors
 #' @export
-getSourceEditorContext <- function() {
-  getDocumentContext("getSourceEditorContext")
+getSourceEditorContext <- function(id = NULL) {
+  getDocumentContext("getSourceEditorContext", id)
 }
 
 #' @name rstudio-editors

R/document-methods.R

@@ -207,14 +207,20 @@ primary_selection.document_selection <- function(x, ...) {
   x[[1]]
 }
 
-getDocumentContext <- function(fn) {
-  context <- callFun(fn)
+getDocumentContext <- function(fn, id = NULL) {
+
+  context <- if (is.null(id))
+    callFun(fn)
+  else
+    callFun(fn, id)
 
-  if (is.null(context)) return(NULL)
+  if (is.null(context))
+    return(NULL)
 
   Encoding(context$path) <- "UTF-8"
   Encoding(context$contents) <- "UTF-8"
   context$selection <- as.document_selection(context$selection)
 
   structure(context, class = "document_context")
+
 }