Add a Custom Editor Theme

Description

Adds a custom editor theme to RStudio and returns the name of the newly added theme.

Usage

addTheme(themePath, apply = FALSE, force = FALSE, globally = FALSE)

Arguments

Note

The addTheme function was introduced in RStudio 1.2.879.

Apply an Editor Theme to RStudio

Description

Applies the specified editor theme to RStudio.

Usage

applyTheme(name)

Arguments

Note

The applyTheme function was introduced in RStudio 1.2.879.

Ask the user for a password interactively

Description

Ask the user for a password interactively.

Usage

askForPassword(prompt = "Please enter your password")

Arguments

Details

RStudio also sets the global askpass option to the rstudioapi::askForPassword function so that it can be invoked in a front-end independent manner.

Note

The askForPassword function was added in version 0.99.853 of RStudio.

Examples

## Not run: 
rstudioapi::askForPassword("Please enter your password")

## End(Not run)

Prompt user for secret

Description

Request a secret from the user. If the keyring package is installed, it will be used to cache requested secrets.

Usage

askForSecret(
  name,
  message = paste(name, ":", sep = ""),
  title = paste(name, "Secret")
)

Arguments

Note

The askForSecret function was added in version 1.1.419 of RStudio.

File an RStudio Bug Report

Description

A utility function to assist with the filing of an RStudio bug report. This function will pre-populate a template with information useful in understanding your reported bug.

Usage

bugReport()

Build Tools

Description

Check, install, and use build tools as required.

Usage

buildToolsCheck()

buildToolsInstall(action)

buildToolsExec(expr)

Arguments

Details

These functions are intended to be used together – one should first check whether build tools are available, and when not, prompt for installation. For example:

compile_model <- function(...) {

  if (rstudioapi::isAvailable()) {

    if (!rstudioapi::buildToolsCheck())
      rstudioapi::buildToolsInstall("Model compilation")

    rstudioapi::buildToolsExec({
      # code requiring build tools here
    })

  }
}

The action parameter is used to communicate (with a prompt) the operation being performed that requires build tool installation. Setting it to NULL or the empty string will suppress that prompt.

Note

The buildToolsCheck(), buildToolsInstall(), and buildToolsExec() functions were added with version 1.2.962 of RStudio.

Call an RStudio API 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 hasFun.

Usage

callFun(fname, ...)

Arguments

Examples

if (rstudioapi::isAvailable()) {
  rstudioapi::callFun("versionInfo")
}

Register and Unregister a Chunk Callback

Description

Register a callback function to be executed after a chunk within an R Markdown document is run.

Usage

registerChunkCallback(callback)

unregisterChunkCallback(id = NULL)

Arguments

Value

For registerChunkCallback(), a unique identifier. That identifier can be passed to unreigsterChunkCallback() to de-register a previously-registered callback.

Chunk Callbacks

The callback argument should be a function accepting two parameters:

• chunkName: The chunk label,

• chunkCode: The code within the chunk.

The function should return an R list of HTML outputs, to be displayed after that chunk has been executed.

Convert a tmTheme to an RStudio Theme

Description

Converts a tmTheme to an rstheme and optionally adds and applies it to RStudio and returns the name of the theme.

Usage

convertTheme(
  themePath,
  add = TRUE,
  outputLocation = NULL,
  apply = FALSE,
  force = FALSE,
  globally = FALSE
)

Arguments

Note

The convertTheme function was introduced in RStudio 1.2.879.

Create a Project Template

Description

Create a project template. See https://rstudio.github.io/rstudio-extensions/rstudio_project_templates.html for more information.

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

Interact with RStudio's Dictionaries

Description

Interact with the hunspell dictionaries used by RStudio for spell checking.

Usage

dictionariesPath()

userDictionariesPath()

Details

dictionariesPath() gives a path to the dictionaries installed and distributed with RStudio.

userDictionariesPath() gives the path where users can provide their own custom hunspell dictionaries.

Note

The dictionariesPath() and userDictionariesPath() functions were introduced with RStudio 1.2.1202.

Create a Document Position

Description

Creates a document_position, which can be used to indicate e.g. the row + column location of the cursor in a document.

Usage

document_position(row, column)

is.document_position(x)

as.document_position(x)

Arguments

Create a Range

Description

A document_range is a pair of document_position objects, with each position indicating the start and end of the range, respectively.

Usage

document_range(start, end = NULL)

is.document_range(x)

as.document_range(x)

Arguments

Value

An list with class document_range and fields:

Execute Command

Description

Executes an arbitrary RStudio command.

Usage

executeCommand(commandId, quiet = FALSE)

Arguments

Details

Most menu commands and many buttons in RStudio can be invoked from the API using this method.

The quiet command governs the behavior of the function when the command does not exist. By default, an error is shown if you attempt to invoke a non-existent command. You should set this to TRUE when invoking a command that may not be available if you don't want your users to see an error.

The command is run asynchronously, so no status is returned.

See the RStudio Server Professional Administration Guide for a list of supported command IDs.

Note

The executeCommand function was introduced in RStudio 1.2.1261.

See Also

registerCommandCallback to be notified of command executions.

Select a file / folder

Description

Prompt the user for the path to a file or folder, using the system file dialogs with RStudio Desktop, and RStudio's own dialogs with RStudio Server.

Usage

