Interact with Documents open in RStudio — rstudio-documents • rstudioapi

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 = "r",
  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. One of "r" (default), "rmarkdown", or "sql".
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.

Note

The insertText, modifyRange and setDocumentContents functions were added with version 0.99.796 of RStudio.

The setCursorPosition and setSelectionRanges functions were added with version 0.99.1111 of RStudio.

The documentSave and documentSaveAll functions were added with version 1.1.287 of RStudio.

The documentId and documentPath functions were added with version 1.4.843 of RStudio.

The documentNew function was introduced in RStudio 1.2.640.

The documentOpen function was introduced in RStudio 1.4.1106.

The documentClose function was introduced in RStudio 1.2.1255