provide 'setDocumentContents' API

NAMESPACE

@@ -13,6 +13,8 @@ S3method(print,document_selection)
 export(as.document_position)
 export(as.document_range)
 export(callFun)
+export(document_position)
+export(document_range)
 export(findFun)
 export(getActiveDocumentContext)
 export(getVersion)
@@ -21,10 +23,9 @@ export(insertText)
 export(is.document_position)
 export(is.document_range)
 export(isAvailable)
-export(makePosition)
-export(makeRange)
 export(navigateToFile)
 export(previewRd)
+export(setDocumentContents)
 export(sourceMarkers)
 export(verifyAvailable)
 export(versionInfo)

R/document-api.R

@@ -54,6 +54,29 @@ insertText <- function(location, text, id = NULL) {
   callFun("insertText", location, text, id)
 }
 
+#' Set the Contents of a Document
+#'
+#' Set the contents of a document, deleting any other text existing in the
+#' document previously.
+#'
+#' @param text The text to insert into the document.
+#'
+#' @param id The document id. When \code{NULL} or blank,
+#'   the mutation will apply to the currently open, or last
+#'   focused, RStudio document. Use the \code{id} returned
+#'   from \code{\link{getActiveDocumentContext}()} to ensure
+#'   that the operation is applied on the intended document.
+#' @export
+setDocumentContents <- function(text, id = NULL) {
+
+  location <- document_range(
+    document_position(1, 1),
+    document_position(Inf, 1)
+  )
+
+  insertText(location, text, id)
+}
+
 #' Get the Active Document Context
 #'
 #' Returns information about the currently active
@@ -80,5 +103,5 @@ insertText <- function(location, text, id = NULL) {
 getActiveDocumentContext <- function() {
   context <- callFun("getActiveDocumentContext")
   context$selection <- as.document_selection(context$selection)
-  `class<-`(context, "document_context")
+  structure(context, class = "document_context")
 }

R/document-methods.R

@@ -11,7 +11,7 @@
 #'
 #' @export
 #' @family location
-makePosition <- function(row, column) {
+document_position <- function(row, column) {
   structure(c(row = as.numeric(row), column = as.numeric(column)),
             class = "document_position")
 }
@@ -39,7 +39,7 @@ as.document_position.default <- function(x) {
   if (length(x) != 2 || !is.numeric(x))
     stop("'x' should be a numeric vector of length 2", call. = FALSE)
 
-  makePosition(row = x[[1]], column = x[[2]])
+  document_position(row = x[[1]], column = x[[2]])
 }
 
 #' @export
@@ -73,9 +73,9 @@ print.document_position <- function(x, ...) {
 #' @name document_range
 #'
 #' @export
-makeRange <- function(start, end = NULL) {
+document_range <- function(start, end = NULL) {
 
-  # Allow users to write e.g. 'makeRange(c(1, 2, 3, 4))';
+  # Allow users to write e.g. 'document_range(c(1, 2, 3, 4))';
   # ie, ignore using the 'end' argument
   if (is.null(end)) {
 
@@ -110,13 +110,13 @@ as.document_range.document_range <- function(x) {
 
 #' @export
 as.document_range.default <- function(x) {
-  makeRange(x)
+  document_range(x)
 }
 
 #' @export
 format.document_range <- function(x, ...) {
   startPos <- as.document_position(x$start)
-  endPos <- as.document_position(x$end)
+  endPos   <- as.document_position(x$end)
   paste(format(startPos, ...), "--", format(endPos, ...))
 }
 

tests/testthat/test-document-apis.R

@@ -21,23 +21,23 @@ test_that("various APIs for interacting with an RStudio document work", {
   scratchRanges <- Map(c, Map(c, 7:11, 1), Map(c, 7:11, Inf))
 
   # Insert text at position
-  insertText(makePosition(7, Inf), " Hello")
+  insertText(document_position(7, Inf), " Hello")
   insertText(list(
-    makePosition(8, Inf),
-    makePosition(9, Inf)
+    document_position(8, Inf),
+    document_position(9, Inf)
   ), " Hello")
 
   insertText(list(
-    makePosition(10, Inf),
-    makePosition(11, Inf)
+    document_position(10, Inf),
+    document_position(11, Inf)
   ), c(" First", " Second"))
 
   # Clean up
   insertText(scratchRanges, "#")
 
   # Insert text at range
   insertText(c(7, 1, 7, Inf), "# Howdy")
-  insertText(makeRange(start = c(8, 1), end = c(8, Inf)), "# Hello There")
+  insertText(document_range(start = c(8, 1), end = c(8, Inf)), "# Hello There")
 
   # Clean up
   insertText(scratchRanges, "#")
@@ -57,7 +57,7 @@ test_that("various APIs for interacting with an RStudio document work", {
   # Clean up things we appended to the document
   end <- grep("^# -- Final Scratch Space -- #", context$contents)
   insertText(
-    makeRange(start = c(end + 1, 1), end = c(Inf, 1)),
+    document_range(start = c(end + 1, 1), end = c(Inf, 1)),
     ""
   )