selectFile(
  caption = "Select File",
  label = "Select",
  path = getActiveProject(),
  filter = "All Files (*)",
  existing = TRUE
)

selectDirectory(
  caption = "Select Directory",
  label = "Select",
  path = getActiveProject()
)

Arguments

Details

When the selected file resolves within the user's home directory, RStudio will return an aliased path – that is, prefixed with ~/.

Note

The selectFile and selectDirectory functions were added in version 1.1.287 of RStudio.

Navigate to a Directory in the Files Pane

Description

Navigate to a directory in the Files pane. The contents of that directory will be listed and shown in the Files pane.

Usage

filesPaneNavigate(path)

Arguments

Retrieve path to active RStudio project

Description

Get the path to the active RStudio project (if any). If the path contains non-ASCII characters, it will be UTF-8 encoded.

Usage

getActiveProject()

Value

The path to the current project, or NULL if no project is currently open.

Note

The getActiveProject function was added in version 0.99.854 of RStudio.

OAuth2 Tokens for Delegated Azure Resources

Description

When Workbench is using Azure Active Directory for sign-in, this function can return an OAuth2 token for a service Workbench users have delegated access to. This requires configuring delegated permissions in Azure itself.

Usage

getDelegatedAzureToken(resource)

Arguments

Examples

## Not run: 
getDelegatedAzureToken("https://storage.azure.com")

## End(Not run)

Report whether RStudio Desktop or RStudio Server is in use

Description

Use getMode() if you need to differentiate between server and desktop installations of RStudio.

Usage

getMode()

Value

"desktop" for RStudio Desktop installations, and "server" for RStudio Server / RStudio Workbench installations.

Get RStudio Package Dependencies

Description

Gets a list of the all the R packages that RStudio depends on in some way.

Usage

getRStudioPackageDependencies()

Details

The data frame of package dependencies contains the following columns:

name

The name of the R package.

version

The required minimum version of the R package.

location

Where RStudio expects the package to be, cran for a CRAN-like repository or embedded for development packages embedded in RStudio itself.

source

Whether the package should be installed from source.

Value

A data frame containing a row per R package.

Note

The getRStudioPackageDependencies function was introduced in RStudio 1.3.525.

Retrieve Themes

Description

Retrieves a list with information about the current color theme used by RStudio.

Usage

getThemeInfo()

Details

A list is returned with the following elements:

editor

The name of the current editor theme, such as Textmate.

global

The name of the current global theme. One of Modern, Classic, or Sky.

dark

TRUE if the editor theme is dark, FALSE otherwise.

foreground

The current editor theme's default text foreground color, formatted as a CSS-compatible color string, such as rgb(1, 22, 39). Supported since RStudio 1.2.1214.

background

The current editor theme's default text background color, formatted as a CSS-compatible color string. Supported since RStudio 1.2.1214.

Get Theme List

Description

Retrieves a list of the names of all the editor themes installed for RStudio.

Usage

getThemes()

Note

The getThemes function was introduced in RStudio 1.2.879.

Determine the version of RStudio

Description

Use getVersion() to determine the current version of RStudio. This can be useful for R packages which need to gate certain functionality based on the version of RStudio currently available.

Usage

getVersion()

Value

A "numeric_version" object, giving the version of RStudio in use.

Check if console supports ANSI color escapes.

Description

Check if the RStudio console supports ANSI color escapes.

Usage

hasColorConsole()

Value

TRUE if ANSI color escapes are supported; FALSE otherwise.

Note

The hasColorConsole function was added in version 1.1.216 of RStudio.

Examples

## Not run: 
if (rstudioapi::hasColorConsole()) {
  message("RStudio console supports ANSI color sequences.")
}


## End(Not run)

Exists/get for RStudio functions

Description

These are specialized versions of get and exists that look in the rstudio package namespace. If RStudio is not running, hasFun will return FALSE.

Usage

hasFun(name, version_needed = NULL, ...)

findFun(name, version_needed = NULL, ...)

Arguments

Examples

rstudioapi::hasFun("viewer")

Highlight UI Elements within the RStudio IDE

Description

This function can be used to highlight UI elements within the RStudio IDE. UI elements can be selected using query selectors; most commonly, one should choose to highlight elements based on their IDs when available.

Usage

highlightUi(queries)

Arguments

Details

The tool at:

Help -> Diagnostics -> Show DOM Elements 

can be useful for identifying the classes and IDs assigned to the different elements within RStudio.

Queries

Elements are selected using the same queries as through the web querySelectorAll() API. See https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll for more details.

For example, to highlight the Save icon within the Source pane, one might use:

rstudioapi::highlightUi("#rstudio_tb_savesourcedoc") 

In some cases, multiple UI elements need to be highlighted – e.g. if you want to highlight both a menu button, and a menu item within the menu displayed after the button is pressed. We'll use the Environment Pane's Import Dataset button as an example. To highlight the ⁠From Text (readr)⁠ command, you might use:

rstudioapi::highlightUi( list(
list(query = "#rstudio_mb_import_dataset", parent = 0L), list(query =
"#rstudio_label_from_text_readr_command", parent = 1L) ) ) 

Note

The highlightUi function was introduced in RStudio 1.3.658.

Examples

## Not run: rstudioapi::highlightUi("#rstudio_workbench_panel_git")

# clear current highlights
## Not run: rstudioapi::highlightUi("")

