1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/document-api.R
\name{rstudio-documents}
\alias{rstudio-documents}
\alias{insertText}
\alias{modifyRange}
\alias{setDocumentContents}
\alias{setCursorPosition}
\alias{setSelectionRanges}
\alias{documentId}
\alias{documentPath}
\alias{documentSave}
\alias{documentSaveAll}
\alias{documentNew}
\alias{documentOpen}
\alias{documentClose}
\title{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{
\item{location}{An object specifying the positions, or ranges, wherein text
should be inserted. See \bold{Details} for more information.}
\item{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 \code{ranges} list.}
\item{id}{The document id. When \code{NULL} or blank, the requested operation
will apply to the currently open, or last focused, RStudio document.}
\item{position}{The cursor position, typically created through
\code{\link{document_position}()}.}
\item{ranges}{A list of one or more ranges, typically created
through \code{\link{document_range}()}.}
\item{allowConsole}{Allow the pseudo-id \verb{#console} to be returned, if the \R
console is currently focused? Set this to \code{FALSE} if you'd always like to
target the currently-active or last-active editor in the Source pane.}
\item{type}{The type of document to be created.}
\item{execute}{Should the code be executed after the document
is created?}
\item{path}{The path to the document.}
\item{line}{The line in the document to navigate to.}
\item{col}{The column in the document to navigate to.}
\item{moveCursor}{Boolean; move the cursor to the requested location after
opening the document?}
\item{save}{Whether to commit unsaved changes to the document before closing it.}
}
\description{
Use these functions to interact with documents open in RStudio.
}
\details{
\code{location} should be a (list of) \code{\link{document_position}} or
\code{\link{document_range}} object(s), or numeric vectors coercable to
such objects.
To operate on the current selection in a document, call \code{insertText()}
with only a text argument, e.g.
\preformatted{
insertText("# Hello\\n")
insertText(text = "# Hello\\n")
}
Otherwise, specify a (list of) positions or ranges, as in:
\preformatted{
# 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, "")
}
\code{modifyRange} is a synonym for \code{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 \code{insertText} when working with
\code{\link{document_position}}s, and \code{modifyRange} when working with
\code{\link{document_range}}s.
\code{documentClose} accepts an ID of an open document rather than a path.
You can retrieve the ID of the active document using the \code{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 \code{save} parameter governs the behavior: when \code{TRUE},
unsaved changes are committed, and when \code{FALSE} they are discarded.
}
\note{
The \code{insertText}, \code{modifyRange} and \code{setDocumentContents}
functions were added with version 0.99.796 of RStudio.
The \code{setCursorPosition} and \code{setSelectionRanges} functions were
added with version 0.99.1111 of RStudio.
The \code{documentSave} and \code{documentSaveAll} functions were added
with version 1.1.287 of RStudio.
The \code{documentId} and \code{documentPath} functions were added with
version 1.4.843 of RStudio.
The \code{documentNew} function was introduced in RStudio 1.2.640.
The \code{documentOpen} function was introduced in RStudio 1.4.1106.
The \code{documentClose} function was introduced in RStudio 1.2.1255
}
|
