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 startwhile (!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/terminal.R 0000644 0001762 0000144 00000002653 13154303177 016127 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/projects.Rmd 0000644 0001762 0000144 00000001202 13134175746 016462 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/projects.html 0000644 0001762 0000144 00000021325 13154303177 016705 0 ustar ligges users
Interacting with RStudio Projects
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")
rstudioapi/inst/doc/dialogs.R 0000644 0001762 0000144 00000002375 13154303176 015736 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 00000000641 13154303177 016231 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)
rstudioapi/inst/doc/r-session.Rmd 0000644 0001762 0000144 00000001233 13147601347 016552 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)
```
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)
```
rstudioapi/inst/doc/r-session.html 0000644 0001762 0000144 00000021361 13154303177 016776 0 ustar ligges users
Interacting with the R Session
Interacting with the R Session
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)
rstudioapi/inst/doc/projects.R 0000644 0001762 0000144 00000000737 13154303177 016146 0 ustar ligges users ## ----setup, include=FALSE------------------------------------------------
knitr::opts_chunk$set(eval = FALSE)
## ------------------------------------------------------------------------
# # 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/introduction.html 0000644 0001762 0000144 00000015037 13154303177 017600 0 ustar ligges users
Introduction to rstudioapi
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/dialogs.Rmd 0000644 0001762 0000144 00000003166 13147601230 016250 0 ustar ligges users ---
title: "File Dialogs"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{File Dialogs}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```
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.
```{r}
# 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.
```{r}
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.
```{r}
rstudioapi::showDialog(title = "Hello, world!",
message = "You're awesome!",
url = "http://www.example.com")
```
rstudioapi/inst/doc/introduction.Rmd 0000644 0001762 0000144 00000001401 13147605407 017347 0 ustar ligges users ---
title: "Introduction to rstudioapi"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Introduction to rstudioapi}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
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/document-manipulation.R 0000644 0001762 0000144 00000002677 13154303177 020636 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/doc/terminal.Rmd 0000644 0001762 0000144 00000011165 13153571034 016444 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.html 0000644 0001762 0000144 00000025274 13154303176 016504 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 usersaveRDS(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/inst/doc/document-manipulation.Rmd 0000644 0001762 0000144 00000004074 13147601244 021146 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.html 0000644 0001762 0000144 00000027424 13154303177 021376 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/NAMESPACE 0000644 0001762 0000144 00000003640 13147600706 013663 0 ustar ligges users # Generated by roxygen2: do not edit by hand
S3method(as.document_position,default)
S3method(as.document_position,document_position)
S3method(as.document_range,default)
S3method(as.document_range,document_range)
S3method(format,document_position)
S3method(format,document_range)
S3method(primary_selection,document_context)
S3method(primary_selection,document_selection)
S3method(print,document_context)
S3method(print,document_position)
S3method(print,document_range)
S3method(print,document_selection)
export(as.document_position)
export(as.document_range)
export(askForPassword)
export(callFun)
export(createProjectTemplate)
export(documentSave)
export(documentSaveAll)
export(document_position)
export(document_range)
export(findFun)
export(getActiveDocumentContext)
export(getActiveProject)
export(getConsoleEditorContext)
export(getPersistentValue)
export(getSourceEditorContext)
export(getThemeInfo)
export(getVersion)
export(hasColorConsole)
export(hasFun)
export(initializeProject)
export(insertText)
export(is.document_position)
export(is.document_range)
export(isAvailable)
export(modifyRange)
export(navigateToFile)
export(openProject)
export(previewRd)
export(primary_selection)
export(readPreference)
export(restartSession)
export(savePlotAsImage)
export(selectDirectory)
export(selectFile)
export(sendToConsole)
export(setCursorPosition)
export(setDocumentContents)
export(setPersistentValue)
export(setSelectionRanges)
export(showDialog)
export(showPrompt)
export(showQuestion)
export(sourceMarkers)
export(terminalActivate)
export(terminalBuffer)
export(terminalBusy)
export(terminalClear)
export(terminalContext)
export(terminalCreate)
export(terminalExecute)
export(terminalExitCode)
export(terminalKill)
export(terminalList)
export(terminalRunning)
export(terminalSend)
export(terminalVisible)
export(updateDialog)
export(verifyAvailable)
export(versionInfo)
export(viewer)
export(writePreference)
importFrom(utils,capture.output)
rstudioapi/NEWS.md 0000644 0001762 0000144 00000002036 13147600706 013540 0 ustar ligges users # rstudioapi 0.7
* `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/R/ 0000755 0001762 0000144 00000000000 13153571034 012640 5 ustar ligges users rstudioapi/R/utils.R 0000644 0001762 0000144 00000000000 13122012571 014101 0 ustar ligges users rstudioapi/R/terminal.R 0000644 0001762 0000144 00000022760 13153571034 014605 0 ustar ligges users
#' Send Text to a Terminal
#'
#' Send text to an existing terminal.
#'
#' @param id The terminal id. The \code{id} is obtained from
#' \code{\link{terminalList}()}, \code{\link{terminalVisible}()},
#' \code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.
#' @param text Character vector containing text to be inserted.
#'
#' @note The \code{terminalSend} function was added in version 1.1.350 of RStudio.
#'
#' @examples
#' \dontrun{
#' termId <- rstudioapi::terminalCreate()
#' rstudioapi::terminalSend(termId, 'ls -l\n')
#' }
#'
#' @export
terminalSend <- function(id, text) {
callFun("terminalSend", id, text)
}
#' Clear Terminal Buffer
#'
#' Clears the buffer for specified terminal.
#'
#' @param id The terminal id. The \code{id} is obtained from
#' \code{\link{terminalList}()}, \code{\link{terminalVisible}()},
#' \code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.
#'
#' @note The \code{terminalClear} function was added in version 1.1.350 of RStudio.
#'
#' @examples
#' \dontrun{
#' termId <- rstudioapi::terminalCreate()
#' rstudioapi::terminalSend(termId, 'ls -l\n')
#' Sys.sleep(3)
#' rstudioapi::terminalClear(termId)
#' }
#'
#' @export
terminalClear <- function(id) {
callFun("terminalClear", id)
}
#' Create a Terminal
#'
#' Create a new Terminal.
#'
#' @param caption The desired terminal caption. When \code{NULL} or blank,
#' the terminal caption will be chosen by the system.
#' @param show If \code{FALSE}, terminal won't be brought to front.
#'
#' @return The terminal identifier as a character vector (\code{NULL} if
#' unable to create the terminal or the given terminal caption is already
#' in use).
#'
#' @note The \code{terminalCreate} function was added in version 1.1.350 of RStudio.
#'
#' @examples
#' \dontrun{
#' termId <- rstudioapi::terminalCreate('My Terminal')
#' }
#'
#' @export
terminalCreate <- function(caption = NULL, show = TRUE) {
callFun("terminalCreate", caption, show)
}
#' Is Terminal Busy
#'
#' Are terminals reporting that they are busy?
#'
#' @param id The terminal id. The \code{id} is obtained from
#' \code{\link{terminalList}()}, \code{\link{terminalVisible}()},
#' \code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.
#'
#' @return a boolean
#'
#' @note The \code{terminalBusy} function was added in version 1.1.350 of RStudio.
#'
#' @examples
#' \dontrun{
#' # create a hidden terminal and run a lengthy command
#' termId <- rstudioapi::terminalCreate(show = FALSE)
#' rstudioapi::terminalSend(termId, "sleep 5\n")
#'
#' # wait until a busy terminal is finished
#' while (rstudioapi::terminalBusy(termId)) {
#' Sys.sleep(0.1)
#' }
#' print("Terminal available")
#' }
#' @export
terminalBusy <- function(id) {
callFun("terminalBusy", id)
}
#' Is Terminal Running
#'
#' Does a terminal have a process associated with it? If the R session is
#' restarted after a terminal has been created, the terminal will not
#' restart its shell until it is displayed either via the user
#' interface, or via \code{\link{terminalActivate}()}.
#'
#' @param id The terminal id. The \code{id} is obtained from
#' \code{\link{terminalList}()}, \code{\link{terminalVisible}()},
#' \code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.
#'
#' @return a boolean
#'
#' @note The \code{terminalRunning} function was added in version 1.1.350 of RStudio.
#'
#' @examples
#' \dontrun{
#' # termId has a handle to a previously created terminal
#' # make sure it is still running before we send it a command
#' if (!rstudioapi::terminalRunning(termId)) {
#' rstudioapi::terminalActivate(termId))
#'
#' # wait for it to start
#' while (!rstudioapi::terminalRunning(termId)) {
#' Sys.sleep(0.1)
#' }
#'
#' terminalSend(termId, "echo Hello\n")
#' }
#' }
#' @export
terminalRunning <- function(id) {
callFun("terminalRunning", id)
}
#' Get All Terminal Ids
#'
#' Return a character vector containing all the current terminal identifiers.
#'
#' @return The terminal identifiers as a character vector.
#'
#' @note The \code{terminalList} function was added in version 1.1.350 of RStudio.
#'
#' @export
terminalList <- function() {
callFun("terminalList")
}
#' Retrieve Information about RStudio Terminals
#'
#' Returns information about RStudio terminal instances.
#'
#' @param id The terminal id. The \code{id} is obtained from
#' \code{\link{terminalList}()}, \code{\link{terminalVisible}()},
#' \code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.
#'
#' @return A \code{list} with elements:
#' \tabular{ll}{
#' \code{handle} \tab the internal handle\cr
#' \code{caption} \tab caption\cr
#' \code{title} \tab title set by the shell\cr
#' \code{working_dir} \tab working directory\cr
#' \code{shell} \tab shell type\cr
#' \code{running} \tab is terminal process executing\cr
#' \code{busy} \tab is terminal running a program\cr
#' \code{exit_code} \tab process exit code or NULL\cr
#' \code{connection} \tab websockets or rpc\cr
#' \code{sequence} \tab creation sequence\cr
#' \code{lines} \tab lines of text in terminal buffer\cr
#' \code{cols} \tab columns in terminal\cr
#' \code{rows} \tab rows in terminal\cr
#' \code{pid} \tab process id of terminal shell\cr
#' \code{full_screen} \tab full screen program running\cr
#' }
#'
#' @note The \code{terminalContext} function was added in version 1.1.350 of RStudio.
#'
#' @examples
#' \dontrun{
#' termId <- rstudioapi::terminalCreate("example", show = FALSE)
#' View(rstudioapi::terminalContext(termId))
#'
#' }
#'
#' @export
terminalContext <- function(id) {
callFun("terminalContext", id)
}
#' Activate Terminal
#'
#' Ensure terminal is running and optionally bring to front in RStudio.
#'
#' @param id The terminal id. The \code{id} is obtained from
#' \code{\link{terminalList}()}, \code{\link{terminalVisible}()},
#' \code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.
#' If NULL, the terminal tab will be selected but no specific terminal
#' will be chosen.
#' @param show If TRUE, bring the terminal to front in RStudio.
#'
#' @note The \code{terminalActivate} function was added in version 1.1.350 of RStudio.
#'
#' @examples
#' \dontrun{
#' # create a hidden terminal and run a lengthy command
#' termId = rstudioapi::terminalCreate(show = FALSE)
#' rstudioapi::terminalSend(termId, "sleep 5\n")
#'
#' # wait until a busy terminal is finished
#' while (rstudioapi::terminalBusy(termId)) {
#' Sys.sleep(0.1)
#' }
#' print("Terminal available")#'
#'
#' rstudioapi::terminalActivate(termId)
#' }
#'
#' @export
terminalActivate <- function(id = NULL, show = TRUE) {
callFun("terminalActivate", id, show)
}
#' Get Terminal Buffer
#'
#' Returns contents of a terminal buffer.
#'
#' @param id The terminal id. The \code{id} is obtained from
#' \code{\link{terminalList}()}, \code{\link{terminalVisible}()},
#' \code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.
#' @param stripAnsi If FALSE, don't strip out Ansi escape sequences before returning
#' terminal buffer.
#'
#' @return The terminal contents, one line per row.
#'
#' @note The \code{terminalBuffer} function was added in version 1.1.350 of RStudio.
#'
#' @export
terminalBuffer <- function(id, stripAnsi = TRUE) {
callFun("terminalBuffer", id, stripAnsi)
}
#' Kill Terminal
#'
#' Kill processes and close a terminal.
#'
#' @param id The terminal id. The \code{id} is obtained from
#' \code{\link{terminalList}()}, \code{\link{terminalVisible}()},
#' \code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.
#'
#' @note The \code{terminalKill} function was added in version 1.1.350 of RStudio.
#'
#' @export
terminalKill<- function(id) {
callFun("terminalKill", id)
}
#' Get Visible Terminal
#'
#' @return Terminal identifier selected in the client, if any.
#'
#' @note The \code{terminalVisible} function was added in version 1.1.350 of RStudio.
#'
#' @export
terminalVisible <- function() {
callFun("terminalVisible")
}
#' Execute Command
#'
#' Execute a command, showing results in the terminal pane.
#'
#' @param command System command to be invoked, as a character string.
#' @param workingDir Working directory for command
#' @param env Vector of name=value strings to set environment variables
#' @param show If FALSE, terminal won't be brought to front
#'
#' @return The terminal identifier as a character vector (\code{NULL} if
#' unable to create the terminal).
#'
#' @note The \code{terminalExecute} function was added in version 1.1.350 of RStudio.
#'
#' @examples
#' \dontrun{
#' termId <- rstudioapi::terminalExecute(
#' command = 'echo $HELLO && echo $WORLD',
#' workingDir = '/usr/local',
#' env = c('HELLO=WORLD', 'WORLD=EARTH'),
#' show = FALSE)
#'
#' while (is.null(rstudioapi::terminalExitCode(termId))) {
#' Sys.sleep(0.1)
#' }
#'
#' result <- terminalBuffer(termId)
#' terminalKill(termId)
#' print(result)
#' }
#'
#' @export
terminalExecute <- function(command,
workingDir = NULL,
env = character(),
show = TRUE) {
callFun("terminalExecute", command, workingDir, env, show)
}
#' Terminal Exit Code
#'
#' Get exit code of terminal process, or NULL if still running.
#'
#' @param id The terminal id. The \code{id} is obtained from
#' \code{\link{terminalList}()}, \code{\link{terminalVisible}()},
#' ,\code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.
#'
#' @return The exit code as an integer vector, or NULL if process still running.
#'
#' @note The \code{terminalExitCode} function was added in version 1.1.350 of RStudio.
#'
#' @export
terminalExitCode <- function(id) {
callFun("terminalExitCode", id)
}
rstudioapi/R/document-api.R 0000644 0001762 0000144 00000011574 13124550757 015367 0 ustar ligges users #' Interact with Documents open in RStudio
#'
#' Use these functions to interact with documents open in RStudio.
#'
#' @param location An object specifying the positions, or ranges, wherein
#' text should be inserted. See \bold{Details} for more information.
#'
#' @param 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.
#'
#' @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.
#'
#' @param position The cursor position, typically created through
#' \code{\link{document_position}()}.
#'
#' @param ranges A list of one or more ranges, typically created
#' through \code{\link{document_range}()}.
#'
#' @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.
#'
#' @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.
#'
#' @name rstudio-documents
NULL
#' @name rstudio-documents
#' @export
insertText <- function(location, text, id = NULL) {
callFun("insertText", location, text, id)
}
#' @name rstudio-documents
#' @export
modifyRange <- insertText
#' @name rstudio-documents
#' @export
setDocumentContents <- function(text, id = NULL) {
location <- document_range(
document_position(1, 1),
document_position(Inf, 1)
)
insertText(location, text, id)
}
#' @name rstudio-documents
#' @export
setCursorPosition <- function(position, id = NULL) {
callFun("setSelectionRanges", position, id)
}
#' @name rstudio-documents
#' @export
setSelectionRanges <- function(ranges, id = NULL) {
callFun("setSelectionRanges", ranges, id)
}
#' @name rstudio-documents
#' @export
documentSave <- function(id = NULL) {
callFun("documentSave", id)
}
#' @name rstudio-documents
#' @export
documentSaveAll <- function() {
callFun("documentSaveAll")
}
#' Retrieve Information about an RStudio Editor
#'
#' Returns information about an RStudio editor.
#'
#' The \code{selection} field returned is a list of document selection objects.
#' A document selection is just a pairing of a document \code{range}, and the
#' \code{text} within that range.
#'
#' @note
#' The \code{getActiveDocumentContext} function was added with version 0.99.796
#' of RStudio, while the \code{getSourceEditorContext} and the \code{getConsoleEditorContext}
#' functions were added with version 0.99.1111.
#'
#' @return A \code{list} with elements:
#' \tabular{ll}{
#' \code{id} \tab The document ID.\cr
#' \code{path} \tab The path to the document on disk.\cr
#' \code{contents} \tab The contents of the document.\cr
#' \code{selection} \tab A \code{list} of selections. See \bold{Details} for more information.\cr
#' }
#'
#' @rdname rstudio-editors
#' @name rstudio-editors
#' @export
getActiveDocumentContext <- function() {
getDocumentContext("getActiveDocumentContext")
}
#' @name rstudio-editors
#' @export
getSourceEditorContext <- function() {
getDocumentContext("getSourceEditorContext")
}
#' @name rstudio-editors
#' @export
getConsoleEditorContext <- function() {
getDocumentContext("getConsoleEditorContext")
}
rstudioapi/R/dialogs.R 0000644 0001762 0000144 00000006425 13102441273 014407 0 ustar ligges users #' Show Dialog Box
#'
#' Shows a dialog box with a given title and contents.
#'
#' @param title The title to display in the dialog box.
#'
#' @param message A character vector with the contents to display in
#' the main dialog area. Contents can contain the following HTML tags:
#' "p", "em", "strong", "b" and "i".
#'
#' @param url And optional url to display under the \code{message}.
#'
#' @details
#'
#' \preformatted{
#' showDialog("A dialog", "Showing bold text in the message.")
#' }
#'
#' @note The \code{showDialog} function was added in version 1.1.67 of RStudio.
#'
#' @export
showDialog <- function(title, message, url = NULL) {
callFun("showDialog", title, message, url)
}
#' Updates a Dialog Box
#'
#' Updates specific properties from the current dialog box.
#'
#' @param ... Named parameters and values to update a dialog box.
#'
#' @details
#'
#' Currently, the only dialog with support for this action is the
#' New Connection dialog in which the code preview can be
#' updated through this API.
#'
#' \preformatted{
#' updateDialog(code = "con <- NULL")
#' }
#'
#' @note The \code{updateDialog} function was added in version 1.1.67 of RStudio.
#'
#' @export
updateDialog <- function(...) {
callFun("updateDialog", ...)
}
#' Show Prompt Dialog Box
#'
#' Shows a dialog box with a prompt field.
#'
#' @param title The title to display in the dialog box.
#'
#' @param message A character vector with the contents to display in
#' the main dialog area.
#'
#' @param default An optional character vector that fills the prompt field
#' with a default value.
#'
#' @note The \code{showPrompt} function was added in version 1.1.67 of RStudio.
#'
#' @export
showPrompt <- function(title, message, default = NULL) {
callFun("showPrompt", title, message, default)
}
#' Show Question Dialog Box
#'
#' Shows a dialog box asking a question.
#'
#' @param title The title to display in the dialog box.
#'
#' @param message A character vector with the contents to display in
#' the main dialog area.
#'
#' @param ok And optional character vector that overrides the caption for
#' the OK button.
#'
#' @param cancel An optional character vector that overrides the caption for
#' the Cancel button.
#'
#' @note The \code{showQuestion} function was added in version 1.1.67 of RStudio.
#'
#' @export
showQuestion <- function(title, message, ok = NULL, cancel = NULL) {
callFun("showQuestion", title, message, ok, cancel)
}
#' Read Preference
#'
#' Reads a user interface preference, useful to remember preferences across
#' different r sessions for the same user.
#'
#' @param name The name of the preference.
#'
#' @param default The default value to use when the preference is not available.
#'
#' @note The \code{readPreference} function was added in version 1.1.67 of RStudio.
#'
#' @export
readPreference <- function(name, default) {
callFun("readPreference", name, default)
}
#' Write Preference
#'
#' Writes a user interface preference, useful to remember preferences across
#' different r sessions for the same user.
#'
#' @param name The name of the preference.
#'
#' @param value The value of the preference.
#'
#' @note The \code{writePreference} function was added in version 1.1.67 of RStudio.
#'
#' @export
writePreference <- function(name, value) {
callFun("writePreference", name, value)
}
rstudioapi/R/themes.R 0000644 0001762 0000144 00000000553 13134170233 014246 0 ustar ligges users #' Retrieve Themes
#'
#' Retrieves a list with themes information. Currently, \code{editor} as
#' the theme used under the code editor, \code{global} as the global theme
#' applied to the main user interface in RStudio and \code{dark} when
#' the user interface is optimized for dark themes.
#'
#' @export
getThemeInfo <- function() {
callFun("getThemeInfo")
}
rstudioapi/R/code.R 0000644 0001762 0000144 00000006661 13102441273 013701 0 ustar ligges users #' Check if RStudio is running.
#'
#' @return \code{isAvailable} a boolean; \code{verifyAvailable} an error message
#' if RStudio is not running
#' @param version_needed An optional version specification. If supplied,
#' ensures that RStudio is at least that version.
#' @export
#' @examples
#' rstudioapi::isAvailable()
#' \dontrun{rstudioapi::verifyAvailable()}
isAvailable <- function(version_needed = NULL) {
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, ...) {
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/R/stubs.R 0000644 0001762 0000144 00000014172 13124551103 014121 0 ustar ligges users
#' @export
versionInfo <- function() {
callFun("versionInfo")
}
#' @export
previewRd <- function(rdFile) {
callFun("previewRd", rdFile)
}
#' @export
viewer <- function(url, height = NULL) {
callFun("viewer", url, height = height)
}
#' @export
sourceMarkers <- function(name, markers, basePath = NULL,
autoSelect = c("none", "first", "error")) {
callFun("sourceMarkers", name, markers, basePath, autoSelect)
}
#' @export
navigateToFile <- function(file, line = -1L, column = -1L) {
callFun("navigateToFile", file, as.integer(line), as.integer(column))
}
#' @export
askForPassword <- function(prompt = "Please enter your password") {
callFun("askForPassword", prompt)
}
#' @export
getActiveProject <- function() {
callFun("getActiveProject")
}
#' Save Active RStudio Plot as an Image
#'
#' Save the currnently active RStudio as an image file.
#'
#' @param file Target filename
#' @param format Image format ("png", "jpeg", "bmp", "tiff", "emf", "svg", or "eps")
#' @param height Image height in pixels
#' @param width Image width in pixels
#'
#' @note The \code{savePlotAsImage} function was introduced in RStudio 1.1.57
#'
#' @export
savePlotAsImage <- function(file,
format = c("png", "jpeg", "bmp", "tiff", "emf", "svg", "eps"),
width,
height) {
format <- match.arg(format)
callFun("savePlotAsImage", file, format, width, height)
}
#' Send Code to the R Console
#'
#' Send code to the R console and optionally execute it.
#'
#' @param code Character vector containing code to be executed.
#' @param execute \code{TRUE} to execute the code immediately.
#'
#' @note The \code{sendToConsole} function was added in version 0.99.787 of RStudio.
#'
#' @examples
#' \dontrun{
#' rstudioapi::sendToConsole(".Platform", execute = TRUE)
#' }
#'
#' @export
sendToConsole <- function (code, execute = TRUE) {
callFun("sendToConsole", code, TRUE, execute, TRUE)
}
#' Persistent Keys and Values
#'
#' Store persistent keys and values. Storage is per-project, if there is
#' no project currently active then a global store is used.
#'
#' @param name Key name
#' @param value Key value
#' @return The stored value as a character vector (\code{NULL} if no value
#' of the specified name is available).
#'
#' @note The \code{setPersistentValue} and \code{getPersistentValue} functions
#' were added in version 1.1.57 of RStudio.
#'
#' @name persistent-values
#' @export
setPersistentValue <- function(name, value) {
callFun("setPersistentValue", name, value)
}
#' @rdname persistent-values
#' @export
getPersistentValue <- function(name) {
callFun("getPersistentValue", name)
}
#' Check if Console Supports ANSI Color Escapes
#'
#' @return a boolean
#'
#' @examples
#' \dontrun{
#' if (rstudioapi::hasColorConsole()) {
#' message("RStudio console supports ANSI color sequences.")
#' }
#' }
#'
#' @note The \code{hasColorConsole} function was added in version 1.1.216
#' of RStudio.
#'
#' @export
hasColorConsole <- function() {
callFun("getConsoleHasColor")
}
#' Restart the R Session
#'
#' Restart the RStudio \R session.
#'
#' @param command An \R command (as a string) to be run
#' after restarting \R.
#'
#' @note The \code{restartSession} function was added in version 1.1.281
#' of RStudio.
#'
#' @export
restartSession <- function(command = "") {
callFun("restartSession", command)
}
#' Select a File / Folder
#'
#' Prompt the user for the path to a file or folder, using the system
#' file dialogs with RStudio Desktop, and RStudio's own web dialogs
#' with RStudio Server.
#'
#' When the selected file resolves within the user's home directory,
#' RStudio will return an aliased path -- that is, prefixed with \code{~/}.
#'
#' @param caption The window title.
#' @param label The label to use for the 'Accept' / 'OK' button.
#' @param path The initial working directory, from which the file dialog
#' should begin browsing. When \code{NULL}, defaults to the current RStudio
#' project directory.
#' @param filter A glob filter, to be used when attempting to open a file
#' with a particular extension. For example, to scope the dialog to
#' \R files, one could use \code{R Files (*.R)} here.
#' @param existing Boolean; should the file dialog limit itself to existing
#' files on the filesystem, or allow the user to select the path to a new file?
#'
#' @note The \code{selectFile} and \code{selectDirectory} functions were
#' added in version 1.1.287 of RStudio.
#'
#' @name file-dialogs
NULL
#' @name file-dialogs
#' @export
selectFile <- function(caption = "Select File",
label = "Select",
path = NULL,
filter = NULL,
existing = TRUE)
{
callFun("selectFile", caption, label, path, filter, existing)
}
#' @name file-dialogs
#' @export
selectDirectory <- function(caption = "Select Directory",
label = "Select",
path = NULL)
{
callFun("selectFile", caption, label, path)
}
#' Open a Project in RStudio
#'
#' Initialize and open RStudio projects.
#'
#' Calling \code{openProject()} without arguments effectively re-opens the
#' currently open project in RStudio. When switching projects, users will
#' be prompted to save any unsaved files; alternatively, you can explicitly
#' save any open documents using \code{\link{documentSaveAll}()}.
#'
#' @param path Either the path to an existing \code{.Rproj} file, or a path
#' to a directory in which a new project should be initialized and opened.
#' @param newSession Boolean; should the project be opened in a new session,
#' or should the current RStudio session switch to that project? Note that
#' \code{TRUE} values are only supported with RStudio Desktop and RStudio
#' Server Pro.
#'
#' @note The \code{openProject} and \code{initializeProject} functions were
#' added in version 1.1.287 of RStudio.
#'
#' @name projects
NULL
#' @name projects
#' @export
openProject <- function(path = NULL, newSession = FALSE) {
callFun("openProject", path, newSession)
}
#' @name projects
#' @export
initializeProject <- function(path = getwd()) {
callFun("initializeProject", path)
}
rstudioapi/R/templates.R 0000644 0001762 0000144 00000006364 13102441665 014772 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/document-methods.R 0000644 0001762 0000144 00000012324 13122012571 016234 0 ustar ligges users #' Create a Document Position
#'
#' Creates a \code{document_position}, which can be used to indicate e.g. the
#' row + column location of the cursor in a document.
#'
#' @param x An object coercable to \code{document_position}.
#' @param row The row (using 1-based indexing).
#' @param column The column (using 1-based indexing).
#'
#' @name document_position
#'
#' @export
#' @family location
document_position <- function(row, column) {
structure(c(row = as.numeric(row), column = as.numeric(column)),
class = "document_position")
}
#' @rdname document_position
#' @export
is.document_position <- function(x) {
inherits(x, "document_position")
}
#' @name document_position
#' @export
as.document_position <- function(x) {
UseMethod("as.document_position")
}
#' @export
as.document_position.document_position <- function(x) {
x
}
#' @export
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)
document_position(row = x[[1]], column = x[[2]])
}
#' @export
format.document_position <- function(x, ...) {
paste("[", paste(x, collapse = ", "), "]", sep = "")
}
#' @export
print.document_position <- function(x, ...) {
cat("Document Position: ", format(x), "\n", sep = "")
}
#' Create a Range
#'
#' A \code{document_range} is a pair of \code{\link{document_position}} objects,
#' with each position indicating the \code{start} and \code{end} of the range,
#' respectively.
#'
#' @param x An object coercable to \code{document_range}.
#' @param start A \code{\link{document_position}} indicating the start of the
#' range.
#' @param end A \code{\link{document_position}} indicating the end of the range.
#'
#' @return An \R \code{list} with class \code{document_range} and fields:
#'
#' \tabular{ll}{
#' \code{start:}\tab The start position.\cr
#' \code{end:}\tab The end position.\cr
#' }
#'
#' @name document_range
#'
#' @export
document_range <- function(start, end = NULL) {
# Allow users to write e.g. 'document_range(c(1, 2, 3, 4))';
# ie, ignore using the 'end' argument
if (is.null(end)) {
if (length(start) != 4 || !is.numeric(start))
stop("invalid range specification", call. = FALSE)
end <- start[3:4]
start <- start[1:2]
}
structure(list(start = as.document_position(start),
end = as.document_position(end)),
class = "document_range")
}
#' @name document_range
#' @export
is.document_range <- function(x) {
inherits(x, "document_range")
}
#' @name document_range
#' @export
as.document_range <- function(x) {
UseMethod("as.document_range")
}
#' @export
as.document_range.document_range <- function(x) {
x
}
#' @export
as.document_range.default <- function(x) {
document_range(x)
}
#' @export
format.document_range <- function(x, ...) {
startPos <- as.document_position(x$start)
endPos <- as.document_position(x$end)
paste(format(startPos, ...), "--", format(endPos, ...))
}
#' @export
print.document_range <- function(x, ...) {
cat("Document Range:",
"\n- Start: ", format(x$start),
"\n- End: ", format(x$end),
"\n", sep = "")
}
as.document_selection <- function(x) {
invalidMsg <- "'x' should be a list of {range, text} pairs"
if (!is.list(x))
stop(invalidMsg, call. = FALSE)
result <- lapply(x, function(el) {
named <- all(c("range", "text") %in% names(el))
if (!named)
stop(invalidMsg, call. = FALSE)
Encoding(el$text) <- "UTF-8"
list(
range = as.document_range(el$range),
text = el$text
)
})
structure(result, class = "document_selection")
}
formatSelection <- function(x) {
vapply(x, FUN.VALUE = character(1), function(el) {
rng <- format(el$range)
txt <- formatText(el$text)
paste(rng, ": '", txt, "'", sep = "")
})
}
#' @export
print.document_selection <- function(x, ...) {
cat("Document Selection:", sep = "")
formatted <- formatSelection(x)
lapply(formatted, function(el) {
cat("\n- ", el, sep = "")
})
cat("\n", sep = "")
}
#' @export
print.document_context <- function(x, ...) {
cat("Document Context: ",
"\n- id: '", x$id, "'",
"\n- path: '", x$path, "'",
"\n- contents: <", length(x$contents), " rows>",
"\n", sep = "")
print(x$selection)
}
#' Extract the Primary Selection
#'
#' By default, functions returning a document context will
#' return a list of selections, including both the 'primary'
#' selection and also 'other' selections (e.g. to handle the
#' case where a user might have multiple cursors active).
#' Use \code{primary_selection()} to extract the primary
#' selection.
#'
#' @param x A document context, or a selection.
#' @param ... Optional arguments (currently ignored).
#'
#' @export
primary_selection <- function(x, ...) {
UseMethod("primary_selection")
}
#' @export
primary_selection.document_context <- function(x, ...) {
primary_selection(x$selection)
}
#' @export
primary_selection.document_selection <- function(x, ...) {
x[[1]]
}
getDocumentContext <- function(fn) {
context <- callFun(fn)
Encoding(context$path) <- "UTF-8"
Encoding(context$contents) <- "UTF-8"
context$selection <- as.document_selection(context$selection)
structure(context, class = "document_context")
}
rstudioapi/R/misc.R 0000644 0001762 0000144 00000000310 13102441273 013703 0 ustar ligges users #' @importFrom utils capture.output
formatText <- function(text, n = 20L, truncated = "<...>") {
result <- if (nchar(text) < n)
text
else
paste(text, truncated)
encodeString(result)
}
rstudioapi/vignettes/ 0000755 0001762 0000144 00000000000 13154303200 014434 5 ustar ligges users rstudioapi/vignettes/projects.Rmd 0000644 0001762 0000144 00000001202 13134175746 016750 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/vignettes/r-session.Rmd 0000644 0001762 0000144 00000001233 13147601347 017040 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)
```
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)
```
rstudioapi/vignettes/dialogs.Rmd 0000644 0001762 0000144 00000003166 13147601230 016536 0 ustar ligges users ---
title: "File Dialogs"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{File Dialogs}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```
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.
```{r}
# 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.
```{r}
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.
```{r}
rstudioapi::showDialog(title = "Hello, world!",
message = "You're awesome!",
url = "http://www.example.com")
```
rstudioapi/vignettes/introduction.Rmd 0000644 0001762 0000144 00000001401 13147605407 017635 0 ustar ligges users ---
title: "Introduction to rstudioapi"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Introduction to rstudioapi}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
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/vignettes/terminal.Rmd 0000644 0001762 0000144 00000011165 13153571034 016732 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/vignettes/document-manipulation.Rmd 0000644 0001762 0000144 00000004074 13147601244 021434 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/MD5 0000644 0001762 0000144 00000010571 13154336432 012755 0 ustar ligges users 9c760c928788bde1e31a2ddb299e0240 *DESCRIPTION
2491c4039e00be047cce99c452d3fd00 *LICENSE
f376e7fab407e6942b31e0b4e696968c *NAMESPACE
c098e68f7585f40bb442fa44a1fd4e13 *NEWS.md
40d7e575519c656e3b0dc640f5670103 *R/code.R
ebc1e68f4e1cb629489fcb7ab115d4c2 *R/dialogs.R
2da0b7c2b10251ed9124679fc8299855 *R/document-api.R
a9d3a435533f353c85c27e240df82691 *R/document-methods.R
627c1993928ca912b11e33ee38fd7e15 *R/misc.R
11e7e0efeec4dbe9374d7ab59cf774eb *R/stubs.R
4ff4a8ad43716c847b75431bf5917b6d *R/templates.R
98f5e22aee067de10ac911ea7537ebb6 *R/terminal.R
285d1a9c64689bd21ea41eef0f969bb2 *R/themes.R
d41d8cd98f00b204e9800998ecf8427e *R/utils.R
6ac3d92861c5d04d889675e8dee5c914 *build/vignette.rds
7cc8f3e74401cc4d6243e7e17a35f3d0 *inst/doc/dialogs.R
01f5841a3d3d9249f0b6509697189d5e *inst/doc/dialogs.Rmd
2ef129bd751172a689b84eb03a5b9112 *inst/doc/dialogs.html
a26f368d57055c7264dea6cc7bb3a473 *inst/doc/document-manipulation.R
0a81e2595fc31915b1c6ec77cdbc8fe2 *inst/doc/document-manipulation.Rmd
da06e48003c0615e9668bfbbb796d431 *inst/doc/document-manipulation.html
4eb7f4d912f65f74a951b41ca1ab859d *inst/doc/introduction.Rmd
3a6f9bf7c8f9dc5398223552bcb99689 *inst/doc/introduction.html
56dd08d3e641735a5e064a40db50ded1 *inst/doc/projects.R
b3f763976fc12d073ef5f4cf610589db *inst/doc/projects.Rmd
1eb8ac3d3e298631580471da8d7c92d5 *inst/doc/projects.html
fdc9d3e65011faebe4ea5c33d8cc8eb0 *inst/doc/r-session.R
e6a3d01fd23d7703544ce9fa0c5a5089 *inst/doc/r-session.Rmd
803d3e0908e878080452e23aed52d743 *inst/doc/r-session.html
dd76bcdef8bbf43956ace43c481baad1 *inst/doc/terminal.R
2ba016fe1aab495668b3409636332aa3 *inst/doc/terminal.Rmd
dd0a2ed8489a1b2839960af9090c5026 *inst/doc/terminal.html
03ae66de60e7f4e1516280cba5e474ec *man/askForPassword.Rd
ad21ab32c5daacffad889acd69376795 *man/callFun.Rd
8ac4e409d80a637339fa92f4ccfdd7a7 *man/createProjectTemplate.Rd
291045dce4647df9c71550a1bf57923d *man/document_position.Rd
8a8204ffb5da369e4b14f1420925c7ff *man/document_range.Rd
cd2efda56d6ba686e1f52504d5d72299 *man/file-dialogs.Rd
d14b51dd251dd29bfaf0331da150e656 *man/getActiveProject.Rd
50c241884c4ff6b804cabc96f45bc5c6 *man/getThemeInfo.Rd
687411752d5b2bef75ac2fed853dbc51 *man/getVersion.Rd
ee6402d2f2c55ced5f0a0db12babc10a *man/hasColorConsole.Rd
e05c2ee202f37c1fc83906acd091f2b5 *man/hasFun.Rd
41046d652e58828f56177c7aae4b11f2 *man/isAvailable.Rd
86b986e7537985ce69231bf925bbb88c *man/navigateToFile.Rd
e5b99f32efcfa5cbb382f692ffd86c0a *man/persistent-values.Rd
11afff28da5a838ddfcd210abfc8e144 *man/previewRd.Rd
7b821cb2132dcd6c12a9d637b71f4579 *man/primary_selection.Rd
165de5264090d14b7345e6c02a09198d *man/projects.Rd
f59bcedf1ed821a03c872bc42d3748eb *man/readPreference.Rd
9ef0a82e3f60f7376543a63ba8c4d304 *man/restartSession.Rd
1e7a7192b903f15acbf3ccdc20512258 *man/rstudio-documents.Rd
6875fd0ca0324d5d2c6fce8502429551 *man/rstudio-editors.Rd
2277521a3e2165296ad63eb6c5950439 *man/savePlotAsImage.Rd
8d9df681f160c700a3b733689b77f96e *man/sendToConsole.Rd
e25f829def19bb6776f4f153e0c0bdae *man/showDialog.Rd
19c83a2f89748a964b29c28811d8f152 *man/showPrompt.Rd
5d93ce0c1c220e766829593935f80145 *man/showQuestion.Rd
0d5ed2c1fbd1d32f3d1c67bdd21d9c8a *man/sourceMarkers.Rd
209facce79d9b8745aefcb32b26ec380 *man/terminalActivate.Rd
3c6a4f340b0b363511497f473d36eaa8 *man/terminalBuffer.Rd
12aadc9c42d535142caf1a09bb03b43b *man/terminalBusy.Rd
971aba2c3224708516047ebaee9e571d *man/terminalClear.Rd
d952a8fab9e2e89a80d61ae82693bf55 *man/terminalContext.Rd
fcae94bc5a9868e802e36681a154c63b *man/terminalCreate.Rd
ad018d102bde2341955a14f391b90cfd *man/terminalExecute.Rd
58186f9255226b2e33ff2459a489b453 *man/terminalExitCode.Rd
ce1abbd7856353cb9212f71e2c74088c *man/terminalKill.Rd
35606fc8b8e6c7c12a4c1fbb4681b799 *man/terminalList.Rd
4d96a78cadf0f5e74f4f964c4b0a39d6 *man/terminalRunning.Rd
3fa1650a1cf65d915f71bb56c9d52d50 *man/terminalSend.Rd
44a2b40ffbf8ee37c0f8297f2f25b1e3 *man/terminalVisible.Rd
9bd0485e13b003db97e8bbc0cc7a3e30 *man/updateDialog.Rd
81a78e563475ba823e5bc21d7eef55ed *man/versionInfo.Rd
94dbccd5ee33fca7d9601a03622990d4 *man/viewer.Rd
658d453feef6f58d75f3abd870e2d7f3 *man/writePreference.Rd
01f5841a3d3d9249f0b6509697189d5e *vignettes/dialogs.Rmd
0a81e2595fc31915b1c6ec77cdbc8fe2 *vignettes/document-manipulation.Rmd
4eb7f4d912f65f74a951b41ca1ab859d *vignettes/introduction.Rmd
b3f763976fc12d073ef5f4cf610589db *vignettes/projects.Rmd
e6a3d01fd23d7703544ce9fa0c5a5089 *vignettes/r-session.Rmd
2ba016fe1aab495668b3409636332aa3 *vignettes/terminal.Rmd
rstudioapi/build/ 0000755 0001762 0000144 00000000000 13154303177 013540 5 ustar ligges users rstudioapi/build/vignette.rds 0000644 0001762 0000144 00000000554 13154303177 016103 0 ustar ligges users RN0thiQBh"RՊMkؑws,:u"8؞}<! bƗ`ak>3.Yv(8B7\gU!LɲʙZTh^e |X*2>62+0T,L悦{U]>!PCƺKJ{`Àt+݆.5Q0Yȃ q} rstudioapi/DESCRIPTION 0000644 0001762 0000144 00000002015 13154336432 014145 0 ustar ligges users Package: rstudioapi
Title: Safely Access the RStudio API
Description: Access the RStudio API (if available) and provide informative error
messages when it's not.
Version: 0.7
Authors@R: c(
person("JJ", "Allaire", role = c("aut", "cre"), email = "jj@rstudio.com"),
person("Hadley", "Wickham", role = c("aut"), email = "hadley@rstudio.com"),
person("Kevin", "Ushey", role = c("aut"), email = "kevin@rstudio.com"),
person("Gary", "Ritchie", role = c("aut"), email = "gary@rstudio.com"),
person(family = "RStudio", role = "cph")
)
Maintainer: JJ Allaire
License: MIT + file LICENSE
URL: https://github.com/rstudio/rstudioapi
BugReports: https://github.com/rstudio/rstudioapi/issues
RoxygenNote: 6.0.1
Suggests: testthat, knitr, rmarkdown
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2017-09-07 17:48:48 UTC; kevin
Author: JJ Allaire [aut, cre],
Hadley Wickham [aut],
Kevin Ushey [aut],
Gary Ritchie [aut],
RStudio [cph]
Repository: CRAN
Date/Publication: 2017-09-07 21:41:46 UTC
rstudioapi/man/ 0000755 0001762 0000144 00000000000 13153571034 013212 5 ustar ligges users rstudioapi/man/updateDialog.Rd 0000644 0001762 0000144 00000001170 13102441273 016075 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dialogs.R
\name{updateDialog}
\alias{updateDialog}
\title{Updates a Dialog Box}
\usage{
updateDialog(...)
}
\arguments{
\item{...}{Named parameters and values to update a dialog box.}
}
\description{
Updates specific properties from the current dialog box.
}
\details{
Currently, the only dialog with support for this action is the
New Connection dialog in which the code preview can be
updated through this API.
\preformatted{
updateDialog(code = "con <- NULL")
}
}
\note{
The \code{updateDialog} function was added in version 1.1.67 of RStudio.
}
rstudioapi/man/askForPassword.Rd 0000644 0001762 0000144 00000001174 13102441273 016447 0 ustar ligges users \name{askForPassword}
\alias{askForPassword}
\title{
Ask the user for a password interactively
}
\description{
Ask the user for a password interactively.
}
\note{
The \code{askForPassword} function was added in version 0.99.853 of RStudio.
}
\usage{
askForPassword(prompt)
}
\arguments{
\item{prompt}{Single element character vector containing the prompt to be displayed}
}
\details{
RStudio also sets the global \code{askpass} option to the \code{rstudioapi::askForPassword} function so that it can be invoked in a front-end independent manner.
}
\examples{
\dontrun{
rstudioapi::askForPassword("Please enter your password")
}
}
rstudioapi/man/terminalExitCode.Rd 0000644 0001762 0000144 00000001205 13153571034 016737 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/terminal.R
\name{terminalExitCode}
\alias{terminalExitCode}
\title{Terminal Exit Code}
\usage{
terminalExitCode(id)
}
\arguments{
\item{id}{The terminal id. The \code{id} is obtained from
\code{\link{terminalList}()}, \code{\link{terminalVisible}()},
,\code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.}
}
\value{
The exit code as an integer vector, or NULL if process still running.
}
\description{
Get exit code of terminal process, or NULL if still running.
}
\note{
The \code{terminalExitCode} function was added in version 1.1.350 of RStudio.
}
rstudioapi/man/writePreference.Rd 0000644 0001762 0000144 00000001001 13102441273 016615 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dialogs.R
\name{writePreference}
\alias{writePreference}
\title{Write Preference}
\usage{
writePreference(name, value)
}
\arguments{
\item{name}{The name of the preference.}
\item{value}{The value of the preference.}
}
\description{
Writes a user interface preference, useful to remember preferences across
different r sessions for the same user.
}
\note{
The \code{writePreference} function was added in version 1.1.67 of RStudio.
}
rstudioapi/man/rstudio-documents.Rd 0000644 0001762 0000144 00000006427 13124550617 017204 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/document-api.R
\name{rstudio-documents}
\alias{rstudio-documents}
\alias{rstudio-documents}
\alias{insertText}
\alias{rstudio-documents}
\alias{modifyRange}
\alias{rstudio-documents}
\alias{setDocumentContents}
\alias{rstudio-documents}
\alias{setCursorPosition}
\alias{rstudio-documents}
\alias{setSelectionRanges}
\alias{rstudio-documents}
\alias{documentSave}
\alias{rstudio-documents}
\alias{documentSaveAll}
\title{Interact with Documents open in RStudio}
\usage{
insertText(location, text, id = NULL)
modifyRange(location, text, id = NULL)
setDocumentContents(text, id = NULL)
setCursorPosition(position, id = NULL)
setSelectionRanges(ranges, id = NULL)
documentSave(id = NULL)
documentSaveAll()
}
\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 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.}
\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}()}.}
}
\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.
}
\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.
}
rstudioapi/man/primary_selection.Rd 0000644 0001762 0000144 00000001203 13102441273 017220 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/document-methods.R
\name{primary_selection}
\alias{primary_selection}
\title{Extract the Primary Selection}
\usage{
primary_selection(x, ...)
}
\arguments{
\item{x}{A document context, or a selection.}
\item{...}{Optional arguments (currently ignored).}
}
\description{
By default, functions returning a document context will
return a list of selections, including both the 'primary'
selection and also 'other' selections (e.g. to handle the
case where a user might have multiple cursors active).
Use \code{primary_selection()} to extract the primary
selection.
}
rstudioapi/man/getThemeInfo.Rd 0000644 0001762 0000144 00000000703 13134170233 016052 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/themes.R
\name{getThemeInfo}
\alias{getThemeInfo}
\title{Retrieve Themes}
\usage{
getThemeInfo()
}
\description{
Retrieves a list with themes information. Currently, \code{editor} as
the theme used under the code editor, \code{global} as the global theme
applied to the main user interface in RStudio and \code{dark} when
the user interface is optimized for dark themes.
}
rstudioapi/man/versionInfo.Rd 0000644 0001762 0000144 00000002035 13102441273 015775 0 ustar ligges users \name{versionInfo}
\alias{versionInfo}
\title{
RStudio Version Information
}
\description{
Provides information about the currently running version of RStudio, including it's specific version number and whether it is running in desktop or server mode.
}
\note{
The \code{versionInfo} function was added in version 0.97.124 of RStudio.
}
\usage{
versionInfo()
}
\value{
Returns a list with the following elements:
\tabular{ll}{
\code{version} \tab A package version object that can be used in comparisons. This is the same value which would be returned from \code{packageVersion("rstudio")} \cr
\code{mode} \tab Current program mode (either "desktop" or "server")\cr
\code{citation} \tab An object inheriting from class \code{bibentry}\cr
}
}
\examples{
\dontrun{
require(rstudioapi)
ver <- versionInfo()
# Test specific version constraint
if (ver$version >= "0.97") {
# do some 0.97 dependent stuff
}
# Check current mode
desktopMode <- ver$mode == "desktop"
serverMode <- ver$mode == "server"
# Get the citation
ver$citation
}
}
rstudioapi/man/terminalBusy.Rd 0000644 0001762 0000144 00000001531 13153571034 016157 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/terminal.R
\name{terminalBusy}
\alias{terminalBusy}
\title{Is Terminal Busy}
\usage{
terminalBusy(id)
}
\arguments{
\item{id}{The terminal id. The \code{id} is obtained from
\code{\link{terminalList}()}, \code{\link{terminalVisible}()},
\code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.}
}
\value{
a boolean
}
\description{
Are terminals reporting that they are busy?
}
\note{
The \code{terminalBusy} function was added in version 1.1.350 of RStudio.
}
\examples{
\dontrun{
# create a hidden terminal and run a lengthy command
termId <- rstudioapi::terminalCreate(show = FALSE)
rstudioapi::terminalSend(termId, "sleep 5\\n")
# wait until a busy terminal is finished
while (rstudioapi::terminalBusy(termId)) {
Sys.sleep(0.1)
}
print("Terminal available")
}
}
rstudioapi/man/hasColorConsole.Rd 0000644 0001762 0000144 00000000773 13102442225 016576 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stubs.R
\name{hasColorConsole}
\alias{hasColorConsole}
\title{Check if Console Supports ANSI Color Escapes}
\usage{
hasColorConsole()
}
\value{
a boolean
}
\description{
Check if Console Supports ANSI Color Escapes
}
\note{
The \code{hasColorConsole} function was added in version 1.1.216
of RStudio.
}
\examples{
\dontrun{
if (rstudioapi::hasColorConsole()) {
message("RStudio console supports ANSI color sequences.")
}
}
}
rstudioapi/man/previewRd.Rd 0000644 0001762 0000144 00000000661 13102441273 015446 0 ustar ligges users \name{previewRd}
\alias{previewRd}
\title{
Preview an Rd topic in the Help pane
}
\description{
Preview an Rd topic in the Help pane
}
\note{
The \code{previewRd} function was added in version 0.98.191 of RStudio.
}
\usage{
previewRd(rdFile)
}
\arguments{
\item{rdFile}{Single element character vector containing the name of the Rd file to be displayed}
}
\examples{
\dontrun{
rstudioapi::previewRd("~/MyPackage/man/foo.Rd")
}
} rstudioapi/man/savePlotAsImage.Rd 0000644 0001762 0000144 00000001200 13102441273 016511 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stubs.R
\name{savePlotAsImage}
\alias{savePlotAsImage}
\title{Save Active RStudio Plot as an Image}
\usage{
savePlotAsImage(file, format = c("png", "jpeg", "bmp", "tiff", "emf", "svg",
"eps"), width, height)
}
\arguments{
\item{file}{Target filename}
\item{format}{Image format ("png", "jpeg", "bmp", "tiff", "emf", "svg", or "eps")}
\item{width}{Image width in pixels}
\item{height}{Image height in pixels}
}
\description{
Save the currnently active RStudio as an image file.
}
\note{
The \code{savePlotAsImage} function was introduced in RStudio 1.1.57
}
rstudioapi/man/showQuestion.Rd 0000644 0001762 0000144 00000001300 13102441273 016176 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dialogs.R
\name{showQuestion}
\alias{showQuestion}
\title{Show Question Dialog Box}
\usage{
showQuestion(title, message, ok = NULL, cancel = NULL)
}
\arguments{
\item{title}{The title to display in the dialog box.}
\item{message}{A character vector with the contents to display in
the main dialog area.}
\item{ok}{And optional character vector that overrides the caption for
the OK button.}
\item{cancel}{An optional character vector that overrides the caption for
the Cancel button.}
}
\description{
Shows a dialog box asking a question.
}
\note{
The \code{showQuestion} function was added in version 1.1.67 of RStudio.
}
rstudioapi/man/document_range.Rd 0000644 0001762 0000144 00000001651 13102441273 016471 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/document-methods.R
\name{document_range}
\alias{document_range}
\alias{document_range}
\alias{is.document_range}
\alias{document_range}
\alias{as.document_range}
\title{Create a Range}
\usage{
document_range(start, end = NULL)
is.document_range(x)
as.document_range(x)
}
\arguments{
\item{start}{A \code{\link{document_position}} indicating the start of the
range.}
\item{end}{A \code{\link{document_position}} indicating the end of the range.}
\item{x}{An object coercable to \code{document_range}.}
}
\value{
An \R \code{list} with class \code{document_range} and fields:
\tabular{ll}{
\code{start:}\tab The start position.\cr
\code{end:}\tab The end position.\cr
}
}
\description{
A \code{document_range} is a pair of \code{\link{document_position}} objects,
with each position indicating the \code{start} and \code{end} of the range,
respectively.
}
rstudioapi/man/restartSession.Rd 0000644 0001762 0000144 00000000650 13122533525 016531 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stubs.R
\name{restartSession}
\alias{restartSession}
\title{Restart the R Session}
\usage{
restartSession(command = "")
}
\arguments{
\item{command}{An \R command (as a string) to be run
after restarting \R.}
}
\description{
Restart the RStudio \R session.
}
\note{
The \code{restartSession} function was added in version 1.1.281
of RStudio.
}
rstudioapi/man/projects.Rd 0000644 0001762 0000144 00000002226 13124551105 015327 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stubs.R
\name{projects}
\alias{projects}
\alias{projects}
\alias{openProject}
\alias{projects}
\alias{initializeProject}
\title{Open a Project in RStudio}
\usage{
openProject(path = NULL, newSession = FALSE)
initializeProject(path = getwd())
}
\arguments{
\item{path}{Either the path to an existing \code{.Rproj} file, or a path
to a directory in which a new project should be initialized and opened.}
\item{newSession}{Boolean; should the project be opened in a new session,
or should the current RStudio session switch to that project? Note that
\code{TRUE} values are only supported with RStudio Desktop and RStudio
Server Pro.}
}
\description{
Initialize and open RStudio projects.
}
\details{
Calling \code{openProject()} without arguments effectively re-opens the
currently open project in RStudio. When switching projects, users will
be prompted to save any unsaved files; alternatively, you can explicitly
save any open documents using \code{\link{documentSaveAll}()}.
}
\note{
The \code{openProject} and \code{initializeProject} functions were
added in version 1.1.287 of RStudio.
}
rstudioapi/man/persistent-values.Rd 0000644 0001762 0000144 00000001334 13102441273 017172 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stubs.R
\name{persistent-values}
\alias{persistent-values}
\alias{setPersistentValue}
\alias{getPersistentValue}
\title{Persistent Keys and Values}
\usage{
setPersistentValue(name, value)
getPersistentValue(name)
}
\arguments{
\item{name}{Key name}
\item{value}{Key value}
}
\value{
The stored value as a character vector (\code{NULL} if no value
of the specified name is available).
}
\description{
Store persistent keys and values. Storage is per-project, if there is
no project currently active then a global store is used.
}
\note{
The \code{setPersistentValue} and \code{getPersistentValue} functions
were added in version 1.1.57 of RStudio.
}
rstudioapi/man/showDialog.Rd 0000644 0001762 0000144 00000001357 13102441273 015602 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dialogs.R
\name{showDialog}
\alias{showDialog}
\title{Show Dialog Box}
\usage{
showDialog(title, message, url = NULL)
}
\arguments{
\item{title}{The title to display in the dialog box.}
\item{message}{A character vector with the contents to display in
the main dialog area. Contents can contain the following HTML tags:
"p", "em", "strong", "b" and "i".}
\item{url}{And optional url to display under the \code{message}.}
}
\description{
Shows a dialog box with a given title and contents.
}
\details{
\preformatted{
showDialog("A dialog", "Showing bold text in the message.")
}
}
\note{
The \code{showDialog} function was added in version 1.1.67 of RStudio.
}
rstudioapi/man/terminalList.Rd 0000644 0001762 0000144 00000000640 13153571034 016150 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/terminal.R
\name{terminalList}
\alias{terminalList}
\title{Get All Terminal Ids}
\usage{
terminalList()
}
\value{
The terminal identifiers as a character vector.
}
\description{
Return a character vector containing all the current terminal identifiers.
}
\note{
The \code{terminalList} function was added in version 1.1.350 of RStudio.
}
rstudioapi/man/readPreference.Rd 0000644 0001762 0000144 00000001041 13102441273 016402 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dialogs.R
\name{readPreference}
\alias{readPreference}
\title{Read Preference}
\usage{
readPreference(name, default)
}
\arguments{
\item{name}{The name of the preference.}
\item{default}{The default value to use when the preference is not available.}
}
\description{
Reads a user interface preference, useful to remember preferences across
different r sessions for the same user.
}
\note{
The \code{readPreference} function was added in version 1.1.67 of RStudio.
}
rstudioapi/man/document_position.Rd 0000644 0001762 0000144 00000001241 13102441273 017234 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/document-methods.R
\name{document_position}
\alias{document_position}
\alias{is.document_position}
\alias{document_position}
\alias{as.document_position}
\title{Create a Document Position}
\usage{
document_position(row, column)
is.document_position(x)
as.document_position(x)
}
\arguments{
\item{row}{The row (using 1-based indexing).}
\item{column}{The column (using 1-based indexing).}
\item{x}{An object coercable to \code{document_position}.}
}
\description{
Creates a \code{document_position}, which can be used to indicate e.g. the
row + column location of the cursor in a document.
}
rstudioapi/man/getActiveProject.Rd 0000644 0001762 0000144 00000000754 13102441273 016744 0 ustar ligges users \name{getActiveProject}
\alias{getActiveProject}
\title{
Path to Active RStudio Project
}
\description{
Returns the path to the currently active RStudio project.
}
\note{
The \code{getActiveProject} function was added in version 0.99.854 of RStudio.
}
\usage{
getActiveProject()
}
\value{
Returns a single element character vector with the path of the currently active RStudio project. Returns \code{NULL} if no project is active.
}
\examples{
\dontrun{
rstudioapi::getActiveProject()
}
}
rstudioapi/man/hasFun.Rd 0000644 0001762 0000144 00000001532 13102441273 014721 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/code.R
\name{hasFun}
\alias{hasFun}
\alias{findFun}
\title{Exists/get for RStudio functions}
\usage{
hasFun(name, version_needed = NULL, ...)
findFun(name, version_needed = NULL, ...)
}
\arguments{
\item{name}{name of object to look for}
\item{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.}
\item{...}{other arguments passed on to \code{\link[base]{exists}} and
\code{\link[base]{get}}}
}
\description{
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}.
}
\examples{
rstudioapi::hasFun("viewer")
}
rstudioapi/man/file-dialogs.Rd 0000644 0001762 0000144 00000002713 13124545162 016044 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stubs.R
\name{file-dialogs}
\alias{file-dialogs}
\alias{file-dialogs}
\alias{selectFile}
\alias{file-dialogs}
\alias{selectDirectory}
\title{Select a File / Folder}
\usage{
selectFile(caption = "Select File", label = "Select", path = NULL,
filter = NULL, existing = TRUE)
selectDirectory(caption = "Select Directory", label = "Select",
path = NULL)
}
\arguments{
\item{caption}{The window title.}
\item{label}{The label to use for the 'Accept' / 'OK' button.}
\item{path}{The initial working directory, from which the file dialog
should begin browsing. When \code{NULL}, defaults to the current RStudio
project directory.}
\item{filter}{A glob filter, to be used when attempting to open a file
with a particular extension. For example, to scope the dialog to
\R files, one could use \code{R Files (*.R)} here.}
\item{existing}{Boolean; should the file dialog limit itself to existing
files on the filesystem, or allow the user to select the path to a new file?}
}
\description{
Prompt the user for the path to a file or folder, using the system
file dialogs with RStudio Desktop, and RStudio's own web dialogs
with RStudio Server.
}
\details{
When the selected file resolves within the user's home directory,
RStudio will return an aliased path -- that is, prefixed with \code{~/}.
}
\note{
The \code{selectFile} and \code{selectDirectory} functions were
added in version 1.1.287 of RStudio.
}
rstudioapi/man/terminalCreate.Rd 0000644 0001762 0000144 00000001411 13153571034 016435 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/terminal.R
\name{terminalCreate}
\alias{terminalCreate}
\title{Create a Terminal}
\usage{
terminalCreate(caption = NULL, show = TRUE)
}
\arguments{
\item{caption}{The desired terminal caption. When \code{NULL} or blank,
the terminal caption will be chosen by the system.}
\item{show}{If \code{FALSE}, terminal won't be brought to front.}
}
\value{
The terminal identifier as a character vector (\code{NULL} if
unable to create the terminal or the given terminal caption is already
in use).
}
\description{
Create a new Terminal.
}
\note{
The \code{terminalCreate} function was added in version 1.1.350 of RStudio.
}
\examples{
\dontrun{
termId <- rstudioapi::terminalCreate('My Terminal')
}
}
rstudioapi/man/viewer.Rd 0000644 0001762 0000144 00000007443 13102441273 015005 0 ustar ligges users \name{viewer}
\alias{viewer}
\title{
View local web content within RStudio
}
\description{
View local web content within RStudio. Content can be served from static files in the R session temporary directory or can be a \link[shiny:shiny-package]{Shiny}, \link[Rook:Rook-package]{Rook}, \link[opencpu:opencpu]{OpenCPU}, or any other type of localhost web application.
}
\usage{
viewer(url, height = NULL)
}
\arguments{
\item{url}{Application URL. This can be either a localhost URL or a path to a file within the R session temporary directory (i.e. a path returned by \code{\link[base:tempfile]{tempfile}}).
}
\item{height}{Desired height. Specifies a desired height for the Viewer pane (the default is \code{NULL} which makes no change to the height of the pane). This value can be numeric or the string \code{"maximize"} in which case the Viewer will expand to fill all vertical space. See details below for a discussion of constraints imposed on the height.
}
}
\details{
RStudio also sets the global \code{viewer} option to the \code{rstudioapi::viewer} function so that it can be invoked in a front-end independent manner.
Applications are displayed within the Viewer pane. The application URL must either be served from localhost or be a path to a file within the R session temporary directory. If the URL doesn't conform to these requirements it is displayed within a standard browser window.
The \code{height} parameter specifies a desired height, however it's possible the Viewer pane will end up smaller if the request can't be fulfilled (RStudio ensures that the pane paired with the Viewer maintains a minimum height). A height of 400 pixels or lower is likely to succeed in a large proportion of configurations.
A very large height (e.g. 2000 pixels) will allocate the maximum allowable space for the Viewer (while still preserving some view of the pane above or below it). The value \code{"maximize"} will force the Viewer to full height. Note that this value should only be specified in cases where maximum vertical space is essential, as it will result in one of the user's other panes being hidden.
}
\note{
The \code{viewer} function was added in version 0.98.423 of RStudio. The ability to specify \code{maximize} for the \code{height} parameter was introduced in version 0.99.1001 of RStudio.
}
\section{Viewer Detection}{
When a page is displayed within the Viewer it's possible that the user will choose to pop it out into a standalone browser window. When rendering inside a standard browser you may want to make different choices about how content is laid out or scaled. Web pages can detect that they are running inside the Viewer pane by looking for the \code{viewer_pane} query parameter, which is automatically injected into URLs when they are shown in the Viewer. For example, the following URL:
\preformatted{
http://localhost:8100
}
When rendered in the Viewer pane is transformed to:
\preformatted{
http://localhost:8100?viewer_pane=1
}
To provide a good user experience it's strongly recommended that callers take advantage of this to automatically scale their content to the current size of the Viewer pane. For example, re-rendering a JavaScript plot with new dimensions when the size of the pane changes.
}
\examples{
\dontrun{
# run an application inside the IDE
rstudioapi::viewer("http://localhost:8100")
# run an application and request a height of 500 pixels
rstudioapi::viewer("http://localhost:8100", height = 500)
# probe for viewer option then fall back to browseURL
viewer <- getOption("viewer")
if (!is.null(viewer))
viewer("http://localhost:8100")
else
utils::browseURL("http://localhost:8100")
# generate a temporary html file and display it
dir <- tempfile()
dir.create(dir)
htmlFile <- file.path(dir, "index.html")
# (code to write some content to the file)
rstudioapi::viewer(htmlFile)
}
} rstudioapi/man/navigateToFile.Rd 0000644 0001762 0000144 00000002204 13122310635 016372 0 ustar ligges users \name{navigateToFile}
\alias{navigateToFile}
\title{
Navigate to File
}
\description{
Open a file in RStudio, optionally at a specified location.
}
\note{
The \code{navigateToFile} function was added in version 0.99.719 of RStudio.
}
\usage{
navigateToFile(file, line = -1L, column = -1L)
}
\arguments{
\item{file}{Path to the file to open)}
\item{line}{Optional; integer specifying the line number on which to place the cursor}
\item{column}{Optional; integer specifying the column number on which to place the cursor}
}
\details{
The \code{navigateToFile} opens a file in RStudio. If the file is already open, its tab or window is activated.
Once the file is open, the cursor is moved to the specified location. If the \code{line}
and \code{column} arguments are both equal to \code{-1L} (the default), then
the cursor position in the document that is opened will be preserved.
Note that if your intent is to navigate to a particular function within a file, you can also cause RStudio to navigate there by invoking \code{\link[utils]{View}} on the function, which has the advantage of falling back on deparsing if the file is not available.
}
rstudioapi/man/terminalActivate.Rd 0000644 0001762 0000144 00000002076 13153571034 017002 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/terminal.R
\name{terminalActivate}
\alias{terminalActivate}
\title{Activate Terminal}
\usage{
terminalActivate(id = NULL, show = TRUE)
}
\arguments{
\item{id}{The terminal id. The \code{id} is obtained from
\code{\link{terminalList}()}, \code{\link{terminalVisible}()},
\code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.
If NULL, the terminal tab will be selected but no specific terminal
will be chosen.}
\item{show}{If TRUE, bring the terminal to front in RStudio.}
}
\description{
Ensure terminal is running and optionally bring to front in RStudio.
}
\note{
The \code{terminalActivate} function was added in version 1.1.350 of RStudio.
}
\examples{
\dontrun{
# create a hidden terminal and run a lengthy command
termId = rstudioapi::terminalCreate(show = FALSE)
rstudioapi::terminalSend(termId, "sleep 5\\n")
# wait until a busy terminal is finished
while (rstudioapi::terminalBusy(termId)) {
Sys.sleep(0.1)
}
print("Terminal available")#'
rstudioapi::terminalActivate(termId)
}
}
rstudioapi/man/showPrompt.Rd 0000644 0001762 0000144 00000001127 13102441273 015657 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dialogs.R
\name{showPrompt}
\alias{showPrompt}
\title{Show Prompt Dialog Box}
\usage{
showPrompt(title, message, default = NULL)
}
\arguments{
\item{title}{The title to display in the dialog box.}
\item{message}{A character vector with the contents to display in
the main dialog area.}
\item{default}{An optional character vector that fills the prompt field
with a default value.}
}
\description{
Shows a dialog box with a prompt field.
}
\note{
The \code{showPrompt} function was added in version 1.1.67 of RStudio.
}
rstudioapi/man/callFun.Rd 0000644 0001762 0000144 00000001101 13102441273 015051 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/code.R
\name{callFun}
\alias{callFun}
\title{Call an RStudio API function}
\usage{
callFun(fname, ...)
}
\arguments{
\item{fname}{name of the RStudio function to call.}
\item{...}{Other arguments passed on to the function}
}
\description{
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}}.
}
\examples{
if (rstudioapi::isAvailable()) {
rstudioapi::callFun("versionInfo")
}
}
rstudioapi/man/terminalContext.Rd 0000644 0001762 0000144 00000002631 13153571034 016663 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/terminal.R
\name{terminalContext}
\alias{terminalContext}
\title{Retrieve Information about RStudio Terminals}
\usage{
terminalContext(id)
}
\arguments{
\item{id}{The terminal id. The \code{id} is obtained from
\code{\link{terminalList}()}, \code{\link{terminalVisible}()},
\code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.}
}
\value{
A \code{list} with elements:
\tabular{ll}{
\code{handle} \tab the internal handle\cr
\code{caption} \tab caption\cr
\code{title} \tab title set by the shell\cr
\code{working_dir} \tab working directory\cr
\code{shell} \tab shell type\cr
\code{running} \tab is terminal process executing\cr
\code{busy} \tab is terminal running a program\cr
\code{exit_code} \tab process exit code or NULL\cr
\code{connection} \tab websockets or rpc\cr
\code{sequence} \tab creation sequence\cr
\code{lines} \tab lines of text in terminal buffer\cr
\code{cols} \tab columns in terminal\cr
\code{rows} \tab rows in terminal\cr
\code{pid} \tab process id of terminal shell\cr
\code{full_screen} \tab full screen program running\cr
}
}
\description{
Returns information about RStudio terminal instances.
}
\note{
The \code{terminalContext} function was added in version 1.1.350 of RStudio.
}
\examples{
\dontrun{
termId <- rstudioapi::terminalCreate("example", show = FALSE)
View(rstudioapi::terminalContext(termId))
}
}
rstudioapi/man/terminalKill.Rd 0000644 0001762 0000144 00000001007 13153571034 016126 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/terminal.R
\name{terminalKill}
\alias{terminalKill}
\title{Kill Terminal}
\usage{
terminalKill(id)
}
\arguments{
\item{id}{The terminal id. The \code{id} is obtained from
\code{\link{terminalList}()}, \code{\link{terminalVisible}()},
\code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.}
}
\description{
Kill processes and close a terminal.
}
\note{
The \code{terminalKill} function was added in version 1.1.350 of RStudio.
}
rstudioapi/man/terminalExecute.Rd 0000644 0001762 0000144 00000002132 13153571034 016635 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/terminal.R
\name{terminalExecute}
\alias{terminalExecute}
\title{Execute Command}
\usage{
terminalExecute(command, workingDir = NULL, env = character(),
show = TRUE)
}
\arguments{
\item{command}{System command to be invoked, as a character string.}
\item{workingDir}{Working directory for command}
\item{env}{Vector of name=value strings to set environment variables}
\item{show}{If FALSE, terminal won't be brought to front}
}
\value{
The terminal identifier as a character vector (\code{NULL} if
unable to create the terminal).
}
\description{
Execute a command, showing results in the terminal pane.
}
\note{
The \code{terminalExecute} function was added in version 1.1.350 of RStudio.
}
\examples{
\dontrun{
termId <- rstudioapi::terminalExecute(
command = 'echo $HELLO && echo $WORLD',
workingDir = '/usr/local',
env = c('HELLO=WORLD', 'WORLD=EARTH'),
show = FALSE)
while (is.null(rstudioapi::terminalExitCode(termId))) {
Sys.sleep(0.1)
}
result <- terminalBuffer(termId)
terminalKill(termId)
print(result)
}
}
rstudioapi/man/sourceMarkers.Rd 0000644 0001762 0000144 00000003110 13102441273 016314 0 ustar ligges users \name{sourceMarkers}
\alias{sourceMarkers}
\title{
Display Source Markers
}
\description{
Display user navigable source markers in a pane within RStudio
}
\note{
The \code{sourceMarkers} function was added in version 0.99.225 of RStudio.
}
\usage{
sourceMarkers(name, markers, basePath = NULL,
autoSelect = c("none", "first", "error"))
}
\arguments{
\item{name}{Name of marker set (will replace any markers of the same name previously shown)}
\item{markers}{List or data frame containing source markers (see below for details on how to specify markers)}
\item{basePath}{Optional. If all source files are within a base path then specifying that path here will result in file names being displayed as relative paths. Note that in this case markers still need to specify source file names as full paths.}
\item{autoSelect}{Optional. Automatically select and drive focus to either the first marker or the first marker that is an error.}
}
\details{
The \code{markers} argument can contains either a list of marker lists or a data frame with the appropriate marker columns. The fields in a marker are as follows (all are required):
\tabular{ll}{
\code{type} \tab Marker type ("error", "warning", "info", "style", or "usage")\cr
\code{file} \tab Path to source file\cr
\code{line} \tab Line number witin source file \cr
\code{column} \tab Column number within line\cr
\code{message} \tab Short descriptive message\cr
}
Note that if the \code{message} field is of class "html" (i.e. \code{inherits(message, "html") == TRUE}) then it's contents will be treated as HTML.
}
rstudioapi/man/createProjectTemplate.Rd 0000644 0001762 0000144 00000003155 13102441671 017770 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/templates.R
\name{createProjectTemplate}
\alias{createProjectTemplate}
\title{Create a Project Template}
\usage{
createProjectTemplate(package = ".", binding, title,
subtitle = paste("Create a new", title), caption = paste("Create", title),
icon = NULL, open_files = NULL, overwrite = FALSE, edit = TRUE)
}
\arguments{
\item{package}{The path to an \R package sources.}
\item{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.}
\item{title}{The title to be shown within the \strong{New Project...} wizard.}
\item{subtitle}{(optional) The subtitle to be shown within the \strong{New Project...} wizard.}
\item{caption}{(optional) The caption to be shown on the landing page for this template.}
\item{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.}
\item{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.}
\item{overwrite}{Boolean; overwrite a pre-existing template file if one exists?}
\item{edit}{Boolean; open the file for editting after creation?}
}
\description{
Create a project template. See
\url{https://rstudio.github.io/rstudio-extensions/rstudio_project_templates.html}
for more information.
}
rstudioapi/man/sendToConsole.Rd 0000644 0001762 0000144 00000001110 13102441273 016244 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stubs.R
\name{sendToConsole}
\alias{sendToConsole}
\title{Send Code to the R Console}
\usage{
sendToConsole(code, execute = TRUE)
}
\arguments{
\item{code}{Character vector containing code to be executed.}
\item{execute}{\code{TRUE} to execute the code immediately.}
}
\description{
Send code to the R console and optionally execute it.
}
\note{
The \code{sendToConsole} function was added in version 0.99.787 of RStudio.
}
\examples{
\dontrun{
rstudioapi::sendToConsole(".Platform", execute = TRUE)
}
}
rstudioapi/man/terminalRunning.Rd 0000644 0001762 0000144 00000002166 13153571034 016662 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/terminal.R
\name{terminalRunning}
\alias{terminalRunning}
\title{Is Terminal Running}
\usage{
terminalRunning(id)
}
\arguments{
\item{id}{The terminal id. The \code{id} is obtained from
\code{\link{terminalList}()}, \code{\link{terminalVisible}()},
\code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.}
}
\value{
a boolean
}
\description{
Does a terminal have a process associated with it? If the R session is
restarted after a terminal has been created, the terminal will not
restart its shell until it is displayed either via the user
interface, or via \code{\link{terminalActivate}()}.
}
\note{
The \code{terminalRunning} function was added in version 1.1.350 of RStudio.
}
\examples{
\dontrun{
# termId has a handle to a previously created terminal
# make sure it is still running before we send it a command
if (!rstudioapi::terminalRunning(termId)) {
rstudioapi::terminalActivate(termId))
# wait for it to start
while (!rstudioapi::terminalRunning(termId)) {
Sys.sleep(0.1)
}
terminalSend(termId, "echo Hello\\n")
}
}
}
rstudioapi/man/rstudio-editors.Rd 0000644 0001762 0000144 00000002256 13124550631 016644 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/document-api.R
\name{rstudio-editors}
\alias{rstudio-editors}
\alias{getActiveDocumentContext}
\alias{rstudio-editors}
\alias{getSourceEditorContext}
\alias{rstudio-editors}
\alias{getConsoleEditorContext}
\title{Retrieve Information about an RStudio Editor}
\usage{
getActiveDocumentContext()
getSourceEditorContext()
getConsoleEditorContext()
}
\value{
A \code{list} with elements:
\tabular{ll}{
\code{id} \tab The document ID.\cr
\code{path} \tab The path to the document on disk.\cr
\code{contents} \tab The contents of the document.\cr
\code{selection} \tab A \code{list} of selections. See \bold{Details} for more information.\cr
}
}
\description{
Returns information about an RStudio editor.
}
\details{
The \code{selection} field returned is a list of document selection objects.
A document selection is just a pairing of a document \code{range}, and the
\code{text} within that range.
}
\note{
The \code{getActiveDocumentContext} function was added with version 0.99.796
of RStudio, while the \code{getSourceEditorContext} and the \code{getConsoleEditorContext}
functions were added with version 0.99.1111.
}
rstudioapi/man/isAvailable.Rd 0000644 0001762 0000144 00000001173 13102441273 015712 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/code.R
\name{isAvailable}
\alias{isAvailable}
\alias{verifyAvailable}
\title{Check if RStudio is running.}
\usage{
isAvailable(version_needed = NULL)
verifyAvailable(version_needed = NULL)
}
\arguments{
\item{version_needed}{An optional version specification. If supplied,
ensures that RStudio is at least that version.}
}
\value{
\code{isAvailable} a boolean; \code{verifyAvailable} an error message
if RStudio is not running
}
\description{
Check if RStudio is running.
}
\examples{
rstudioapi::isAvailable()
\dontrun{rstudioapi::verifyAvailable()}
}
rstudioapi/man/getVersion.Rd 0000644 0001762 0000144 00000000746 13102441273 015630 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/code.R
\name{getVersion}
\alias{getVersion}
\title{Return the current version of the RStudio API}
\usage{
getVersion()
}
\value{
A \code{\link{numeric_version}} which you can compare to a string
and get correct results.
}
\description{
Return the current version of the RStudio API
}
\examples{
\dontrun{
if (rstudioapi::getVersion() < "0.98.100") {
message("Your version of RStudio is quite old")
}
}
}
rstudioapi/man/terminalClear.Rd 0000644 0001762 0000144 00000001265 13153571034 016267 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/terminal.R
\name{terminalClear}
\alias{terminalClear}
\title{Clear Terminal Buffer}
\usage{
terminalClear(id)
}
\arguments{
\item{id}{The terminal id. The \code{id} is obtained from
\code{\link{terminalList}()}, \code{\link{terminalVisible}()},
\code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.}
}
\description{
Clears the buffer for specified terminal.
}
\note{
The \code{terminalClear} function was added in version 1.1.350 of RStudio.
}
\examples{
\dontrun{
termId <- rstudioapi::terminalCreate()
rstudioapi::terminalSend(termId, 'ls -l\\n')
Sys.sleep(3)
rstudioapi::terminalClear(termId)
}
}
rstudioapi/man/terminalVisible.Rd 0000644 0001762 0000144 00000000572 13153571034 016636 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/terminal.R
\name{terminalVisible}
\alias{terminalVisible}
\title{Get Visible Terminal}
\usage{
terminalVisible()
}
\value{
Terminal identifier selected in the client, if any.
}
\description{
Get Visible Terminal
}
\note{
The \code{terminalVisible} function was added in version 1.1.350 of RStudio.
}
rstudioapi/man/terminalSend.Rd 0000644 0001762 0000144 00000001302 13153571034 016122 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/terminal.R
\name{terminalSend}
\alias{terminalSend}
\title{Send Text to a Terminal}
\usage{
terminalSend(id, text)
}
\arguments{
\item{id}{The terminal id. The \code{id} is obtained from
\code{\link{terminalList}()}, \code{\link{terminalVisible}()},
\code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.}
\item{text}{Character vector containing text to be inserted.}
}
\description{
Send text to an existing terminal.
}
\note{
The \code{terminalSend} function was added in version 1.1.350 of RStudio.
}
\examples{
\dontrun{
termId <- rstudioapi::terminalCreate()
rstudioapi::terminalSend(termId, 'ls -l\\n')
}
}
rstudioapi/man/terminalBuffer.Rd 0000644 0001762 0000144 00000001301 13153571034 016441 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/terminal.R
\name{terminalBuffer}
\alias{terminalBuffer}
\title{Get Terminal Buffer}
\usage{
terminalBuffer(id, stripAnsi = TRUE)
}
\arguments{
\item{id}{The terminal id. The \code{id} is obtained from
\code{\link{terminalList}()}, \code{\link{terminalVisible}()},
\code{\link{terminalCreate}()}, or \code{\link{terminalExecute}()}.}
\item{stripAnsi}{If FALSE, don't strip out Ansi escape sequences before returning
terminal buffer.}
}
\value{
The terminal contents, one line per row.
}
\description{
Returns contents of a terminal buffer.
}
\note{
The \code{terminalBuffer} function was added in version 1.1.350 of RStudio.
}
rstudioapi/LICENSE 0000644 0001762 0000144 00000000045 13102441273 013436 0 ustar ligges users YEAR: 2015
COPYRIGHT HOLDER: RStudio