# highlight within an RMD
## Not run: rstudioapi::highlightUi(".rstudio_chunk_setup .rstudio_run_chunk")

# Optionally provide a callback adjacent to 
# the queries that will be executed when the 
# highlighted element is clicked on.
## Not run: rstudioapi::highlightUi(
  list(
    list(
      query="#rstudio_workbench_panel_git", 
      callback="rstudioapi::highlightUi('')"
    )
  )
)
## End(Not run)

Check if RStudio is running

Description

Check if RStudio is running.

Usage

isAvailable(version_needed = NULL, child_ok = FALSE)

verifyAvailable(version_needed = NULL)

Arguments

Value

isAvailable a boolean; verifyAvailable an error message if RStudio is not running

Examples

rstudioapi::isAvailable()
## Not run: rstudioapi::verifyAvailable()

Detect RStudio Jobs

Description

Use this function to detect whether RStudio is running an R "job". These jobs are normally used for actions taken in the Jobs tab, as well as within the R build pane.

Usage

isJob()

isBackgroundJob()

isWorkbenchJob()

Details

isWorkbenchJob() is used to detect scripts which have been launched as Workbench jobs, and is only available in RStudio Workbench 2024.04 or newer. These jobs use the RStudio Launcher to run R scripts on remote clusters, as opposed to isBackgroundJob(), which is used to detect background jobs which are run on the local machine.

This function is primarily intended to be used by package authors, who need to customize the behavior of their methods when run within an RStudio job.

Value

Boolean; TRUE if this is an RStudio job.

Add a Job

Description

Inform RStudio's Background Jobs pane that a job has been added.

Usage

jobAdd(
  name,
  status = "",
  progressUnits = 0L,
  actions = NULL,
  running = FALSE,
  autoRemove = TRUE,
  show = TRUE
)

Arguments

Value

An ID representing the newly added job, used as a handle to provide further updates of the job's status.

Actions

The actions parameter is a named list of functions that the user can invoke on the job; for example: actions = list(stop = function(id) { ... }). The function will be passed a parameter named id with the job ID that invoked it.

There are three special action names:

stop

If there is an action named stop, then the job will have a Stop button in in the Jobs pane, and pressing that button will invoke the stop action.

info

If there is an action named info, then the job will have an informational link in the Background Jobs pane rather than an output display, and clicking the link will invoke the info action.

replay

If there is an action named replay, then the job will have a Replay button that displays when the job has finished running. Clicking the button will invoke the replay action.

See Also

Other jobs: jobAddOutput(), jobAddProgress(), jobGetState(), jobList(), jobRemove(), jobRunScript(), jobSetProgress(), jobSetState(), jobSetStatus()

Add Background Job Output

Description

Adds text output to a background job.

Usage

jobAddOutput(job, output, error = FALSE)

Arguments

See Also

Other jobs: jobAdd(), jobAddProgress(), jobGetState(), jobList(), jobRemove(), jobRunScript(), jobSetProgress(), jobSetState(), jobSetStatus()

Add Background Job Progress

Description

Adds incremental progress units to a background job.

Usage

jobAddProgress(job, units)

Arguments

See Also

Other jobs: jobAdd(), jobAddOutput(), jobGetState(), jobList(), jobRemove(), jobRunScript(), jobSetProgress(), jobSetState(), jobSetStatus()

Get Background Job State

Description

Get Background Job State

Usage

jobGetState(job)

Arguments

See Also

Other jobs: jobAdd(), jobAddOutput(), jobAddProgress(), jobList(), jobRemove(), jobRunScript(), jobSetProgress(), jobSetState(), jobSetStatus()

List Background Jobs

Description

List any registered background jobs.

Usage

jobList()

See Also

Other jobs: jobAdd(), jobAddOutput(), jobAddProgress(), jobGetState(), jobRemove(), jobRunScript(), jobSetProgress(), jobSetState(), jobSetStatus()

Remove a Background Job

Description

Remove a background job from RStudio's Background Jobs pane.

Usage

jobRemove(job)

Arguments

See Also

Other jobs: jobAdd(), jobAddOutput(), jobAddProgress(), jobGetState(), jobList(), jobRunScript(), jobSetProgress(), jobSetState(), jobSetStatus()

Run R Script As Background Job

Description

Starts an R script as a background job.

Usage

jobRunScript(
  path,
  name = NULL,
  encoding = "unknown",
  workingDir = NULL,
  importEnv = FALSE,
  exportEnv = ""
)

Arguments

See Also

Other jobs: jobAdd(), jobAddOutput(), jobAddProgress(), jobGetState(), jobList(), jobRemove(), jobSetProgress(), jobSetState(), jobSetStatus()

Set Background Job Progress

Description

Updates the progress for a background job.

Usage

jobSetProgress(job, units)

Arguments

See Also

Other jobs: jobAdd(), jobAddOutput(), jobAddProgress(), jobGetState(), jobList(), jobRemove(), jobRunScript(), jobSetState(), jobSetStatus()

Set Background Job State

Description

Changes the state of a background job.

Usage

jobSetState(
  job,
  state = c("idle", "running", "succeeded", "cancelled", "failed")
)

Arguments

States

The following states are supported:

idle

The job is waiting to run.

running

The job is actively running.

succeeded

The job has finished successfully.

cancelled

The job was cancelled.

failed

The job finished but did not succeed.

See Also

