rstudio-documents: Interact with Documents open in RStudio

Description

Use these functions to interact with documents open in RStudio.

Usage

insertText(location = NULL, text = NULL, id = NULL)
modifyRange(location = NULL, text = NULL, id = NULL)
setDocumentContents(text, id = NULL)
setCursorPosition(position, id = NULL)
setSelectionRanges(ranges, id = NULL)
documentId(allowConsole = TRUE)
documentPath(id = NULL)
documentSave(id = NULL)
documentSaveAll()
documentNew(
  text,
  type = c("r", "rmarkdown", "sql"),
  position = document_position(0, 0),
  execute = FALSE
)
documentOpen(path, line = -1L, col = -1L, moveCursor = TRUE)
documentClose(id = NULL, save = TRUE)

Arguments

location: An object specifying the positions, or ranges, wherein text should be inserted. See Details for more information.
text: A character vector, indicating what text should be inserted at each aforementioned range. This should either be length one (in which case, this text is applied to each range specified); otherwise, it should be the same length as the ranges list.
id: The document id. When NULL or blank, the requested operation will apply to the currently open, or last focused, RStudio document.
position: The cursor position, typically created through document_position().
ranges: A list of one or more ranges, typically created through document_range().
allowConsole: Allow the pseudo-id #console to be returned, if the R console is currently focused? Set this to FALSE if you'd always like to target the currently-active or last-active editor in the Source pane.
type: The type of document to be created.
execute: Should the code be executed after the document is created?
path: The path to the document.
line: The line in the document to navigate to.
col: The column in the document to navigate to.
moveCursor: Boolean; move the cursor to the requested location after opening the document?
save: Whether to commit unsaved changes to the document before closing it.

Details

location should be a (list of) document_position or document_range object(s), or numeric vectors coercable to such objects.

To operate on the current selection in a document, call insertText() with only a text argument, e.g.


    insertText("# Hello\n")
    insertText(text = "# Hello\n")

Otherwise, specify a (list of) positions or ranges, as in:


    # insert text at the start of the document
    insertText(c(1, 1), "# Hello\n")
    # insert text at the end of the document
    insertText(Inf, "# Hello\n")
    # comment out the first 5 rows
    pos <- Map(c, 1:5, 1)
    insertText(pos, "# ")
    # uncomment the first 5 rows, undoing the previous action
    rng <- Map(c, Map(c, 1:5, 1), Map(c, 1:5, 3))
    modifyRange(rng, "")

modifyRange is a synonym for insertText, but makes its intent clearer when working with ranges, as performing text insertion with a range will replace the text previously existing in that range with new text. For clarity, prefer using insertText when working with document_positions, and modifyRange when working with document_ranges.

documentClose accepts an ID of an open document rather than a path. You can retrieve the ID of the active document using the documentId() function.

Closing is always done non-interactively; that is, no prompts are given to the user. If the user has made changes to the document but not saved them, then the save parameter governs the behavior: when TRUE, unsaved changes are committed, and when FALSE they are discarded.