) }}.\cr
#' Default: \code{FALSE}.
#' @param force Whether to force the operation and overwrite an existing file with the same
#' name.\cr
#' Default: \code{FALSE}.
#' @param globally Whether to install this theme for the current user or all users. If set to
#' \code{TRUE} this will attempt to install the theme for all users, which may
#' require administrator privileges. Only applies when \code{add} is \code{TRUE}. \cr
#' Default: \code{FALSE}.
#'
#' @note The \code{convertTheme} function was introduced in RStudio 1.2.879.
#'
#' @export
convertTheme <- function(themePath, add = TRUE, outputLocation = NULL, apply = FALSE, force = FALSE, globally = FALSE)
{
callFun("convertTheme", themePath, add, outputLocation, apply, force, globally)
}
#' Get Theme List
#'
#' Retrieves a list of the names of all the editor themes installed for RStudio.
#'
#' @note The \code{getThemes} function was introduced in RStudio 1.2.879.
#'
#' @export
getThemes <- function()
{
callFun("getThemes")
}
#' Remove a custom theme from RStudio.
#'
#' @param name The unique name of the theme to remove.
#'
#' @note The \code{removeTheme} function was introduced in RStudio 1.2.879.
#'
#' @export
removeTheme <- function(name)
{
callFun("removeTheme", name)
}
rstudioapi/R/remote.R 0000644 0001762 0000144 00000003200 13542731513 014253 0 ustar ligges users
isChildProcess <- function() {
!is.na(Sys.getenv("RSTUDIOAPI_IPC_REQUESTS_FILE", unset = NA))
}
callRemote <- function(call, frame) {
# check for active request / response
request <- Sys.getenv("RSTUDIOAPI_IPC_REQUESTS_FILE", unset = NA)
response <- Sys.getenv("RSTUDIOAPI_IPC_RESPONSE_FILE", unset = NA)
secret <- Sys.getenv("RSTUDIOAPI_IPC_SHARED_SECRET", unset = NA)
if (is.na(request) || is.na(response) || is.na(secret))
stop("internal error: callFunRemote() called without remote connection")
attr(call, "srcref") <- NULL
# ensure rstudioapi functions get appropriate prefix
if (is.name(call[[1L]]))
call[[1L]] <- call("::", as.name("rstudioapi"), call[[1L]])
# ensure arguments are evaluated before sending request
for (i in seq_along(call)[-1L])
call[[i]] <- eval(call[[i]], envir = frame)
# write to tempfile and rename, to ensure atomicity
data <- list(secret = secret, call = call)
tmp <- tempfile(tmpdir = dirname(request))
saveRDS(data, file = tmp)
file.rename(tmp, request)
# loop until response is ready (poll)
# in theory we'd just do a blocking read but there isn't really a good
# way to do this in a cross-platform way without additional dependencies
now <- Sys.time()
repeat {
# check for response
if (file.exists(response))
break
# check for lack of response
diff <- difftime(Sys.time(), now, units = "secs")
if (diff > 10)
stop("RStudio did not respond to rstudioapi IPC request")
# wait a bit
Sys.sleep(0.1)
}
# read response
response <- readRDS(response)
if (inherits(response, "error"))
stop(response)
response
}
rstudioapi/R/templates.R 0000644 0001762 0000144 00000006364 13535525640 015000 0 ustar ligges users #' Create a Project Template
#'
#' Create a project template. See
#' \url{https://rstudio.github.io/rstudio-extensions/rstudio_project_templates.html}
#' for more information.
#'
#' @param package The path to an \R package sources.
#' @param binding The \R skeleton function to associate with this project
#' template. This is the name of the function that will be used to initialize
#' the project.
#' @param title The title to be shown within the \strong{New Project...} wizard.
#' @param subtitle (optional) The subtitle to be shown within the \strong{New Project...} wizard.
#' @param caption (optional) The caption to be shown on the landing page for this template.
#' @param icon (optional) The path to an icon, on disk, to be used in the dialog. Must be an
#' \code{.png} of size less than 64KB.
#' @param open_files (optional) Files that should be opened by RStudio when the project is
#' generated. Shell-style globs can be used to indicate when multiple files
#' matching some pattern should be opened -- for example, OpenFiles: R/*.R
#' would indicate that RStudio should open all .R files within the R folder of
#' the generated project.
#' @param overwrite Boolean; overwrite a pre-existing template file if one exists?
#' @param edit Boolean; open the file for editting after creation?
#' @export
createProjectTemplate <- function(package = ".",
binding,
title,
subtitle = paste("Create a new", title),
caption = paste("Create", title),
icon = NULL,
open_files = NULL,
overwrite = FALSE,
edit = TRUE)
{
package <- normalizePath(package, winslash = "/", mustWork = TRUE)
# construct metadata
metadata <- list(
Binding = binding,
Title = title,
Subtitle = subtitle,
Caption = caption,
Icon = icon,
OpenFiles = open_files
)
# drop nulls
metadata <-
metadata[vapply(metadata, Negate(is.null), FUN.VALUE = logical(1))]
# create templates directory
templates_dir <- file.path(package, "inst/rstudio/templates/project")
if (!file.exists(templates_dir))
if (!dir.create(templates_dir, recursive = TRUE))
stop(sprintf("failed to create '%s' directory", templates_dir))
# construct DCF metadata contents
dcf <- paste(names(metadata), ": ", metadata, sep = "")
# add header linking to online documentation
header <- c(
"# This file provides the metadata necessary for RStudio to",
"# use the '%s()' function when initializing a project. See",
"# the documentation online at: ",
"#",
"# https://rstudio.github.io/rstudio-extensions/rstudio_project_templates.html",
"#",
"# for more details.",
""
)
header <- sprintf(header, binding)
dcf <- c(header, dcf)
# construct path to file
name <- gsub("[^a-zA-Z0-9_.]", "_", binding)
path <- file.path(templates_dir, paste(name, "dcf", sep = "."))
if (file.exists(path) && !overwrite)
stop(sprintf("a skeleton function already exists at path '%s'", path))
# write out
writeLines(dcf, con = path)
if (edit)
utils::file.edit(path)
TRUE
}
rstudioapi/R/code.R 0000644 0001762 0000144 00000007610 13542731513 013703 0 ustar ligges users #' Check if RStudio is running.
#'
#' @param version_needed An optional version specification. If supplied,
#' ensures that RStudio is at least that version.
#'
#' @param child_ok Boolean; check if the current R process is a child
#' process of the main RStudio session? This can be useful for e.g. RStudio
#' Jobs, where you'd like to communicate back with the main R session from
#' a child process through `rstudioapi`.
#'
#' @return \code{isAvailable} a boolean; \code{verifyAvailable} an error message
#' if RStudio is not running
#'
#' @export
#' @examples
#' rstudioapi::isAvailable()
#' \dontrun{rstudioapi::verifyAvailable()}
isAvailable <- function(version_needed = NULL, child_ok = FALSE) {
if (child_ok && isChildProcess())
return(callRemote(sys.call(), parent.frame()))
identical(.Platform$GUI, "RStudio") && version_ok(version_needed)
}
version_ok <- function(version = NULL) {
if (is.null(version)) return(TRUE)
getVersion() >= version
}
#' @rdname isAvailable
#' @export
verifyAvailable <- function(version_needed = NULL) {
if (!isAvailable()) stop("RStudio not running", call. = FALSE)
if (!version_ok(version_needed)) {
stop("Need at least version ", version_needed, " of RStudio. ",
"Currently running ", getVersion(), call. = FALSE)
}
invisible(TRUE)
}
#' Return the current version of the RStudio API
#'
#' @return A \code{\link{numeric_version}} which you can compare to a string
#' and get correct results.
#' @export
#' @examples
#' \dontrun{
#' if (rstudioapi::getVersion() < "0.98.100") {
#' message("Your version of RStudio is quite old")
#' }
#' }
getVersion <- function() {
verifyAvailable()
callFun("versionInfo")$version
}
#' Call an RStudio API function
#'
#' This function will return an error if RStudio is not running, or the
#' function is not available. If you want to fall back to different
#' behavior, use \code{\link{hasFun}}.
#'
#' @param fname name of the RStudio function to call.
#' @param ... Other arguments passed on to the function
#' @export
#' @examples
#' if (rstudioapi::isAvailable()) {
#' rstudioapi::callFun("versionInfo")
#' }
callFun <- function(fname, ...) {
if (isChildProcess())
return(callRemote(sys.call(), parent.frame()))
verifyAvailable()
if (usingTools())
found <- exists(toolsName(fname), envir = toolsEnv(), mode = "function")
else
found <- exists(fname, envir = asNamespace("rstudio"), mode = "function")
if (!found)
stop("Function ", fname, " not found in RStudio", call. = FALSE)
f <- findFun(fname, mode = "function")
f(...)
}
#' Exists/get for RStudio functions
#'
#' These are specialized versions of \code{\link[base]{get}} and
#' \code{\link[base]{exists}} that look in the rstudio package namespace.
#' If RStudio is not running, \code{hasFun} will return \code{FALSE}.
#'
#' @param name name of object to look for
#' @param ... other arguments passed on to \code{\link[base]{exists}} and
#' \code{\link[base]{get}}
#' @param version_needed An optional version specification. If supplied,
#' ensures that RStudio is at least that version. This is useful if
#' function behavior has changed over time.
#' @export
#' @examples
#' rstudioapi::hasFun("viewer")
hasFun <- function(name, version_needed = NULL, ...) {
if (!isAvailable(version_needed)) return(FALSE)
if (usingTools())
exists(toolsName(name), toolsEnv(), ...)
else
exists(name, envir = asNamespace("rstudio"), ...)
}
#' @export
#' @rdname hasFun
findFun <- function(name, version_needed = NULL, ...) {
verifyAvailable(version_needed)
if (usingTools())
get(toolsName(name), toolsEnv(), ...)
else
get(name, envir = asNamespace("rstudio"), ...)
}
usingTools <- function() {
exists(toolsName("versionInfo"), envir = toolsEnv())
}
toolsName <- function(name) {
paste(".rs.api.", name, sep="")
}
toolsEnv <- function() {
as.environment(match("tools:rstudio", search()))
}
rstudioapi/NEWS.md 0000644 0001762 0000144 00000005561 13617331257 013552 0 ustar ligges users
# rstudioapi 0.11
* `rstudioapi::launcherResourceLimit()` now properly delegates the type
and memory arguments. (#164)
* `rstudioapi` gains the function `highlightUi()`, used to highlight UI
elements in newer versions of RStudio.
* Paths returned from `selectFile()` are now properly marked with
UTF-8 encoding.
* It is now possible for `rstudioapi` to communicate with a parent RStudio
session, for R sessions launched as RStudio jobs. Use
`rstudioapi::isAvailable(child_ok = TRUE)` to assert that it's okay to check
that `rstudioapi` is available and is running within an RStudio job.
* Added `bugReport()`, a helper function for reporting RStudio bugs
on the GitHub issue tracker with an issue template pre-populated
with some helpful diagnostic information.
* 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:
`buildToolsCheck()`, `buildToolsInstall()`, `buildToolsExec()`
* Added functions for installing + using themes: `addTheme()`, `applyTheme()`,
`convertTheme()`, `getThemes()`, `getThemeInfo()`.
* Added `previewSql()`, for previewing output from executing a SQL query.
* Added `askForSecret()`, for prompting the user to enter a password or otherwise privileged information.
* Fixed an issue where `getActiveProject()` failed for non-ASCII paths. (#86)
# rstudioapi 0.7
* Added methods for prompting the user for file paths: `selectFile()`,
`selectDirectory()`.
* `askForPassword()` gains a default prompt (#41)
* Add `createProjectTemplate()` function
* Add `setPersistentValue()` / `getPersistentValue()` functions
* Add methods for interacting with Terminal tab:
`terminalActivate()`, `terminalClear()`, `terminalCreate()`, `terminalList()`,
`terminalBuffer()`, `terminalContext()`, `terminalVisible()`, `terminalBusy()`,
`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/MD5 0000644 0001762 0000144 00000016410 13617370242 012754 0 ustar ligges users 52c9119f42754fdee3b115afd25a5d86 *DESCRIPTION
2491c4039e00be047cce99c452d3fd00 *LICENSE
b756a4c6b03f3db63daa294e56ff1fe7 *NAMESPACE
ff4bc51b46abe762be4417055d34e78d *NEWS.md
8079d5d17a7544786ae008beb8bcfeff *R/bug-report.R
55173aca0882afbde1f0255d458bc4d1 *R/build-tools.R
c8c3e88180d402f3efbec33ce57d3641 *R/code.R
4a18e62299bb7e705b6909f2105ef27f *R/commands.R
cbf2dc8a60ac9c041d46cd2cf3eb616a *R/dependencies.R
d3c1b096bce76401a443187c76adc980 *R/dialogs.R
d3b7b1360801c205e6217adc8c8a5d3d *R/dictionaries.R
3817651bef22ba2c61d3a60f520802f5 *R/document-api.R
489638fe1f6c67d1afa7a9c983d4e8f7 *R/document-methods.R
54f0340af2a982b8a0b15aa291fc3e63 *R/highlight-ui.R
5584305529c126844bf5630637364535 *R/jobs.R
adc717e1855b71b7214350f9160c6c5f *R/launcher-functions.R
a6b30acdc0bba6b16108033aee980ba6 *R/launcher.R
627c1993928ca912b11e33ee38fd7e15 *R/misc.R
79eec1cb2c08f7cf08d65c905326b44c *R/prefs.R
b993b959fb26173752c62514952af63b *R/preview.R
1ef0b0fa956973a7458b7173a2b50579 *R/remote.R
7e2f7b3a3ffe953516b099bf2eef3bbb *R/stubs.R
4ff4a8ad43716c847b75431bf5917b6d *R/templates.R
3236309e8e13f9de2467556413fc6dc5 *R/terminal.R
2d7e1fbeb173a3802cbb6b8989dafc68 *R/themes.R
803dd0ced443c56b0a3457007b52f89c *R/tutorial.R
590e8d0ab9ee2f18c4a207db7cbd0f98 *R/urls.R
e93f0ae783320dd015e29338f7790b57 *R/user.R
1219c514fd50cdd826fe436c25d006e0 *R/utils.R
1915dcc02ca5e391e58789e77a050b7c *build/vignette.rds
bd533fab67709a0c98a10338d39ee679 *inst/doc/dialogs.R
01f5841a3d3d9249f0b6509697189d5e *inst/doc/dialogs.Rmd
f003379d255b96fd2d4c07603d47a1df *inst/doc/dialogs.html
462250065182d40e516e44efddc7dc36 *inst/doc/document-manipulation.R
0a81e2595fc31915b1c6ec77cdbc8fe2 *inst/doc/document-manipulation.Rmd
19cf19865084ad5cb46964785ed28292 *inst/doc/document-manipulation.html
4eb7f4d912f65f74a951b41ca1ab859d *inst/doc/introduction.Rmd
89487e0b2c5c2ff36d5cc63e5a5938e4 *inst/doc/introduction.html
0ed95f3ce75ac90c6e6948d13c746b8e *inst/doc/projects.R
b3f763976fc12d073ef5f4cf610589db *inst/doc/projects.Rmd
19963167fdb87737daad07a0517a8b6d *inst/doc/projects.html
26da07b8e9e5d3e5986c75a8444ca0ca *inst/doc/r-session.R
3d38c4910650dbcb09439a1a17f585ca *inst/doc/r-session.Rmd
478bd7e3b9c8f643986fd2a3b5a2c14e *inst/doc/r-session.html
41a4c559971972d6d9dcd58bfff08ae1 *inst/doc/terminal.R
2ba016fe1aab495668b3409636332aa3 *inst/doc/terminal.Rmd
589529dc848fe9d66fcc114e6c548f9b *inst/doc/terminal.html
5ce8c65f8c31f69388f565ac5489d6fc *inst/resources/bug-report.md
d56348eb1de0a1598a08f341e6c77fb7 *man/addTheme.Rd
a1cf55bd498336bae467889235fc3a69 *man/applyTheme.Rd
03ae66de60e7f4e1516280cba5e474ec *man/askForPassword.Rd
bbb1277f8fdb80c43a8a729a74354724 *man/askForSecret.Rd
f61ff76af7670343148eddcfb4322a7c *man/bugReport.Rd
131ed40ec1f2c247de1daca8d61987da *man/build-tools.Rd
ca498d6d2888e0fede04ba5b602101f7 *man/callFun.Rd
1e8edeaf164a2cf7eec9e63a14ceed4f *man/convertTheme.Rd
b10ea44fcfca221242a2451c2225d09b *man/createProjectTemplate.Rd
21c99823cf7f079015c90598ec9dd0fa *man/dictionaries.Rd
d87040340d4b4d6c4dca502b9e3ae9b4 *man/document_position.Rd
d1962425c332ad09514f3e37f303ed0f *man/document_range.Rd
55a9095839caec4ff0d1c5c2e11101e0 *man/executeCommand.Rd
c47a9b7aac17e65a1cbd34ee82199d2c *man/figures/logo.png
df5831ec5c23b263da1bbbf667a9d428 *man/figures/logo.svg
f04fbc421ccf0b918695f75f4ae8b055 *man/file-dialogs.Rd
d14b51dd251dd29bfaf0331da150e656 *man/getActiveProject.Rd
e8613e517f5cc356760d0ce5b644cfbf *man/getRStudioPackageDependencies.Rd
5b4bad70a80db81b876e5f6463d3548a *man/getThemeInfo.Rd
8edc2af0faef24f9a652a86b81b5c24e *man/getThemes.Rd
968062ff97bfc41d78110ff3b10c0a52 *man/getVersion.Rd
3c53d1752a61b88ad8651daa6f819869 *man/hasColorConsole.Rd
8f8b3eccc1a09659f46c4452f3b3c944 *man/hasFun.Rd
c7409259025e7b1662bf9905ac73f27e *man/highlightUi.Rd
a0211f534c0d88747c7e1ef2d05a2791 *man/isAvailable.Rd
eebab5f604b61d1bafe51256d4b9affd *man/jobAdd.Rd
acdbf8a0338af356077082b15b355e9d *man/jobAddOutput.Rd
9051b67163d45cfd6e6d9ae6f0577496 *man/jobAddProgress.Rd
93ee60c5b960e68323a23a99fe8e7e0d *man/jobRemove.Rd
f31c1e0b8a5838fd0db7ed56287dcfce *man/jobRunScript.Rd
79373cca7a9f0ab6ee23521380c5c8e0 *man/jobSetProgress.Rd
d31710ec126547221421e54eb07a0125 *man/jobSetState.Rd
71f57ac475e575fc512b43bc0010d019 *man/jobSetStatus.Rd
b592071a8f1e3592bf32b7ea78b17d91 *man/launcher.Rd
567b5f1568782839dd88c77b4f7e241f *man/launcherConfig.Rd
cbfb8170d63fdafcd9e5383660223d58 *man/launcherContainer.Rd
6c584fbee9c32f076d3f69c84dba1a3d *man/launcherControlJob.Rd
0f7079f75e81c404d4a205f8fdd89c87 *man/launcherGetJob.Rd
2899e0783ad1e0fe534e3008331e5e4e *man/launcherHostMount.Rd
d64526ddc834f20a11bcb341e2daf758 *man/launcherNfsMount.Rd
61c7c1da73b171d190c5046ae513dd1c *man/launcherPlacementConstraint.Rd
dbd47c3d189ec8240e737b53ab436749 *man/launcherResourceLimit.Rd
502fcbedcad514c55296af0d2c84acdb *man/launcherSubmitJob.Rd
3829c487cbb06f958ef47c9088ccd1af *man/launcherSubmitR.Rd
86b986e7537985ce69231bf925bbb88c *man/navigateToFile.Rd
bc25a20af1d58c6a5be93da3ae89c837 *man/persistent-values.Rd
11afff28da5a838ddfcd210abfc8e144 *man/previewRd.Rd
d6ca33cb2ebd43da41a772b02d9aef90 *man/previewSql.Rd
7b821cb2132dcd6c12a9d637b71f4579 *man/primary_selection.Rd
eb937360ded93ddcc72db9b05ae249db *man/projects.Rd
52e055edef2180fd4cbe3399c36409f4 *man/readPreference.Rd
d0f5111fe66f8a504453fcace0580543 *man/readRStudioPreference.Rd
f6fdc4654fd43e7e8051b137a57b9920 *man/removeTheme.Rd
3df25a8da801d52209245fcab3971490 *man/restartSession.Rd
91076970b25002beb22f48a5bd28e613 *man/rstudio-documents.Rd
45f4ac0bee6c6b5b45094fbaf38fffc8 *man/rstudio-editors.Rd
81d600f00e10340d25838b6aad201435 *man/savePlotAsImage.Rd
e0a004d52100469f3b9e8434c682f59c *man/sendToConsole.Rd
e029ea8323236e891e2633f14cfe8fdd *man/showDialog.Rd
19c83a2f89748a964b29c28811d8f152 *man/showPrompt.Rd
5d93ce0c1c220e766829593935f80145 *man/showQuestion.Rd
0d5ed2c1fbd1d32f3d1c67bdd21d9c8a *man/sourceMarkers.Rd
c64d52cabb74dc47ddb6f03a7aa42dd7 *man/systemUsername.Rd
4fd7953dfeab6e22aae3c56f8a4a7809 *man/terminalActivate.Rd
3c6a4f340b0b363511497f473d36eaa8 *man/terminalBuffer.Rd
c008a5884aabb312c7a43d9a351b3653 *man/terminalBusy.Rd
88d13e99eeae07e762c21ab64c19adb5 *man/terminalClear.Rd
d952a8fab9e2e89a80d61ae82693bf55 *man/terminalContext.Rd
87954224f9cff66b9677f8b5df31ba7f *man/terminalCreate.Rd
6fadb83e4c436541196b6c699d692d24 *man/terminalExecute.Rd
58186f9255226b2e33ff2459a489b453 *man/terminalExitCode.Rd
ce1abbd7856353cb9212f71e2c74088c *man/terminalKill.Rd
35606fc8b8e6c7c12a4c1fbb4681b799 *man/terminalList.Rd
07878b215a21b075d1cb6dbebb40ad32 *man/terminalRunning.Rd
a52daec78ac24d663227ed446a4d182f *man/terminalSend.Rd
44a2b40ffbf8ee37c0f8297f2f25b1e3 *man/terminalVisible.Rd
9be38b177d3343a46b6c805a66de5594 *man/translateLocalUrl.Rd
9bd0485e13b003db97e8bbc0cc7a3e30 *man/updateDialog.Rd
838bfa3b11a19467a2f607749c532105 *man/userIdentity.Rd
81a78e563475ba823e5bc21d7eef55ed *man/versionInfo.Rd
94dbccd5ee33fca7d9601a03622990d4 *man/viewer.Rd
54f1ec85c00d8a6421e5d6fc1cf6f810 *man/writePreference.Rd
48621778ea8d4a52679b916559945e1e *man/writeRStudioPreference.Rd
01f5841a3d3d9249f0b6509697189d5e *vignettes/dialogs.Rmd
0a81e2595fc31915b1c6ec77cdbc8fe2 *vignettes/document-manipulation.Rmd
4eb7f4d912f65f74a951b41ca1ab859d *vignettes/introduction.Rmd
b3f763976fc12d073ef5f4cf610589db *vignettes/projects.Rmd
3d38c4910650dbcb09439a1a17f585ca *vignettes/r-session.Rmd
2ba016fe1aab495668b3409636332aa3 *vignettes/terminal.Rmd
rstudioapi/inst/ 0000755 0001762 0000144 00000000000 13617331501 013412 5 ustar ligges users rstudioapi/inst/doc/ 0000755 0001762 0000144 00000000000 13617331501 014157 5 ustar ligges users rstudioapi/inst/doc/terminal.Rmd 0000644 0001762 0000144 00000011165 13535525640 016452 0 ustar ligges users ---
title: "Interacting with Terminals"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Interacting with Terminals}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```
The `rstudioapi` package provides a collection of functions that can be used to interact with the [RStudio terminal tab](https://support.rstudio.com/hc/en-us/articles/115010737148-Using-the-RStudio-Terminal).
There are two primary approaches to using these functions.
1. Use `terminalExecute()` to run a specific process with the output shown in a new terminal buffer, without blocking the current R session.
2. Create, query, and manipulate interactive terminals. This might be used to develop custom terminal behavior via an [RStudio addin](https://rstudio.github.io/rstudioaddins/).
## TerminalExecute Scenario
```{r}
# Start a command with results displayed in a terminal buffer
termId <- rstudioapi::terminalExecute("ping rstudio.com")
# If viewing the result in the terminal buffer is sufficient,
# then no need to do anything else. The command will continue
# running and displaying its results without blocking the R session.
# To obtain the results programmatically, wait for it to finish.
while (is.null(rstudioapi::terminalExitCode(termId))) {
Sys.sleep(0.1)
}
result <- rstudioapi::terminalBuffer(termId)
# Delete the buffer and close the session in the IDE
rstudioapi::terminalKill(termId)
```
## Interative Terminal Scenario
Several concepts are important to understand to make full use of these functions.
### Terminal Identifier
Each terminal session has a unique **terminal identifier**, a required argument for most of the functions. A terminal identifier is generated and returned when a terminal is created via `terminalCreate()` or `terminalExecute()`, and identifiers of existing terminals can be obtained via `terminalList()` or `terminalVisible()`.
### Terminal Session
A **terminal session** is an instance of a terminal that can be displayed in the RStudio terminal tab. A terminal session consists of:
* a unique terminal identifier
* a unique caption shown in the RStudio terminal dropdown (e.g. "Terminal 1")
* a shell process (e.g. bash) running as a child process of the R session
* zero or more processes running as children of the shell (e.g. commands)
* an xterm-compatible terminal emulator in the terminal tab
* a buffer of output shown in the terminal emulator (can be cleared via `terminalClear()`)
### Busy Terminal
A terminal session with child processes running (excluding the shell), is considered **busy** and this is reflected in the IDE UI and can be queried with `terminalBusy()`.
### Terminal States
In the most common situation, a terminal session has all the above features; however, it is possible for terminals to be in other states.
**No shell process or child processes**: This happens if the associated R session has been closed (or suspended in the case of an inactive RStudio Server session).
The `terminalRunning()` function returns `TRUE` if a terminal is in this state.
If a terminal is not running, it can be started via interacting with it in the RStudio IDE, or via `terminalActivate()`.
```{r}
# start an interactive terminal using the shell selected in
# RStudio global options
myTerm <- rstudioapi::terminalCreate()
# ....
# sometime later
# ....
if (!rstudioapi::terminalRunning(myTerm)) {
# start the terminal shell back up, but don't bring to front
rstudioapi::terminalActivate(myTerm, show = FALSE)
# wait for it to start
while (!rstudioapi::terminalRunning(myTerm)) {
Sys.sleep(0.1)
}
# send a new command
rstudioapi::terminalSend(myTerm, "echo Hello\n")
}
```
**Running but not loaded in the IDE**: On RStudio Server, the web browser can be closed but the R session and any associated terminal sessions keep running. If the web browser is reconnected, each terminal will be redisplayed in the IDE when it is selected. The `rstudioapi` functions may be used on a terminal in this state; for example, the buffer may still be fetched with `terminalBuffer()` even if the terminal isn't loaded in the IDE (so long as the R session is still alive).
**Terminated but still visible**: Normally the terminal emulator for a given terminal session will close when the shell exits. If the option **Close Terminal When Shell Exits** is turned off, then the terminal buffer will remain loaded in the RStudio IDE until closed by the user or `terminalKill()`. Terminals started with `terminalExecute()` will always remain loaded when they finish running. To test a terminal for this state, `terminalExitCode()` will return a non-NULL value.
rstudioapi/inst/doc/dialogs.R 0000644 0001762 0000144 00000002421 13617331500 015722 0 ustar ligges users ## ----setup, include=FALSE-----------------------------------------------------
knitr::opts_chunk$set(eval = FALSE)
## -----------------------------------------------------------------------------
# # request the path to an existing .csv file on disk
# path <- rstudioapi::selectFile(caption = "Select CSV File",
# filter = "CSV Files (*.csv)",
# existing = TRUE)
#
# # now, you could read the data using e.g. 'readr::read_csv()'
# data <- readr::read_csv(path)
#
# # request a file path (e.g. where you would like to save a new file)
# target <- rstudioapi::selectFile(caption = "Save File",
# label = "Save",
# existing = FALSE)
#
# # save data to the path provided by the user
# saveRDS(data, file = target)
## -----------------------------------------------------------------------------
# token <- rstudioapi::askForPassword(
# prompt = "Please provide your GitHub access token."
# )
## -----------------------------------------------------------------------------
# rstudioapi::showDialog(title = "Hello, world!",
# message = "You're awesome!",
# url = "http://www.example.com")
rstudioapi/inst/doc/r-session.R 0000644 0001762 0000144 00000001244 13617331501 016225 0 ustar ligges users ## ----setup, include=FALSE-----------------------------------------------------
knitr::opts_chunk$set(eval = FALSE)
## -----------------------------------------------------------------------------
# # restart R, then run some code after
# rstudioapi::restartSession(command = "print('Welcome back!')")
#
# # send some code to the console and execute it immediately
# rstudioapi::sendToConsole("1 + 1", execute = TRUE)
## -----------------------------------------------------------------------------
# setHook("rstudio.sessionInit", function(newSession) {
# if (newSession)
# message("Welcome to RStudio ", rstudioapi::getVersion())
# }, action = "append")
rstudioapi/inst/doc/r-session.Rmd 0000644 0001762 0000144 00000002645 13535525640 016564 0 ustar ligges users ---
title: "Interacting with the R Session"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Interact with the R Session}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```
## Session Interaction
The `rstudioapi` package allows you to interact with the running R session in a couple useful ways: you can send code to the R console, or restart the R session.
```{r}
# restart R, then run some code after
rstudioapi::restartSession(command = "print('Welcome back!')")
# send some code to the console and execute it immediately
rstudioapi::sendToConsole("1 + 1", execute = TRUE)
```
## Running at Startup
Typically, code that you want to run at the start of an R session is placed into an `.Rprofile` file (see [Initialization at the Start of a Session](https://stat.ethz.ch/R-manual/R-devel/library/base/html/Startup.html) for details). However, RStudio's API hooks are not available until RStudio has fully started up, so most `rstudioapi` methods will not work inside `.Rprofile`.
If you want to invoke `rstudioapi` methods on session startup, use the `rstudio.sessionInit` hook. For example, to print the RStudio version to the R console when the session begins:
```{r}
setHook("rstudio.sessionInit", function(newSession) {
if (newSession)
message("Welcome to RStudio ", rstudioapi::getVersion())
}, action = "append")
```
rstudioapi/inst/doc/terminal.R 0000644 0001762 0000144 00000002672 13617331501 016124 0 ustar ligges users ## ----setup, include=FALSE-----------------------------------------------------
knitr::opts_chunk$set(eval = FALSE)
## -----------------------------------------------------------------------------
# # Start a command with results displayed in a terminal buffer
# termId <- rstudioapi::terminalExecute("ping rstudio.com")
#
# # If viewing the result in the terminal buffer is sufficient,
# # then no need to do anything else. The command will continue
# # running and displaying its results without blocking the R session.
#
# # To obtain the results programmatically, wait for it to finish.
# while (is.null(rstudioapi::terminalExitCode(termId))) {
# Sys.sleep(0.1)
# }
#
# result <- rstudioapi::terminalBuffer(termId)
#
# # Delete the buffer and close the session in the IDE
# rstudioapi::terminalKill(termId)
## -----------------------------------------------------------------------------
# # start an interactive terminal using the shell selected in
# # RStudio global options
# myTerm <- rstudioapi::terminalCreate()
#
# # ....
# # sometime later
# # ....
# if (!rstudioapi::terminalRunning(myTerm)) {
# # start the terminal shell back up, but don't bring to front
# rstudioapi::terminalActivate(myTerm, show = FALSE)
#
# # wait for it to start
# while (!rstudioapi::terminalRunning(myTerm)) {
# Sys.sleep(0.1)
# }
#
# # send a new command
# rstudioapi::terminalSend(myTerm, "echo Hello\n")
# }
rstudioapi/inst/doc/document-manipulation.html 0000644 0001762 0000144 00000032521 13617331501 021364 0 ustar ligges users
Document Manipulation
Document Manipulation
knitr::opts_chunk$set(eval = FALSE)
The rstudioapi package provides a small family of functions that can be used to interact with documents open in an RStudio session. For example, the following code could be used to insert a ‘last modified’ comment at the start of a document:
# construct the text to be inserted
fmt <- "# This document was last modified on %s.\n"
text <- sprintf(fmt, Sys.Date())
# specify a range where this text should be inserted; here,
# we use the first line; that is, the 'range' between the start
# of the first row, and the start of the second row
range <- rstudioapi::document_range(c(1, 0), c(2, 0))
rstudioapi::insertText(range, text)
By default, these APIs target the editor instance either currently focused by the user, or when no such editor is currently focused, the last focused editor. If you need to target a specific editor instance (for example, you want to write code that inserts text into the console), you can use getConsoleEditorContext() to get the id for the console editor:
# get console editor id
context <- rstudioapi::getConsoleEditorContext()
id <- context$id
# send some R code to the console
rstudioapi::insertText(text = "print(1 + 1)", id = id)
# see also: `getActiveEditorContext()`, `getSourceEditorContext()`
You can also modify the cursor position through the use of the setCursorPosition() and setSelectionRanges() APIs.
# put the cursor at the end of the document -- note that here,
# `Inf` is automatically truncated to the actual length of the
# document
rstudioapi::setCursorPosition(Inf)
# select the first 10 even lines in the document
ranges <- lapply(seq(2, by = 2, length.out = 10), function(start) {
rstudioapi::document_range(
c(start, 0),
c(start, Inf)
)
})
rstudioapi::setSelectionRanges(ranges)
See the ?"rstudio-documents" help page for more details.
rstudioapi/inst/doc/dialogs.html 0000644 0001762 0000144 00000027466 13617331500 016505 0 ustar ligges users
File Dialogs
File Dialogs
Using the rstudioapi package, you can request input from the user with various dialogs.
The selectFile() and selectDirectory() APIs allow you to request the name of an existing or non-existing path on the system.
# request the path to an existing .csv file on disk
path <- rstudioapi::selectFile(caption = "Select CSV File",
filter = "CSV Files (*.csv)",
existing = TRUE)
# now, you could read the data using e.g. 'readr::read_csv()'
data <- readr::read_csv(path)
# request a file path (e.g. where you would like to save a new file)
target <- rstudioapi::selectFile(caption = "Save File",
label = "Save",
existing = FALSE)
# save data to the path provided by the user
saveRDS(data, file = target)
Use rstudioapi::askForPassword() to request a password, or other credentials, from a user.
token <- rstudioapi::askForPassword(
prompt = "Please provide your GitHub access token."
)
Use rstudioapi::showDialog() to display an informative dialog to the user. This dialog is used to report some kind of status or information to the user; it does not request any input.
rstudioapi::showDialog(title = "Hello, world!",
message = "You're <b>awesome!</b>",
url = "http://www.example.com")
Interacting with RStudio Projects
Users can create and open RStudio projects using the rstudioapi package.
# open a project in another directory
rstudioapi::openProject("~/projects/t-sne-gene-expression-2017")
# re-open the current project
rstudioapi::openProject()
# initialize an RStudio project (without opening it)
rstudioapi::initializeProject("~/scratch/testbed")
Introduction to rstudioapi
The rstudioapi package provides an interface for interacting with the RStudio IDE with R code. Using rstudioapi, you can:
Examine, manipulate, and save the contents of documents currently open in RStudio,
Create, open, or re-open RStudio projects,
Prompt the user with different kinds of dialogs (e.g. for selecting a file or folder, or requesting a password from the user),
Interact with RStudio terminals,
Interact with the R session associated with the current RStudio instance.
Please see the other articles for more detailed information.
rstudioapi/inst/doc/terminal.html 0000644 0001762 0000144 00000040476 13617331501 016673 0 ustar ligges users
Interacting with Terminals
Interacting with Terminals
The rstudioapi package provides a collection of functions that can be used to interact with the RStudio terminal tab.
There are two primary approaches to using these functions.
Use terminalExecute() to run a specific process with the output shown in a new terminal buffer, without blocking the current R session.
Create, query, and manipulate interactive terminals. This might be used to develop custom terminal behavior via an RStudio addin.
TerminalExecute Scenario
# Start a command with results displayed in a terminal buffer
termId <- rstudioapi::terminalExecute("ping rstudio.com")
# If viewing the result in the terminal buffer is sufficient,
# then no need to do anything else. The command will continue
# running and displaying its results without blocking the R session.
# To obtain the results programmatically, wait for it to finish.
while (is.null(rstudioapi::terminalExitCode(termId))) {
Sys.sleep(0.1)
}
result <- rstudioapi::terminalBuffer(termId)
# Delete the buffer and close the session in the IDE
rstudioapi::terminalKill(termId)
Interative Terminal Scenario
Several concepts are important to understand to make full use of these functions.
Terminal Identifier
Each terminal session has a unique terminal identifier, a required argument for most of the functions. A terminal identifier is generated and returned when a terminal is created via terminalCreate() or terminalExecute(), and identifiers of existing terminals can be obtained via terminalList() or terminalVisible().
Terminal Session
A terminal session is an instance of a terminal that can be displayed in the RStudio terminal tab. A terminal session consists of:
- a unique terminal identifier
- a unique caption shown in the RStudio terminal dropdown (e.g. “Terminal 1”)
- a shell process (e.g. bash) running as a child process of the R session
- zero or more processes running as children of the shell (e.g. commands)
- an xterm-compatible terminal emulator in the terminal tab
- a buffer of output shown in the terminal emulator (can be cleared via
terminalClear())
Busy Terminal
A terminal session with child processes running (excluding the shell), is considered busy and this is reflected in the IDE UI and can be queried with terminalBusy().
Terminal States
In the most common situation, a terminal session has all the above features; however, it is possible for terminals to be in other states.
No shell process or child processes: This happens if the associated R session has been closed (or suspended in the case of an inactive RStudio Server session).
The terminalRunning() function returns TRUE if a terminal is in this state.
If a terminal is not running, it can be started via interacting with it in the RStudio IDE, or via terminalActivate().
# start an interactive terminal using the shell selected in
# RStudio global options
myTerm <- rstudioapi::terminalCreate()
# ....
# sometime later
# ....
if (!rstudioapi::terminalRunning(myTerm)) {
# start the terminal shell back up, but don't bring to front
rstudioapi::terminalActivate(myTerm, show = FALSE)
# wait for it to start
while (!rstudioapi::terminalRunning(myTerm)) {
Sys.sleep(0.1)
}
# send a new command
rstudioapi::terminalSend(myTerm, "echo Hello\n")
}
Running but not loaded in the IDE: On RStudio Server, the web browser can be closed but the R session and any associated terminal sessions keep running. If the web browser is reconnected, each terminal will be redisplayed in the IDE when it is selected. The rstudioapi functions may be used on a terminal in this state; for example, the buffer may still be fetched with terminalBuffer() even if the terminal isn’t loaded in the IDE (so long as the R session is still alive).
Terminated but still visible: Normally the terminal emulator for a given terminal session will close when the shell exits. If the option Close Terminal When Shell Exits is turned off, then the terminal buffer will remain loaded in the RStudio IDE until closed by the user or terminalKill(). Terminals started with terminalExecute() will always remain loaded when they finish running. To test a terminal for this state, terminalExitCode() will return a non-NULL value.
rstudioapi/inst/doc/r-session.html 0000644 0001762 0000144 00000025165 13617331501 017000 0 ustar ligges users
Interacting with the R Session
Interacting with the R Session
Session Interaction
The rstudioapi package allows you to interact with the running R session in a couple useful ways: you can send code to the R console, or restart the R session.
# restart R, then run some code after
rstudioapi::restartSession(command = "print('Welcome back!')")
# send some code to the console and execute it immediately
rstudioapi::sendToConsole("1 + 1", execute = TRUE)
Running at Startup
Typically, code that you want to run at the start of an R session is placed into an .Rprofile file (see Initialization at the Start of a Session for details). However, RStudio’s API hooks are not available until RStudio has fully started up, so most rstudioapi methods will not work inside .Rprofile.
If you want to invoke rstudioapi methods on session startup, use the rstudio.sessionInit hook. For example, to print the RStudio version to the R console when the session begins:
setHook("rstudio.sessionInit", function(newSession) {
if (newSession)
message("Welcome to RStudio ", rstudioapi::getVersion())
}, action = "append")
rstudioapi/inst/doc/projects.Rmd 0000644 0001762 0000144 00000001202 13535525640 016457 0 ustar ligges users ---
title: "Interacting with RStudio Projects"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Interacting with RStudio Projects}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```
Users can create and open RStudio projects using the `rstudioapi` package.
```{r}
# open a project in another directory
rstudioapi::openProject("~/projects/t-sne-gene-expression-2017")
# re-open the current project
rstudioapi::openProject()
# initialize an RStudio project (without opening it)
rstudioapi::initializeProject("~/scratch/testbed")
```
rstudioapi/inst/doc/document-manipulation.Rmd 0000644 0001762 0000144 00000004074 13535525640 021154 0 ustar ligges users ---
title: "Document Manipulation"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Document Manipulation}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup}
knitr::opts_chunk$set(eval = FALSE)
```
The `rstudioapi` package provides a small family of functions that can be used to interact with documents open in an RStudio session. For example, the following code could be used to insert a 'last modified' comment at the start of a document:
```{r}
# construct the text to be inserted
fmt <- "# This document was last modified on %s.\n"
text <- sprintf(fmt, Sys.Date())
# specify a range where this text should be inserted; here,
# we use the first line; that is, the 'range' between the start
# of the first row, and the start of the second row
range <- rstudioapi::document_range(c(1, 0), c(2, 0))
rstudioapi::insertText(range, text)
```
By default, these APIs target the editor instance either currently focused by the user, or when no such editor is currently focused, the last focused editor. If you need to target a specific editor instance (for example, you want to write code that inserts text into the console), you can use `getConsoleEditorContext()` to get the `id` for the console editor:
```{r}
# get console editor id
context <- rstudioapi::getConsoleEditorContext()
id <- context$id
# send some R code to the console
rstudioapi::insertText(text = "print(1 + 1)", id = id)
# see also: `getActiveEditorContext()`, `getSourceEditorContext()`
```
You can also modify the cursor position through the use of the `setCursorPosition()` and `setSelectionRanges()` APIs.
```{r}
# put the cursor at the end of the document -- note that here,
# `Inf` is automatically truncated to the actual length of the
# document
rstudioapi::setCursorPosition(Inf)
# select the first 10 even lines in the document
ranges <- lapply(seq(2, by = 2, length.out = 10), function(start) {
rstudioapi::document_range(
c(start, 0),
c(start, Inf)
)
})
rstudioapi::setSelectionRanges(ranges)
```
See the `?"rstudio-documents"` help page for more details.
rstudioapi/inst/doc/document-manipulation.R 0000644 0001762 0000144 00000002723 13617331500 020621 0 ustar ligges users ## ----setup--------------------------------------------------------------------
knitr::opts_chunk$set(eval = FALSE)
## -----------------------------------------------------------------------------
# # construct the text to be inserted
# fmt <- "# This document was last modified on %s.\n"
# text <- sprintf(fmt, Sys.Date())
#
# # specify a range where this text should be inserted; here,
# # we use the first line; that is, the 'range' between the start
# # of the first row, and the start of the second row
# range <- rstudioapi::document_range(c(1, 0), c(2, 0))
# rstudioapi::insertText(range, text)
## -----------------------------------------------------------------------------
# # get console editor id
# context <- rstudioapi::getConsoleEditorContext()
# id <- context$id
#
# # send some R code to the console
# rstudioapi::insertText(text = "print(1 + 1)", id = id)
#
# # see also: `getActiveEditorContext()`, `getSourceEditorContext()`
## -----------------------------------------------------------------------------
# # put the cursor at the end of the document -- note that here,
# # `Inf` is automatically truncated to the actual length of the
# # document
# rstudioapi::setCursorPosition(Inf)
#
# # select the first 10 even lines in the document
# ranges <- lapply(seq(2, by = 2, length.out = 10), function(start) {
# rstudioapi::document_range(
# c(start, 0),
# c(start, Inf)
# )
# })
# rstudioapi::setSelectionRanges(ranges)
rstudioapi/inst/resources/ 0000755 0001762 0000144 00000000000 13535525640 015434 5 ustar ligges users rstudioapi/inst/resources/bug-report.md 0000644 0001762 0000144 00000001104 13535525640 020040 0 ustar ligges users
### System details
RStudio Edition : ${RSTUDIO_EDITION}
RStudio Version : ${RSTUDIO_VERSION}
OS Version : ${OS_VERSION}
R Version : ${R_VERSION}
### Steps to reproduce the problem
### Describe the problem in detail
### Describe the behavior you expected