Other jobs: jobAdd(), jobAddOutput(), jobAddProgress(), jobGetState(), jobList(), jobRemove(), jobRunScript(), jobSetProgress(), jobSetStatus()

Set Background Job Status

Description

Update a background job's informational status text.

Usage

jobSetStatus(job, status)

Arguments

See Also

Other jobs: jobAdd(), jobAddOutput(), jobAddProgress(), jobGetState(), jobList(), jobRemove(), jobRunScript(), jobSetProgress(), jobSetState()

Check if Workbench Launcher is Available

Description

Check if the Workbench launcher is available and configured to support Workbench jobs; that is, jobs normally launched by the user through the RStudio IDE's user interface.

Usage

launcherAvailable()

See Also

Other job-launcher functionality: launcherConfig(), launcherContainer(), launcherControlJob(), launcherGetInfo(), launcherGetJob(), launcherGetJobs(), launcherHostMount(), launcherNfsMount(), launcherPlacementConstraint(), launcherResourceLimit(), launcherSubmitJob(), launcherSubmitR()

Define a Workbench Launcher Configuration

Description

Define a Workbench launcher configuration, suitable for use with the config argument to launcherSubmitJob().

Usage

launcherConfig(name, value = NULL)

Arguments

See Also

Other job-launcher functionality: launcherAvailable(), launcherContainer(), launcherControlJob(), launcherGetInfo(), launcherGetJob(), launcherGetJobs(), launcherHostMount(), launcherNfsMount(), launcherPlacementConstraint(), launcherResourceLimit(), launcherSubmitJob(), launcherSubmitR()

Define a Workbench Launcher Container

Description

Define a launcher container, suitable for use with the container argument to launcherSubmitJob().

Usage

launcherContainer(image, runAsUserId = NULL, runAsGroupId = NULL)

Arguments

See Also

Other job-launcher functionality: launcherAvailable(), launcherConfig(), launcherControlJob(), launcherGetInfo(), launcherGetJob(), launcherGetJobs(), launcherHostMount(), launcherNfsMount(), launcherPlacementConstraint(), launcherResourceLimit(), launcherSubmitJob(), launcherSubmitR()

Interact with (Control) a Workbench Job

Description

Interact with a Workbench job.

Usage

launcherControlJob(
  jobId,
  operation = c("suspend", "resume", "stop", "kill", "cancel")
)

Arguments

See Also

Other job-launcher functionality: launcherAvailable(), launcherConfig(), launcherContainer(), launcherGetInfo(), launcherGetJob(), launcherGetJobs(), launcherHostMount(), launcherNfsMount(), launcherPlacementConstraint(), launcherResourceLimit(), launcherSubmitJob(), launcherSubmitR()

Retrieve Workbench Launcher Information

Description

Retrieve information about the Workbench launcher, as well as the different clusters that the launcher has been configured to use.

Usage

launcherGetInfo()

See Also

Other job-launcher functionality: launcherAvailable(), launcherConfig(), launcherContainer(), launcherControlJob(), launcherGetJob(), launcherGetJobs(), launcherHostMount(), launcherNfsMount(), launcherPlacementConstraint(), launcherResourceLimit(), launcherSubmitJob(), launcherSubmitR()

Retrieve Workbench Job Information

Description

Retrieve information on a Workbench job with id jobId.

Usage

launcherGetJob(jobId)

Arguments

See Also

Other job-launcher functionality: launcherAvailable(), launcherConfig(), launcherContainer(), launcherControlJob(), launcherGetInfo(), launcherGetJobs(), launcherHostMount(), launcherNfsMount(), launcherPlacementConstraint(), launcherResourceLimit(), launcherSubmitJob(), launcherSubmitR()

Retrieve Workbench Job Information

Description

Retrieve information on Workbench jobs.

Usage

launcherGetJobs(
  statuses = NULL,
  fields = NULL,
  tags = NULL,
  includeSessions = FALSE
)

Arguments

See Also

Other job-launcher functionality: launcherAvailable(), launcherConfig(), launcherContainer(), launcherControlJob(), launcherGetInfo(), launcherGetJob(), launcherHostMount(), launcherNfsMount(), launcherPlacementConstraint(), launcherResourceLimit(), launcherSubmitJob(), launcherSubmitR()

Define a Workbench Launcher Host Mount

Description

Define a launcher host mount, suitable for use with the mounts argument to launcherSubmitJob(). This can be used to mount a path from the host into the generated container.

Usage

launcherHostMount(path, mountPath, readOnly = TRUE)

Arguments

See Also

Other job-launcher functionality: launcherAvailable(), launcherConfig(), launcherContainer(), launcherControlJob(), launcherGetInfo(), launcherGetJob(), launcherGetJobs(), launcherNfsMount(), launcherPlacementConstraint(), launcherResourceLimit(), launcherSubmitJob(), launcherSubmitR()

Define a Workbench Launcher NFS Mount

Description

Define a launcher NFS mount, suitable for use with the mounts argument to launcherSubmitJob(). This can be used to mount a path from a networked filesystem into a newly generated container.

Usage

launcherNfsMount(host, path, mountPath, readOnly = TRUE)

Arguments

See Also

Other job-launcher functionality: launcherAvailable(), launcherConfig(), launcherContainer(), launcherControlJob(), launcherGetInfo(), launcherGetJob(), launcherGetJobs(), launcherHostMount(), launcherPlacementConstraint(), launcherResourceLimit(), launcherSubmitJob(), launcherSubmitR()

Define a Workbench Launcher Placement Constraint

Description

Define a launcher placement constraint, suitable for use with the placementConstraints argument to launcherSubmitJob().

Usage

launcherPlacementConstraint(name, value = NULL)

Arguments

See Also

Other job-launcher functionality: launcherAvailable(), launcherConfig(), launcherContainer(), launcherControlJob(), launcherGetInfo(), launcherGetJob(), launcherGetJobs(), launcherHostMount(), launcherNfsMount(), launcherResourceLimit(), launcherSubmitJob(), launcherSubmitR()

Define a Workbench Launcher Resource Limit

Description

Define a launcher resource limit, suitable for use with the resourceLimits argument to launcherSubmitJob().

Usage

launcherResourceLimit(type, value)

Arguments

See Also

Other job-launcher functionality: launcherAvailable(), launcherConfig(), launcherContainer(), launcherControlJob(), launcherGetInfo(), launcherGetJob(), launcherGetJobs(), launcherHostMount(), launcherNfsMount(), launcherPlacementConstraint(), launcherSubmitJob(), launcherSubmitR()

Submit a Workbench Job

Description

Submit a Workbench job. See https://docs.posit.co/job-launcher/latest/index.html for more information.

Usage

launcherSubmitJob(
  name,
  cluster = "Local",
  tags = NULL,
  command = NULL,
  exe = NULL,
  args = NULL,
  environment = NULL,
  stdin = NULL,
  stdoutFile = NULL,
  stderrFile = NULL,
  workingDirectory = NULL,
  host = NULL,
  container = NULL,
  exposedPorts = NULL,
  mounts = NULL,
  placementConstraints = NULL,
  resourceLimits = NULL,
  queues = NULL,
  config = NULL,
  user = Sys.getenv("USER"),
  applyConfigSettings = TRUE
)

Arguments

See Also

Other job-launcher functionality: launcherAvailable(), launcherConfig(), launcherContainer(), launcherControlJob(), launcherGetInfo(), launcherGetJob(), launcherGetJobs(), launcherHostMount(), launcherNfsMount(), launcherPlacementConstraint(), launcherResourceLimit(), launcherSubmitR()

Execute an R Script as a Workbench Job

Description

Convenience function for running an R script as a Workbench job using whichever R is found on the path in the Workbench launcher cluster.

Usage

launcherSubmitR(script, cluster = "Local", container = NULL)

Arguments

Details

See launcherSubmitJob() for running jobs with full control over command, environment, and so forth.

See Also

Other job-launcher functionality: launcherAvailable(), launcherConfig(), launcherContainer(), launcherControlJob(), launcherGetInfo(), launcherGetJob(), launcherGetJobs(), launcherHostMount(), launcherNfsMount(), launcherPlacementConstraint(), launcherResourceLimit(), launcherSubmitJob()

Navigate to file

Description

Open a file in RStudio, optionally at a specified location.

Usage

navigateToFile(
  file = character(0),
  line = -1L,
  column = -1L,
  moveCursor = TRUE
)

Arguments

Details

The 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 file argument is empty (the default), then the file is the file currently in view if one exists. If the line and column arguments are both equal to -1L (the default), then the cursor position in the document that is opened will be preserved. Alternatively, moveCursor can be set to FALSE to preserve the cursor position.

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 View on the function, which has the advantage of falling back on deparsing if the file is not available.

Note

The navigateToFile function was added in version 0.99.719 of RStudio.

Persistent keys and values

Description

Store persistent keys and values. Storage is per-project; if there is no project currently active, then a global store is used.

Usage

setPersistentValue(name, value)

getPersistentValue(name)

Arguments

Value

The stored value as a character vector (NULL if no value of the specified name is available).

Note

The setPersistentValue and getPersistentValue functions were added in version 1.1.57 of RStudio.

Preview an Rd topic in the Help pane

Description

Preview an Rd topic in the Help pane.

Usage

previewRd(rdFile)

Arguments

Note

The previewRd function was added in version 0.98.191 of RStudio.

Examples

## Not run: 
rstudioapi::previewRd("~/MyPackage/man/foo.Rd")

## End(Not run)

Preview SQL statement

Description

Makes use of 'DBI' and dbGetQuery() to preview a SQL statement for a given 'DBI' connection.

Usage

previewSql(conn, statement, ...)

Arguments

Note

The previewSql function was introduced in RStudio 1.2.600

Extract the Primary Selection

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 primary_selection() to extract the primary selection.

Usage

primary_selection(x, ...)

Arguments

Open a project in RStudio

Description

Initialize and open RStudio projects.

Usage

openProject(path = NULL, newSession = FALSE)

initializeProject(path = getwd())

Arguments

Details

Calling 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 documentSaveAll().

Note

The openProject and initializeProject functions were added in version 1.1.287 of RStudio.

Read Preference

Description

Reads a user preference, useful to remember preferences across different R sessions for the same user.

Usage

readPreference(name, default)

Arguments

Details

User preferences can have arbitrary names and values. You must write the preference with writePreference before it can be read (otherwise its default value will be returned).

Note

The readPreference function was added in version 1.1.67 of RStudio.

See Also

readRStudioPreference, which reads RStudio IDE preferences.

Read RStudio Preference

Description

Reads an internal RStudio IDE preference for the current user.

Usage

readRStudioPreference(name, default)

Arguments

Details

RStudio IDE internal preferences include the values displayed in RStudio's Global Options dialog as well as a number of additional settings.

Note

The readRStudioPreference function was added in version 1.3.387 of RStudio.

See Also

readPreference, which can be used to read arbitrary user (non-RStudio) preferences set with writePreference.

link{writeRStudioPreference}, which can be used to write internal RStudio IDE preferences.

Examples

## Not run: 
# Get indentation settings
spaces <- rstudioapi::readRStudioPreference("num_spaces_for_tab", FALSE)
message("Using ", spaces, " per tab.")

## End(Not run)

Register Command Callback

Description

Registers a callback to be executed when an RStudio command is invoked.

Usage

registerCommandCallback(commandId, callback)

Arguments

Details

RStudio commands can be invoked from menus, toolbars, keyboard shortcuts, and the Command Palette, as well as the RStudio API. The callback will be executed whenever the command is invoked, regardless of how the invocation was triggered.

See the RStudio Server Professional Administration Guide appendix for a list of supported command IDs.

The callback is executed after the command has been run, but as some commands initiate asynchronous processes, there is no guarantee that the command has finished its work when the callback is invoked.

If you're having trouble figuring out the ID of a command you want to listen for, it can be helpful to discover it by listening to the full command stream; see the example in registerCommandStreamCallback for details.

Note that no error will be raised if you use a command ID that does not exist.

Value

A handle representing the registration. Pass this handle to unregisterCommandCallback to unregister the callback.

Note

The registerCommandCallback function was introduced in RStudio 1.4.1589.

See Also

unregisterCommandCallback to unregister the callback, and registerCommandStreamCallback to be notified whenever any command is executed.

Examples

## Not run: 
# Set up a callback to display an encouraging dialog whenever 
# the user knits a document
handle <- rstudioapi::registerCommandCallback(
  "knitDocument", 
  function() {
    rstudioapi::showDialog(
      "Achievement",
      "Congratulations, you have knitted a document. Well done."
    )
  })

# Knit the document interactively and observe the dialog

# Later: Unregister the callback
rstudioapi::unregisterCommandCallback(handle)

## End(Not run)

Register Command Stream Callback

Description

Registers a callback to be executed whenever any RStudio command is invoked.

Usage

registerCommandStreamCallback(callback)

Arguments

Details

The callback function will be given a single argument with the ID of the command that was invoked. See the RStudio Server Professional Administration Guide appendix for a list of command IDs.

Note that there is a small performance penalty incurred across the IDE when a command stream listener is present. If you only need to listen to a few specific commands, it is recommended to set up callbacks for them individually using registerCommandCallback.

Value

A handle representing the registration. Pass this handle to unregisterCommandCallback to unregister the callback.

Note

The registerCommandStreamCallback function was introduced in RStudio 1.4.1589.

See Also

unregisterCommandCallback to unregister the callback, and registerCommandCallback to be notified whenever a specific command is executed.

Examples

## Not run: 
# Set up a callback to print the ID of commands executed to the console.
handle <- rstudioapi::registerCommandStreamCallback(function(id) {
  message("Command executed: ", id)
})

# Later: Unregister the callback
rstudioapi::unregisterCommandCallback(handle)

## End(Not run)

Remove a custom theme from RStudio.

Description

Remove a custom theme from RStudio.

Usage

removeTheme(name)

Arguments

Note

The removeTheme function was introduced in RStudio 1.2.879.

Restart the R Session

Description

Restart the RStudio session.

Usage

restartSession(command = "", clean = FALSE)

Arguments

Note

The restartSession function was added in version 1.1.281 of RStudio. Support for the clean argument was added for version 2024.04 release of RStudio; it is silently ignored in older versions of RStudio.

Interact with Documents open in RStudio

Description

Use these functions to interact with documents open in RStudio.

Usage

insertText(location = NULL, text = NULL, id = NULL)

modifyRange(location = NULL, text = NULL, id = NULL)

setDocumentContents(text, id = NULL)

setCursorPosition(position, id = NULL)

setSelectionRanges(ranges, id = NULL)

documentId(allowConsole = TRUE)

documentPath(id = NULL)

documentSave(id = NULL)

documentSaveAll()

documentNew(
  text,
  type = c("r", "rmarkdown", "sql"),
  position = document_position(0, 0),
  execute = FALSE
)

documentOpen(path, line = -1L, col = -1L, moveCursor = TRUE)

documentClose(id = NULL, save = TRUE)

Arguments

Details

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

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

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

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

    # insert text at the start of the document
    insertText(c(1, 1), "# Hello\n")

    # insert text at the end of the document
    insertText(Inf, "# Hello\n")

    # comment out the first 5 rows
    pos <- Map(c, 1:5, 1)
    insertText(pos, "# ")

    # uncomment the first 5 rows, undoing the previous action
    rng <- Map(c, Map(c, 1:5, 1), Map(c, 1:5, 3))
    modifyRange(rng, "")

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

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

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

Note

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

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

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

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

The documentNew function was introduced in RStudio 1.2.640.

The documentOpen function was introduced in RStudio 1.4.1106.

The documentClose function was introduced in RStudio 1.2.1255

Retrieve Information about an RStudio Editor

Description

Returns information about an RStudio editor.

Usage

getActiveDocumentContext()

getSourceEditorContext(id = NULL)

getConsoleEditorContext()

Arguments

Details

The selection field returned is a list of document selection objects. A document selection is just a pairing of a document range, and the text within that range.

Value

A list with elements:

Note

The getActiveDocumentContext function was added with version 0.99.796 of RStudio, while the getSourceEditorContext and the getConsoleEditorContext functions were added with version 0.99.1111.

Save active RStudio plot image

Description

Save the plot currently displayed in the Plots pane as an image.

Usage

savePlotAsImage(
  file,
  format = c("png", "jpeg", "bmp", "tiff", "emf", "svg", "eps"),
  width,
  height
)

Arguments

Note

The savePlotAsImage function was introduced in RStudio 1.1.57.

Manipulate User Selections in the RStudio IDE

Description

These functions allow users of the rstudioapi package to read and write the user's current selection within the RStudio IDE.

Usage

selectionGet(id = NULL)

selectionSet(value = NULL, id = NULL)

Arguments

Send code to the R console

Description

Send code to the R console, and optionally execute it.

Usage

sendToConsole(code, execute = TRUE, echo = TRUE, focus = TRUE, animate = FALSE)

Arguments

Note

The sendToConsole function was added in version 0.99.787 of RStudio.

Examples

## Not run: 
rstudioapi::sendToConsole(".Platform", execute = FALSE, animate = TRUE)

## End(Not run)

Set ghost text

Description

Set ghost text in the current document. The ghost text will be inserted at the current cursor position. Ghost text can be inserted into the document by pressing Tab, and will be automatically dismissed if the user navigates the cursor away.

Usage

setGhostText(text)

Arguments

Show Dialog Box

Description

Shows a dialog box with a given title and contents.

Usage

showDialog(title, message, url = "", timeout = 60)

Arguments

Note

The showDialog function was added in version 1.1.67 of RStudio.

Examples

if (rstudioapi::isAvailable()) {
  rstudioapi::showDialog("Example Dialog", "This is an <b>example</b> dialog.")
}

Show Prompt Dialog Box

Description

Shows a dialog box with a prompt field.

Usage

showPrompt(title, message, default = NULL, timeout = 60)

Arguments

Note

The showPrompt function was added in version 1.1.67 of RStudio.

Show Question Dialog Box

Description

Shows a dialog box asking a question.

Usage

showQuestion(title, message, ok = NULL, cancel = NULL, timeout = 60)

Arguments

Note

The showQuestion function was added in version 1.1.67 of RStudio.

Display source markers

Description

Display user navigable source markers in a pane within RStudio.

Usage

sourceMarkers(
  name,
  markers,
  basePath = NULL,
  autoSelect = c("none", "first", "error")
)

Arguments

Details

The 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):

Note the marker message can contain ANSI SGR codes for formatting. The cli package can format text for style and color.

Note

The sourceMarkers function was added in version 0.99.225 of RStudio.

Get System Username

Description

Returns the system username of the current user.

Usage

systemUsername()

Activate Terminal

Description

Ensure terminal is running and optionally bring to front in RStudio.

Usage

terminalActivate(id = NULL, show = TRUE)

Arguments

Note

The terminalActivate function was added in version 1.1.350 of RStudio.

Examples

## Not run: 
# 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)

## End(Not run)

Get Terminal Buffer

Description

Returns contents of a terminal buffer.

Usage

terminalBuffer(id, stripAnsi = TRUE)

Arguments

Value

The terminal contents, one line per row.

Note

The terminalBuffer function was added in version 1.1.350 of RStudio.

Is Terminal Busy

Description

Are terminals reporting that they are busy?

Usage

terminalBusy(id)

Arguments

Details

This feature is only supported on RStudio Desktop for Mac and Linux, and RStudio Server. It always returns FALSE on RStudio Desktop for Microsoft Windows.

Value

a boolean

Note

The terminalBusy function was added in version 1.1.350 of RStudio.

Examples

## Not run: 
# 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")

## End(Not run)

Clear Terminal Buffer

Description

Clears the buffer for specified terminal.

Usage

terminalClear(id)

Arguments

Note

The terminalClear function was added in version 1.1.350 of RStudio.

Examples

## Not run: 
termId <- rstudioapi::terminalCreate()
rstudioapi::terminalSend(termId, 'ls -l\n')
Sys.sleep(3)
rstudioapi::terminalClear(termId)

## End(Not run)

Retrieve Information about RStudio Terminals

Description

Returns information about RStudio terminal instances.

Usage

terminalContext(id)

Arguments

Value

A list with elements:

Note

The terminalContext function was added in version 1.1.350 of RStudio.

Examples

## Not run: 
termId <- rstudioapi::terminalCreate("example", show = FALSE)
View(rstudioapi::terminalContext(termId))


## End(Not run)

Create a Terminal

Description

Create a new Terminal.

Usage

terminalCreate(caption = NULL, show = TRUE, shellType = NULL)

Arguments

Value

The terminal identifier as a character vector (NULL if unable to create the terminal or the given terminal caption is already in use).

Note

The terminalCreate function was added in version 1.1.350 of RStudio and the ability to specify shellType was added in version 1.2.696.

Examples

## Not run: 
termId <- rstudioapi::terminalCreate('My Terminal')

## End(Not run)

Execute Command

Description

Execute a command, showing results in the terminal pane.

Usage

terminalExecute(command, workingDir = NULL, env = character(), show = TRUE)

Arguments

Value

The terminal identifier as a character vector (NULL if unable to create the terminal).

Note

The terminalExecute function was added in version 1.1.350 of RStudio.

Examples

## Not run: 
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)

## End(Not run)

Terminal Exit Code

Description

Get exit code of terminal process, or NULL if still running.

Usage

terminalExitCode(id)

Arguments

Value

The exit code as an integer vector, or NULL if process still running.

Note

The terminalExitCode function was added in version 1.1.350 of RStudio.

Kill Terminal

Description

Kill processes and close a terminal.

Usage

terminalKill(id)

Arguments

Note

The terminalKill function was added in version 1.1.350 of RStudio.

Get All Terminal Ids

Description

Return a character vector containing all the current terminal identifiers.

Usage

terminalList()

Value

The terminal identifiers as a character vector.

Note

The terminalList function was added in version 1.1.350 of RStudio.

Is Terminal Running

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 terminalActivate().

Usage

terminalRunning(id)

Arguments

Value

a boolean

Note

The terminalRunning function was added in version 1.1.350 of RStudio.

Examples

## Not run: 
# 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")
}

## End(Not run)

Send Text to a Terminal

Description

Send text to an existing terminal.

Usage

terminalSend(id, text)

Arguments

Note

The terminalSend function was added in version 1.1.350 of RStudio.

Examples

## Not run: 
termId <- rstudioapi::terminalCreate()
rstudioapi::terminalSend(termId, 'ls -l\n')

## End(Not run)

Get Visible Terminal

Description

Get Visible Terminal

Usage

terminalVisible()

Value

Terminal identifier selected in the client, if any.

Note

The terminalVisible function was added in version 1.1.350 of RStudio.

Translate Local URL

Description

Translates a local URL into an externally accessible URL on RStudio Server.

Usage

translateLocalUrl(url, absolute = FALSE)

Arguments

Details

On RStudio Server, URLs which refer to the local host network address (such as http://localhost:1234/ and http://127.0.0.1:5678/) must be translated in order to be externally accessible from a browser. This method performs the required translation, and returns the translated URL, which RStudio Server uses to proxy HTTP requests.

Returns an unmodified URL on RStudio Desktop, and when the URL does not refer to a local address.

Value

The translated URL.

Unregister Command Callback

Description

Removes a previously registered command callback.

Usage

unregisterCommandCallback(handle)

Arguments

Value

NULL, invisibly.

Note

The unregisterCommandCallback function was introduced in RStudio 1.4.1589.

Updates a Dialog Box

Description

Updates specific properties from the current dialog box.

Usage

updateDialog(...)

Arguments

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.

 updateDialog(code = "con <- NULL") 

Note

The updateDialog function was added in version 1.1.67 of RStudio.

Get User Identity

Description

Returns the identity (displayed name) of the current user.

Usage

userIdentity()

RStudio version information

Description

Query information about the currently running instance of RStudio.

Usage

versionInfo()

Value

An R list with the following elements:

Note

The versionInfo function was added in version 0.97.124 of RStudio.

Examples

## Not run: 
info <- rstudioapi::versionInfo()

# check what version of RStudio is in use
if (info$version >= "1.4") {
  # code specific to versions of RStudio 1.4 and newer
}

# check whether RStudio Desktop or RStudio Server is being used
if (info$mode == "desktop") {
  # code specific to RStudio Desktop
}

# Get the citation
info$citation


## End(Not run)

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 via a web application running on localhost.

Usage

viewer(url, height = NULL)

Arguments

Details

RStudio also sets the global viewer option to the 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 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 "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.

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 viewer_pane query parameter, which is automatically injected into URLs when they are shown in the Viewer. For example, the following URL:

 http://localhost:8100 

When rendered in the Viewer pane is transformed to:

 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.

Note

The viewer function was added in version 0.98.423 of RStudio. The ability to specify maximize for the height parameter was introduced in version 0.99.1001 of RStudio.

Examples

## Not run: 

# 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)

# use 'viewer' option if set, or `utils::browseURL()` if unset
viewer <- getOption("viewer", default = utils::browseURL)
viewer("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)


## End(Not run)

Write Preference

Description

Writes a user preference, useful to remember preferences across different R sessions for the same user.

Usage

writePreference(name, value)

Arguments

Note

The writePreference function was added in version 1.1.67 of RStudio.

See Also

writeRStudioPreference, which changes RStudio IDE preferences.

Write RStudio Preference

Description

Writes an internal RStudio IDE preference for the current user.

Usage

writeRStudioPreference(name, value)

Arguments

Details

RStudio IDE internal preferences include the values displayed in RStudio's Global Options dialog as well as a number of additional settings. Set them carefully; inappropriate values can cause unexpected behavior. See the RStudio Server Professional Administration Guide appendix for your version of RStudio for a full list of preference names and values.

Note

The writeRStudioPreference function was added in version 1.3.387 of RStudio.

See Also

writePreference, which can be used to store arbitrary user (non-RStudio) preferences.

readRStudioPreference, which reads internal RStudio IDE preferences.

Examples

## Not run: 
# Hide RStudio's toolbar.
rstudioapi::writeRStudioPreference("toolbar_visible", FALSE)

## End(Not run)