rstudioapi/ 0000755 0001762 0000144 00000000000 13753327012 012440 5 ustar ligges users rstudioapi/NAMESPACE 0000644 0001762 0000144 00000006126 13753072241 013665 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(addTheme)
export(applyTheme)
export(as.document_position)
export(as.document_range)
export(askForPassword)
export(askForSecret)
export(bugReport)
export(buildToolsCheck)
export(buildToolsExec)
export(buildToolsInstall)
export(callFun)
export(convertTheme)
export(createProjectTemplate)
export(dictionariesPath)
export(documentClose)
export(documentId)
export(documentNew)
export(documentPath)
export(documentSave)
export(documentSaveAll)
export(document_position)
export(document_range)
export(executeCommand)
export(filesPaneNavigate)
export(findFun)
export(getActiveDocumentContext)
export(getActiveProject)
export(getConsoleEditorContext)
export(getPersistentValue)
export(getRStudioPackageDependencies)
export(getSourceEditorContext)
export(getThemeInfo)
export(getThemes)
export(getVersion)
export(hasColorConsole)
export(hasFun)
export(highlightUi)
export(initializeProject)
export(insertText)
export(is.document_position)
export(is.document_range)
export(isAvailable)
export(jobAdd)
export(jobAddOutput)
export(jobAddProgress)
export(jobRemove)
export(jobRunScript)
export(jobSetProgress)
export(jobSetState)
export(jobSetStatus)
export(launcherAvailable)
export(launcherConfig)
export(launcherContainer)
export(launcherControlJob)
export(launcherGetInfo)
export(launcherGetJob)
export(launcherGetJobs)
export(launcherHostMount)
export(launcherNfsMount)
export(launcherPlacementConstraint)
export(launcherResourceLimit)
export(launcherSubmitJob)
export(launcherSubmitR)
export(modifyRange)
export(navigateToFile)
export(openProject)
export(previewRd)
export(previewSql)
export(primary_selection)
export(readPreference)
export(readRStudioPreference)
export(registerChunkCallback)
export(removeTheme)
export(restartSession)
export(savePlotAsImage)
export(selectDirectory)
export(selectFile)
export(selectionGet)
export(selectionSet)
export(sendToConsole)
export(setCursorPosition)
export(setDocumentContents)
export(setPersistentValue)
export(setSelectionRanges)
export(showDialog)
export(showPrompt)
export(showQuestion)
export(sourceMarkers)
export(systemUsername)
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(translateLocalUrl)
export(unregisterChunkCallback)
export(updateDialog)
export(userDictionariesPath)
export(userIdentity)
export(verifyAvailable)
export(versionInfo)
export(viewer)
export(writePreference)
export(writeRStudioPreference)
importFrom(utils,capture.output)
rstudioapi/LICENSE 0000644 0001762 0000144 00000000045 13535525640 013451 0 ustar ligges users YEAR: 2015
COPYRIGHT HOLDER: RStudio
rstudioapi/man/ 0000755 0001762 0000144 00000000000 13752334450 013216 5 ustar ligges users rstudioapi/man/launcherSubmitJob.Rd 0000644 0001762 0000144 00000006422 13752325464 017136 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/launcher-functions.R
\name{launcherSubmitJob}
\alias{launcherSubmitJob}
\title{Submit a Launcher Job}
\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{
\item{name}{A descriptive name to assign to the job.}
\item{cluster}{The name of the cluster this job should be submitted to.}
\item{tags}{A set of user-defined tags, used for searching and querying
jobs.}
\item{command}{The command to run within the job. This is executed via the
system shell. Only one of command or exe should be specified.}
\item{exe}{The (fully pathed) executable to run within the job. Only one of
\code{command} or \code{exe} should be specified.}
\item{args}{An array of arguments to pass to the command / executable.}
\item{environment}{A list of environment variables to be set for processes
launched with this job.}
\item{stdin}{Data to be written to stdin when the job process is launched.}
\item{stdoutFile}{The file used for the job's generated standard output. Not
all launcher plugins support this parameter.}
\item{stderrFile}{The file used for the job's generated standard error. Not
all launcher plugins support this parameter.}
\item{workingDirectory}{The working directory to be used by the command /
executable associated with this job.}
\item{host}{The host that the job is running on, or the desired host during
job submission.}
\item{container}{The container to be used for launched jobs.}
\item{exposedPorts}{The ports that are exposed by services running on a
container. Only applicable to systems that support containers.}
\item{mounts}{A list of mount points. See
\code{\link[=launcherHostMount]{launcherHostMount()}} and
\code{\link[=launcherNfsMount]{launcherNfsMount()}} for more information.}
\item{placementConstraints}{A list of placement constraints. See
\code{\link[=launcherPlacementConstraint]{launcherPlacementConstraint()}}
for more information.}
\item{resourceLimits}{A list of resource limits. See
\code{\link[=launcherResourceLimit]{launcherResourceLimit()}} for more
information.}
\item{queues}{A list of available submission queues for the cluster. Only
applicable to batch systems like LSF.}
\item{config}{A list of cluster-specific configuration options. See
\code{\link[=launcherConfig]{launcherConfig()}} for more information.}
\item{user}{The user-name of the job owner.}
\item{applyConfigSettings}{Apply server-configured mounts, exposedPorts, and
environment, in addition to any specified in this call.}
}
\description{
Submit a launcher job. See
https://docs.rstudio.com/job-launcher/latest/index.html for more
information.
}
\seealso{
Other job submission: \code{\link{launcherConfig}()},
\code{\link{launcherContainer}()}, \code{\link{launcherHostMount}()},
\code{\link{launcherNfsMount}()},
\code{\link{launcherPlacementConstraint}()},
\code{\link{launcherResourceLimit}()}, \code{\link{launcherSubmitR}()}
}
rstudioapi/man/terminalExecute.Rd 0000644 0001762 0000144 00000002130 13752325464 016644 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/terminalExitCode.Rd 0000644 0001762 0000144 00000001205 13752325464 016750 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/sourceMarkers.Rd 0000644 0001762 0000144 00000003322 13752334243 016332 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stubs.R
\name{sourceMarkers}
\alias{sourceMarkers}
\title{Display source markers}
\usage{
sourceMarkers(
name,
markers,
basePath = NULL,
autoSelect = c("none", "first", "error")
)
}
\arguments{
\item{name}{The name of marker set. If there is a market set with this name
already being shown, those markers will be replaced.}
\item{markers}{An \R list, or data.frame, of source markers. See \strong{details}
for more details on the expected format.}
\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}{Auto-select a marker after displaying the marker set?}
}
\description{
Display user navigable source markers in a pane within RStudio.
}
\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 The marker type ("error", "warning", "info", "style", or "usage"). \cr
\code{file} \tab The path to the associated source file. \cr
\code{line} \tab The line number for the associated marker. \cr
\code{column} \tab The column number for the associated marker. \cr
\code{message} \tab A message associated with the marker at this location. \cr
}
Note that if the \code{message} field is of class "html" (i.e.
\code{inherits(message, "html") == TRUE}) then its contents will be treated
as HTML.
}
\note{
The \code{sourceMarkers} function was added in version 0.99.225 of
RStudio.
}
rstudioapi/man/getRStudioPackageDependencies.Rd 0000644 0001762 0000144 00000001637 13752325464 021375 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dependencies.R
\name{getRStudioPackageDependencies}
\alias{getRStudioPackageDependencies}
\title{Get RStudio Package Dependencies}
\usage{
getRStudioPackageDependencies()
}
\value{
A data frame containing a row per R package.
}
\description{
Gets a list of the all the R packages that RStudio depends on in some way.
}
\details{
The data frame of package dependencies contains the following columns:
\describe{ \item{name}{The name of the R package.} \item{version}{The
required minimum version of the R package.} \item{location}{Where RStudio
expects the package to be, \code{cran} for a CRAN-like repository or
\code{embedded} for development packages embedded in RStudio itself.}
\item{source}{Whether the package should be installed from source.} }
}
\note{
The \code{getRStudioPackageDependencies} function was introduced in
RStudio 1.3.525.
}
rstudioapi/man/launcherHostMount.Rd 0000644 0001762 0000144 00000001676 13752325464 017206 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/launcher-functions.R
\name{launcherHostMount}
\alias{launcherHostMount}
\title{Define a Launcher Host Mount}
\usage{
launcherHostMount(path, mountPath, readOnly = TRUE)
}
\arguments{
\item{path}{The host path to be mounted.}
\item{mountPath}{The destination path for the mount in the container.}
\item{readOnly}{Boolean; should the path be mounted read-only?}
}
\description{
Define a launcher host mount, suitable for use with the \code{mounts}
argument to \code{\link[=launcherSubmitJob]{launcherSubmitJob()}}. This can
be used to mount a path from the host into the generated container.
}
\seealso{
Other job submission: \code{\link{launcherConfig}()},
\code{\link{launcherContainer}()}, \code{\link{launcherNfsMount}()},
\code{\link{launcherPlacementConstraint}()},
\code{\link{launcherResourceLimit}()}, \code{\link{launcherSubmitJob}()},
\code{\link{launcherSubmitR}()}
}
rstudioapi/man/jobAdd.Rd 0000644 0001762 0000144 00000003671 13752325464 014704 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/jobs.R
\name{jobAdd}
\alias{jobAdd}
\title{Add a Job}
\usage{
jobAdd(
name,
status = "",
progressUnits = 0L,
actions = NULL,
running = FALSE,
autoRemove = TRUE,
show = TRUE
)
}
\arguments{
\item{name}{The job's name.}
\item{status}{The initial status text for the job; optional.}
\item{progressUnits}{The integer number of units of work in the job; for
example, \code{100L} if the job's progress is expressed in percentages. Use
\code{0L} if the number of units of work is unknown.}
\item{actions}{A list of actions that can be performed on the job (see
Actions).}
\item{running}{Whether the job is currently running.}
\item{autoRemove}{Whether to remove the job from the Jobs pane when it's
complete.}
\item{show}{Whether to show the job in the Jobs pane.}
}
\value{
An ID representing the newly added job, used as a handle to provide
further updates of the job's status.
}
\description{
Inform RStudio's Jobs pane that a job has been added.
}
\section{Actions}{
The \code{actions} parameter is a named list of functions that the user can
invoke on the job; for example: \code{actions = list(stop = function(id) {
... })}. The function will be passed a parameter named \code{id} with the
job ID that invoked it.
There are two special action names: \describe{ \item{stop}{If there is an
action named \code{stop}, then the job will have a Stop button in in the
Jobs pane, and pressing that button will invoke the \code{stop} action.}
\item{info}{If there is an action named \code{info}, then the job will have
an informational link in the Jobs pane rather than an output display, and
clicking the link will invoke the \code{info} action.} }
}
\seealso{
Other jobs: \code{\link{jobAddOutput}()},
\code{\link{jobAddProgress}()}, \code{\link{jobRemove}()},
\code{\link{jobRunScript}()}, \code{\link{jobSetProgress}()},
\code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
}
rstudioapi/man/previewRd.Rd 0000644 0001762 0000144 00000000721 13752334243 015454 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stubs.R
\name{previewRd}
\alias{previewRd}
\title{Preview an Rd topic in the Help pane}
\usage{
previewRd(rdFile)
}
\arguments{
\item{rdFile}{The path to an \code{.Rd} file.}
}
\description{
Preview an Rd topic in the Help pane.
}
\note{
The \code{previewRd} function was added in version 0.98.191 of
RStudio.
}
\examples{
\dontrun{
rstudioapi::previewRd("~/MyPackage/man/foo.Rd")
}
}
rstudioapi/man/hasFun.Rd 0000644 0001762 0000144 00000001526 13752325464 014742 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/jobSetState.Rd 0000644 0001762 0000144 00000001635 13752325464 015746 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/jobs.R
\name{jobSetState}
\alias{jobSetState}
\title{Set Job State}
\usage{
jobSetState(
job,
state = c("idle", "running", "succeeded", "cancelled", "failed")
)
}
\arguments{
\item{job}{The ID of the job on which to change state.}
\item{state}{The new job state.}
}
\description{
Changes the state of a job.
}
\section{States}{
The following states are supported: \describe{ \item{idle}{The job is
waiting to run.} \item{running}{The job is actively running.}
\item{succeeded}{The job has finished successfully.} \item{cancelled}{The
job was cancelled.} \item{failed}{The job finished but did not succeed.} }
}
\seealso{
Other jobs: \code{\link{jobAddOutput}()},
\code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
\code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
\code{\link{jobSetProgress}()}, \code{\link{jobSetStatus}()}
}
rstudioapi/man/sendToConsole.Rd 0000644 0001762 0000144 00000001417 13752334243 016267 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, echo = TRUE, focus = TRUE)
}
\arguments{
\item{code}{The \R code to be executed, as a character vector.}
\item{execute}{Boolean; execute the code immediately or just enter the text
into the console?}
\item{echo}{Boolean; echo the code in the console as it is executed?}
\item{focus}{Boolean; focus the console after sending code?}
}
\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/document_range.Rd 0000644 0001762 0000144 00000001570 13752325464 016507 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{is.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 \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/showDialog.Rd 0000644 0001762 0000144 00000001350 13752325464 015611 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 = "")
}
\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}{An 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/launcherContainer.Rd 0000644 0001762 0000144 00000001720 13752325464 017156 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/launcher-functions.R
\name{launcherContainer}
\alias{launcherContainer}
\title{Define a Launcher Container}
\usage{
launcherContainer(image, runAsUserId = NULL, runAsGroupId = NULL)
}
\arguments{
\item{image}{The container image to use.}
\item{runAsUserId}{The user id to run as within the container. Defaults to
the container-specified user.}
\item{runAsGroupId}{The group id to run as within the container. Defaults to
the container-specified group.}
}
\description{
Define a launcher container, suitable for use with the \code{container}
argument to \code{\link[=launcherSubmitJob]{launcherSubmitJob()}}.
}
\seealso{
Other job submission: \code{\link{launcherConfig}()},
\code{\link{launcherHostMount}()}, \code{\link{launcherNfsMount}()},
\code{\link{launcherPlacementConstraint}()},
\code{\link{launcherResourceLimit}()}, \code{\link{launcherSubmitJob}()},
\code{\link{launcherSubmitR}()}
}
rstudioapi/man/jobSetProgress.Rd 0000644 0001762 0000144 00000001135 13752325464 016465 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/jobs.R
\name{jobSetProgress}
\alias{jobSetProgress}
\title{Set Job Progress}
\usage{
jobSetProgress(job, units)
}
\arguments{
\item{job}{The ID of the job to set progress for.}
\item{units}{The integer number of total units of work completed so far.}
}
\description{
Updates the progress for a job.
}
\seealso{
Other jobs: \code{\link{jobAddOutput}()},
\code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
\code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
\code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
}
rstudioapi/man/readRStudioPreference.Rd 0000644 0001762 0000144 00000002131 13752325464 017733 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/prefs.R
\name{readRStudioPreference}
\alias{readRStudioPreference}
\title{Read RStudio Preference}
\usage{
readRStudioPreference(name, default)
}
\arguments{
\item{name}{The name of the preference.}
\item{default}{The default value of the preference, returned if the
preference is not found.}
}
\description{
Reads an internal RStudio IDE preference for the current user.
}
\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 \code{readRStudioPreference} function was added in version 1.3.387
of RStudio.
}
\examples{
\dontrun{
# Get indentation settings
spaces <- rstudioapi::readRStudioPreference("num_spaces_for_tab", FALSE)
message("Using ", spaces, " per tab.")
}
}
\seealso{
\code{\link{readPreference}}, which can be used to read arbitrary
user (non-RStudio) preferences set with \code{\link{writePreference}}.
\code{link{writeRStudioPreference}}, which can be used to write internal
RStudio IDE preferences.
}
rstudioapi/man/userIdentity.Rd 0000644 0001762 0000144 00000000374 13752325464 016206 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/user.R
\name{userIdentity}
\alias{userIdentity}
\title{Get User Identity}
\usage{
userIdentity()
}
\description{
Returns the identity (displayed name) of the current user.
}
rstudioapi/man/rstudio-editors.Rd 0000644 0001762 0000144 00000002176 13752325464 016660 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{getSourceEditorContext}
\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/bugReport.Rd 0000644 0001762 0000144 00000000565 13752325464 015471 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bug-report.R
\name{bugReport}
\alias{bugReport}
\title{File an RStudio Bug Report}
\usage{
bugReport()
}
\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.
}
rstudioapi/man/getThemes.Rd 0000644 0001762 0000144 00000000517 13752325464 015442 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/themes.R
\name{getThemes}
\alias{getThemes}
\title{Get Theme List}
\usage{
getThemes()
}
\description{
Retrieves a list of the names of all the editor themes installed for
RStudio.
}
\note{
The \code{getThemes} function was introduced in RStudio 1.2.879.
}
rstudioapi/man/convertTheme.Rd 0000644 0001762 0000144 00000003556 13752325464 016166 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/themes.R
\name{convertTheme}
\alias{convertTheme}
\title{Convert a tmTheme to an RStudio Theme}
\usage{
convertTheme(
themePath,
add = TRUE,
outputLocation = NULL,
apply = FALSE,
force = FALSE,
globally = FALSE
)
}
\arguments{
\item{themePath}{A full or relative path to the \code{tmTheme} file to be
converted.}
\item{add}{Whether to add the newly converted theme to RStudio. Setting this
to true will have the same impact as running \code{{
rstudioapi::convertTheme(, outputLocation =
); rstudioapi::addTheme() }}.\cr
Default: \code{TRUE}.}
\item{outputLocation}{A full or relative path where a copy of the converted
theme will be saved. If this value is \code{NULL}, no copy will be saved.\cr
Default: \code{NULL}.}
\item{apply}{Whether to immediately apply the newly added theme. This
paramater cannot be set to \code{TRUE} if \code{add} is set to \code{FALSE}.
Setting this and \code{add} to \code{TRUE} has the same impact as running
\code{{ rstudioapi::convertTheme(, outputLocation =
); rstudioapi::addTheme();
rstudioapi::applyTheme() }}.\cr Default: \code{FALSE}.}
\item{force}{Whether to force the operation and overwrite an existing file
with the same name.\cr Default: \code{FALSE}.}
\item{globally}{Whether to install this theme for the current user or all
users. If set to \code{TRUE} this will attempt to install the theme for all
users, which may require administrator privileges. Only applies when
\code{add} is \code{TRUE}. \cr Default: \code{FALSE}.}
}
\description{
Converts a \code{tmTheme} to an \code{rstheme} and optionally adds and
applies it to RStudio and returns the name of the theme.
}
\note{
The \code{convertTheme} function was introduced in RStudio 1.2.879.
}
rstudioapi/man/filesPaneNavigate.Rd 0000644 0001762 0000144 00000000644 13752325464 017103 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/files-pane.R
\name{filesPaneNavigate}
\alias{filesPaneNavigate}
\title{Navigate to a Directory in the Files Pane}
\usage{
filesPaneNavigate(path)
}
\arguments{
\item{path}{The filesystem path to be shown.}
}
\description{
Navigate to a directory in the Files pane. The contents of that directory
will be listed and shown in the Files pane.
}
rstudioapi/man/createProjectTemplate.Rd 0000644 0001762 0000144 00000003166 13752325464 020006 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 package sources.}
\item{binding}{The 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/getActiveProject.Rd 0000644 0001762 0000144 00000001021 13752334243 016741 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stubs.R
\name{getActiveProject}
\alias{getActiveProject}
\title{Retrieve path to active RStudio project}
\usage{
getActiveProject()
}
\value{
The path to the current project, or \code{NULL} if no project is
currently open.
}
\description{
Get the path to the active RStudio project (if any). If the path contains
non-ASCII characters, it will be UTF-8 encoded.
}
\note{
The \code{getActiveProject} function was added in version 0.99.854 of
RStudio.
}
rstudioapi/man/writeRStudioPreference.Rd 0000644 0001762 0000144 00000002230 13752325464 020152 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/prefs.R
\name{writeRStudioPreference}
\alias{writeRStudioPreference}
\title{Write RStudio Preference}
\usage{
writeRStudioPreference(name, value)
}
\arguments{
\item{name}{The name of the preference.}
\item{value}{The value of the preference.}
}
\description{
Writes an internal RStudio IDE preference for the current user.
}
\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 \code{writeRStudioPreference} function was added in version
1.3.387 of RStudio.
}
\examples{
\dontrun{
# Hide RStudio's toolbar.
rstudioapi::writeRStudioPreference("toolbar_visible", FALSE)
}
}
\seealso{
\code{\link{writePreference}}, which can be used to store arbitrary
user (non-RStudio) preferences.
\code{\link{readRStudioPreference}}, which reads internal RStudio IDE
preferences.
}
rstudioapi/man/versionInfo.Rd 0000644 0001762 0000144 00000001766 13752334243 016020 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stubs.R
\name{versionInfo}
\alias{versionInfo}
\title{RStudio version information}
\usage{
versionInfo()
}
\value{
An \R list with the following elements:
\tabular{ll}{
\code{version} \tab The version of RStudio. \cr
\code{mode} \tab \code{"desktop"} for RStudio Desktop, or \code{"server"} for RStudio Server. \cr
\code{citation} \tab Information on how RStudio can be cited in academic publications. \cr
}
}
\description{
Query information about the currently running instance of RStudio.
}
\note{
The \code{versionInfo} function was added in version 0.97.124 of
RStudio.
}
\examples{
\dontrun{
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
}
}
rstudioapi/man/addTheme.Rd 0000644 0001762 0000144 00000002124 13752325464 015224 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/themes.R
\name{addTheme}
\alias{addTheme}
\title{Add a Custom Editor Theme}
\usage{
addTheme(themePath, apply = FALSE, force = FALSE, globally = FALSE)
}
\arguments{
\item{themePath}{A full or relative path or URL to an \code{rstheme} or
\code{tmtheme} to be added.}
\item{apply}{Whether to immediately apply the newly added theme. Setting
this to \code{TRUE} has the same impact as running \code{{
rstudioapi::addTheme(); rstudioapi::applyTheme()
}}.\cr Default: \code{FALSE}.}
\item{force}{Whether to force the operation and overwrite an existing file
with the same name.\cr Default: \code{FALSE}.}
\item{globally}{Whether to install this theme for the current user or all
users. If set to \code{TRUE} this will attempt to install the theme for all
users, which may require administrator privileges.\cr Default: \code{FALSE}.}
}
\description{
Adds a custom editor theme to RStudio and returns the name of the newly
added theme.
}
\note{
The \code{addTheme} function was introduced in RStudio 1.2.879.
}
rstudioapi/man/build-tools.Rd 0000644 0001762 0000144 00000002653 13752325464 015755 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/build-tools.R
\name{build-tools}
\alias{build-tools}
\alias{buildToolsCheck}
\alias{buildToolsInstall}
\alias{buildToolsExec}
\title{Build Tools}
\usage{
buildToolsCheck()
buildToolsInstall(action)
buildToolsExec(expr)
}
\arguments{
\item{action}{The action (as a string) being taken that will require
installation of build tools.}
\item{expr}{An \R expression (unquoted) to be executed with build tools
available and on the \code{PATH}.}
}
\description{
Check, install, and use build tools as required.
}
\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:\if{html}{\out{
}}\preformatted{compile_model <- function(...) \{
if (rstudioapi::isAvailable()) \{
if (!rstudioapi::buildToolsCheck())
rstudioapi::buildToolsInstall("Model compilation")
rstudioapi::buildToolsExec(\{
# code requiring build tools here
\})
\}
\}
}\if{html}{\out{
͊jrGzz.˰\^MeuRRI _; DYY9ARt J vGqO\Rx#i[Ьڬo܈<#A
q hU yifGNIb"h=2ĭ8<"U&T{oCפwЪFvO X1kS=:Ā>5#%E(zxO}%ʣIx "A!n1pM{ [T"'uZTЫC܊sK! h÷'~\v3Zᏻ{(i$K%9 0 q+7_ְ1G턪
Q\
Q2bYN㲹>& 5;vE(wB+Gb\"y Nk_A0C|BU gIyܸqGddpit7RZNς's
Kx($E"hfB8 g<8y
㿎rs ub}wXCluoi/U f'5DŽ<.cLֿOF)vj$+,\ Q%l uicќ L:DUcׁEiPK-;'2~qG}bc :7+CE=-gm]w:-Ι28պ.y.: ;vWk+5rƍ1`^sA,\)8G1y: .a*Mٷ Y<>Q-WC!lEPNٙ"nAKW_,,~:ԸPaD%%[k^&`8VP!EHeWqE 0kұ IENDB` rstudioapi/man/figures/logo.svg 0000644 0001762 0000144 00000113352 13716571545 016360 0 ustar ligges users
rstudioapi/man/writePreference.Rd 0000644 0001762 0000144 00000001116 13752325464 016642 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/prefs.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 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.
}
\seealso{
\code{\link{writeRStudioPreference}}, which changes RStudio IDE
preferences.
}
rstudioapi/man/projects.Rd 0000644 0001762 0000144 00000002204 13752334243 015334 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stubs.R
\name{projects}
\alias{projects}
\alias{openProject}
\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]{documentSaveAll()}}.
}
\note{
The \code{openProject} and \code{initializeProject} functions were
added in version 1.1.287 of RStudio.
}
rstudioapi/man/getThemeInfo.Rd 0000644 0001762 0000144 00000001666 13752325464 016101 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 information about the current color theme used by
RStudio.
}
\details{
A list is returned with the following elements: \describe{ \item{editor}{The
name of the current editor theme, such as \code{Textmate}.}
\item{global}{The name of the current global theme. One of \code{Modern},
\code{Classic}, or \code{Sky}.} \item{dark}{\code{TRUE} if the editor theme
is dark, \code{FALSE} otherwise.} \item{foreground}{The current editor
theme's default text foreground color, formatted as a CSS-compatible color
string, such as \code{rgb(1, 22, 39)}. Supported since RStudio 1.2.1214.}
\item{background}{The current editor theme's default text background color,
formatted as a CSS-compatible color string. Supported since RStudio
1.2.1214.} }
}
rstudioapi/man/launcherSubmitR.Rd 0000644 0001762 0000144 00000002177 13752325464 016630 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/launcher-functions.R
\name{launcherSubmitR}
\alias{launcherSubmitR}
\title{Execute an R Script as a Launcher Job}
\usage{
launcherSubmitR(script, cluster = "Local", container = NULL)
}
\arguments{
\item{script}{Fully qualified path of R script. Must be a path that is
available in the job container (if using containerized job cluster such as
Kubernetes).}
\item{cluster}{The name of the cluster this job should be submitted to.}
\item{container}{The container to be used for launched jobs.}
}
\description{
Convenience function for running an R script as a launcher job using
whichever R is found on the path in the launcher cluster.
}
\details{
See \code{\link[=launcherSubmitJob]{launcherSubmitJob()}} for running jobs
with full control over command, environment, and so forth.
}
\seealso{
Other job submission: \code{\link{launcherConfig}()},
\code{\link{launcherContainer}()}, \code{\link{launcherHostMount}()},
\code{\link{launcherNfsMount}()},
\code{\link{launcherPlacementConstraint}()},
\code{\link{launcherResourceLimit}()}, \code{\link{launcherSubmitJob}()}
}
rstudioapi/man/highlightUi.Rd 0000644 0001762 0000144 00000004350 13752325464 015761 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/highlight-ui.R
\name{highlightUi}
\alias{highlightUi}
\title{Highlight UI Elements within the RStudio IDE}
\usage{
highlightUi(queries)
}
\arguments{
\item{queries}{A list of "query" objects. Each query should be a list with
entries \code{"query"} and \code{"parent"}. See \strong{Queries} for more
details.}
}
\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.
}
\details{
The tool at:\preformatted{Help -> Diagnostics -> Show DOM Elements }
can be useful for identifying the classes and IDs assigned to the different
elements within RStudio.
}
\note{
The \code{highlightUi} function was introduced in RStudio 1.3.658.
}
\section{Queries}{
Elements are selected using the same queries as through the web
\code{querySelectorAll()} API. See
\url{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:\preformatted{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 \verb{From Text
(readr)} command, you might use:\preformatted{rstudioapi::highlightUi( list(
list(query = "#rstudio_mb_import_dataset", parent = 0L), list(query =
"#rstudio_label_from_text_readr_command", parent = 1L) ) ) }
}
\examples{
\dontrun{rstudioapi::highlightUi("#rstudio_workbench_panel_git")}
# clear current highlights
\dontrun{rstudioapi::highlightUi("")}
# highlight within an RMD
\dontrun{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.
\dontrun{rstudioapi::highlightUi(
list(
list(
query="#rstudio_workbench_panel_git",
callback="rstudioapi::highlightUi('')"
)
)
)}
}
rstudioapi/man/askForSecret.Rd 0000644 0001762 0000144 00000001251 13752575533 016110 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dialogs.R
\name{askForSecret}
\alias{askForSecret}
\title{Prompt user for secret}
\usage{
askForSecret(
name,
message = paste(name, ":", sep = ""),
title = paste(name, "Secret")
)
}
\arguments{
\item{name}{The name of the secret.}
\item{message}{A character vector with the contents to display in the main
dialog area.}
\item{title}{The title to display in the dialog box.}
}
\description{
Request a secret from the user. If the \code{keyring} package is installed, it
will be used to cache requested secrets.
}
\note{
The \code{askForSecret} function was added in version 1.1.419 of
RStudio.
}
rstudioapi/man/terminalSend.Rd 0000644 0001762 0000144 00000001303 13752325464 016134 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/applyTheme.Rd 0000644 0001762 0000144 00000000614 13752325464 015623 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/themes.R
\name{applyTheme}
\alias{applyTheme}
\title{Apply an Editor Theme to RStudio}
\usage{
applyTheme(name)
}
\arguments{
\item{name}{The unique name of the theme to apply.}
}
\description{
Applies the specified editor theme to RStudio.
}
\note{
The \code{applyTheme} function was introduced in RStudio 1.2.879.
}
rstudioapi/man/file-dialogs.Rd 0000644 0001762 0000144 00000002700 13752334243 016043 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{selectFile}
\alias{selectDirectory}
\title{Select a file / folder}
\usage{
selectFile(
caption = "Select File",
label = "Select",
path = getActiveProject(),
filter = "All Files (*)",
existing = TRUE
)
selectDirectory(
caption = "Select Directory",
label = "Select",
path = getActiveProject()
)
}
\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. 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 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/terminalActivate.Rd 0000644 0001762 0000144 00000002077 13752325464 017014 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 13752325464 015675 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/hasColorConsole.Rd 0000644 0001762 0000144 00000001112 13752334243 016575 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{
\code{TRUE} if ANSI color escapes are supported; \code{FALSE} otherwise.
}
\description{
Check if the RStudio 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/launcherResourceLimit.Rd 0000644 0001762 0000144 00000002023 13752325464 020017 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/launcher-functions.R
\name{launcherResourceLimit}
\alias{launcherResourceLimit}
\title{Define a Launcher Resource Limit}
\usage{
launcherResourceLimit(type, value)
}
\arguments{
\item{type}{The resource limit type. Must be one of cpuCount, cpuFrequency,
cpuSet, cpuTime, memory, memorySwap. Different launcher plugins may support
different subsets of these resource limit types; please consult the plugin
documentation to learn which limits are supported.}
\item{value}{The formatted value of the requested limit.}
}
\description{
Define a launcher resource limit, suitable for use with the
\code{resourceLimits} argument to
\code{\link[=launcherSubmitJob]{launcherSubmitJob()}}.
}
\seealso{
Other job submission: \code{\link{launcherConfig}()},
\code{\link{launcherContainer}()}, \code{\link{launcherHostMount}()},
\code{\link{launcherNfsMount}()},
\code{\link{launcherPlacementConstraint}()},
\code{\link{launcherSubmitJob}()}, \code{\link{launcherSubmitR}()}
}
rstudioapi/man/launcherNfsMount.Rd 0000644 0001762 0000144 00000002020 13752325464 016777 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/launcher-functions.R
\name{launcherNfsMount}
\alias{launcherNfsMount}
\title{Define a Launcher NFS Mount}
\usage{
launcherNfsMount(host, path, mountPath, readOnly = TRUE)
}
\arguments{
\item{host}{The host name, or IP address, of the NFS server.}
\item{path}{The NFS path to be mounted.}
\item{mountPath}{The destination path for the mount in the container.}
\item{readOnly}{Boolean; should the path be mounted read-only?}
}
\description{
Define a launcher NFS mount, suitable for use with the \code{mounts}
argument to \code{\link[=launcherSubmitJob]{launcherSubmitJob()}}. This can
be used to mount a path from a networked filesystem into a newly generated
container.
}
\seealso{
Other job submission: \code{\link{launcherConfig}()},
\code{\link{launcherContainer}()}, \code{\link{launcherHostMount}()},
\code{\link{launcherPlacementConstraint}()},
\code{\link{launcherResourceLimit}()}, \code{\link{launcherSubmitJob}()},
\code{\link{launcherSubmitR}()}
}
rstudioapi/man/updateDialog.Rd 0000644 0001762 0000144 00000001164 13752325464 016116 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/terminalCreate.Rd 0000644 0001762 0000144 00000002511 13752325464 016450 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, shellType = NULL)
}
\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.}
\item{shellType}{Shell type for the terminal: NULL or "default" to use the
shell selected in Global Options. For Microsoft Windows, alternatives are
"win-cmd" for 64-bit Command Prompt, "win-ps" for 64-bit PowerShell,
"win-git-bash" for Git Bash, or "win-wsl-bash" for Bash on Windows Subsystem
for Linux. On Linux, Mac, and RStudio Server "custom" will use the custom
terminal defined in Global Options. If the requested shell type is not
available, the default shell will be used, instead.}
}
\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 and the ability to specify shellType was added in version 1.2.696.
}
\examples{
\dontrun{
termId <- rstudioapi::terminalCreate('My Terminal')
}
}
rstudioapi/man/terminalKill.Rd 0000644 0001762 0000144 00000001007 13752325464 016137 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/terminalClear.Rd 0000644 0001762 0000144 00000001266 13752325464 016301 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/systemUsername.Rd 0000644 0001762 0000144 00000000372 13752325464 016540 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/user.R
\name{systemUsername}
\alias{systemUsername}
\title{Get System Username}
\usage{
systemUsername()
}
\description{
Returns the system username of the current user.
}
rstudioapi/man/persistent-values.Rd 0000644 0001762 0000144 00000001344 13752334243 017204 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}{The key name.}
\item{value}{The 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/isAvailable.Rd 0000644 0001762 0000144 00000001614 13752576012 015725 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, child_ok = FALSE)
verifyAvailable(version_needed = NULL)
}
\arguments{
\item{version_needed}{An optional version specification. If supplied, ensures
that RStudio is at least that version.}
\item{child_ok}{Boolean; check if the current R process is a child process of
the main RStudio session? This can be useful for e.g. RStudio Jobs, where
you'd like to communicate back with the main R session from a child process
through \code{rstudioapi}.}
}
\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/terminalBusy.Rd 0000644 0001762 0000144 00000002010 13752325464 016161 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?
}
\details{
This feature is only supported on RStudio Desktop for Mac and Linux, and
RStudio Server. It always returns \code{FALSE} on RStudio Desktop for
Microsoft Windows.
}
\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/jobSetStatus.Rd 0000644 0001762 0000144 00000001077 13752325464 016151 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/jobs.R
\name{jobSetStatus}
\alias{jobSetStatus}
\title{Set Job Status}
\usage{
jobSetStatus(job, status)
}
\arguments{
\item{job}{The ID of the job to update.}
\item{status}{Text describing job's new status.}
}
\description{
Update a job's informational status text.
}
\seealso{
Other jobs: \code{\link{jobAddOutput}()},
\code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
\code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
\code{\link{jobSetProgress}()}, \code{\link{jobSetState}()}
}
rstudioapi/man/launcherPlacementConstraint.Rd 0000644 0001762 0000144 00000001646 13752325464 021220 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/launcher-functions.R
\name{launcherPlacementConstraint}
\alias{launcherPlacementConstraint}
\title{Define a Launcher Placement Constraint}
\usage{
launcherPlacementConstraint(name, value = NULL)
}
\arguments{
\item{name}{The name of this placement constraint.}
\item{value}{The value of the constraint. A job will only be placed on a
requested node if the requested placement constraint is present.}
}
\description{
Define a launcher placement constraint, suitable for use with the
\code{placementConstraints} argument to
\code{\link[=launcherSubmitJob]{launcherSubmitJob()}}.
}
\seealso{
Other job submission: \code{\link{launcherConfig}()},
\code{\link{launcherContainer}()}, \code{\link{launcherHostMount}()},
\code{\link{launcherNfsMount}()}, \code{\link{launcherResourceLimit}()},
\code{\link{launcherSubmitJob}()}, \code{\link{launcherSubmitR}()}
}
rstudioapi/man/jobAddOutput.Rd 0000644 0001762 0000144 00000001204 13752325464 016113 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/jobs.R
\name{jobAddOutput}
\alias{jobAddOutput}
\title{Add Job Output}
\usage{
jobAddOutput(job, output, error = FALSE)
}
\arguments{
\item{job}{The ID of the job that has emitted text.}
\item{output}{The text output emitted by the job.}
\item{error}{Whether the output represents an error.}
}
\description{
Adds text output to a job.
}
\seealso{
Other jobs: \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
\code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
\code{\link{jobSetProgress}()}, \code{\link{jobSetState}()},
\code{\link{jobSetStatus}()}
}
rstudioapi/man/executeCommand.Rd 0000644 0001762 0000144 00000002043 13752325464 016452 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/commands.R
\name{executeCommand}
\alias{executeCommand}
\title{Execute Command}
\usage{
executeCommand(commandId, quiet = FALSE)
}
\arguments{
\item{commandId}{The ID of the command to execute.}
\item{quiet}{Whether to show an error if the command does not exist.}
}
\description{
Executes an arbitrary RStudio command.
}
\details{
Most menu commands and many buttons in RStudio can be invoked from the API
using this method.
The \code{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 \code{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 appendix for a list
of supported command IDs.
}
\note{
The \code{executeCommand} function was introduced in RStudio 1.2.1261.
}
rstudioapi/man/terminalContext.Rd 0000644 0001762 0000144 00000002633 13752325464 016676 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/launcherControlJob.Rd 0000644 0001762 0000144 00000001240 13752325464 017304 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/launcher-functions.R
\name{launcherControlJob}
\alias{launcherControlJob}
\title{Interact with (Control) a Job}
\usage{
launcherControlJob(
jobId,
operation = c("suspend", "resume", "stop", "kill", "cancel")
)
}
\arguments{
\item{jobId}{The job id.}
\item{operation}{The operation to execute. The operation should be one of
\code{c("suspend", "resume", "stop", "kill", "cancel")}. Note that different
launcher plugins support different subsets of these operations -- consult
your launcher plugin documentation to see which operations are supported.}
}
\description{
Interact with a job.
}
rstudioapi/man/dictionaries.Rd 0000644 0001762 0000144 00000001555 13752325464 016175 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dictionaries.R
\name{dictionaries}
\alias{dictionaries}
\alias{dictionariesPath}
\alias{userDictionariesPath}
\title{Interact with RStudio's Dictionaries}
\usage{
dictionariesPath()
userDictionariesPath()
}
\description{
Interact with the \href{https://hunspell.github.io/}{hunspell} dictionaries
used by RStudio for spell checking.
}
\details{
\code{dictionariesPath()} gives a path to the dictionaries installed and
distributed with RStudio.
\code{userDictionariesPath()} gives the path where users can provide their
own custom \code{hunspell} dictionaries. See:
\url{https://support.rstudio.com/hc/en-us/articles/200551916-Spelling-Dictionaries}
for more information.
}
\note{
The \code{dictionariesPath()} and \code{userDictionariesPath()} functions were
introduced with RStudio 1.2.1202.
}
rstudioapi/man/terminalRunning.Rd 0000644 0001762 0000144 00000002167 13752325464 016674 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/launcher.Rd 0000644 0001762 0000144 00000002452 13752325464 015316 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/launcher-functions.R
\name{launcher}
\alias{launcher}
\alias{launcherGetInfo}
\alias{launcherAvailable}
\alias{launcherGetJobs}
\title{Retrieve Launcher Information}
\usage{
launcherGetInfo()
launcherAvailable()
launcherGetJobs(
statuses = NULL,
fields = NULL,
tags = NULL,
includeSessions = FALSE
)
}
\arguments{
\item{statuses}{Return only jobs whose status matches one of \code{statuses}.
Valid statuses are: Pending, Running, Suspended, Failed, Finished, Killed,
Canceled. When \code{NULL}, all jobs are returned.}
\item{fields}{Return a subset of fields associated with each job object.
When \code{NULL}, all fields associated with a particular job are returned.}
\item{tags}{An optional set of tags. Only jobs that have been assigned one
of these requested tags will be returned.}
\item{includeSessions}{Boolean; include jobs which are also operating
as RStudio R sessions?}
}
\description{
Retrieve information about the launcher, as well as the different clusters
that the launcher has been configured to use.
Check if the RStudio launcher is available and configured to support
'ad-hoc' jobs; that is, jobs normally launched by the user through
the RStudio IDE's user interface.
Retrieve information on launcher jobs.
}
rstudioapi/man/restartSession.Rd 0000644 0001762 0000144 00000000634 13752334243 016540 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}{A command (as a string) to be run after restarting.}
}
\description{
Restart the RStudio session.
}
\note{
The \code{restartSession} function was added in version 1.1.281 of
RStudio.
}
rstudioapi/man/document_position.Rd 0000644 0001762 0000144 00000001207 13752325464 017254 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{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/launcherGetJob.Rd 0000644 0001762 0000144 00000000513 13752325464 016405 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/launcher-functions.R
\name{launcherGetJob}
\alias{launcherGetJob}
\title{Retrieve Job Information}
\usage{
launcherGetJob(jobId)
}
\arguments{
\item{jobId}{The id of a launcher job.}
}
\description{
Retrieve information on a job with id \code{jobId}.
}
rstudioapi/man/translateLocalUrl.Rd 0000644 0001762 0000144 00000001760 13752325464 017151 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/urls.R
\name{translateLocalUrl}
\alias{translateLocalUrl}
\title{Translate Local URL}
\usage{
translateLocalUrl(url, absolute = FALSE)
}
\arguments{
\item{url}{The fully qualified URL to translate; for example,
\code{http://localhost:1234/service/page.html}.}
\item{absolute}{Whether to return a relative path URL (the default) or an
absolute URL.}
}
\value{
The translated URL.
}
\description{
Translates a local URL into an externally accessible URL on RStudio Server.
}
\details{
On RStudio Server, URLs which refer to the local host network address (such
as \code{http://localhost:1234/} and \code{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.
}
rstudioapi/man/terminalVisible.Rd 0000644 0001762 0000144 00000000572 13752325464 016647 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/DESCRIPTION 0000644 0001762 0000144 00000002056 13753327012 014151 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.13
Authors@R: c(
person("Kevin", "Ushey", role = c("aut", "cre"), email = "kevin@rstudio.com"),
person("JJ", "Allaire", role = c("aut"), email = "jj@rstudio.com"),
person("Hadley", "Wickham", role = c("aut"), email = "hadley@rstudio.com"),
person("Gary", "Ritchie", role = c("aut"), email = "gary@rstudio.com"),
person(family = "RStudio", role = "cph")
)
Maintainer: Kevin Ushey
License: MIT + file LICENSE
URL: https://github.com/rstudio/rstudioapi
BugReports: https://github.com/rstudio/rstudioapi/issues
RoxygenNote: 7.1.1
Suggests: testthat, knitr, rmarkdown, clipr
VignetteBuilder: knitr
Encoding: UTF-8
NeedsCompilation: no
Packaged: 2020-11-11 23:34:30 UTC; kevinushey
Author: Kevin Ushey [aut, cre],
JJ Allaire [aut],
Hadley Wickham [aut],
Gary Ritchie [aut],
RStudio [cph]
Repository: CRAN
Date/Publication: 2020-11-12 21:50:02 UTC
rstudioapi/build/ 0000755 0001762 0000144 00000000000 13753072406 013543 5 ustar ligges users rstudioapi/build/vignette.rds 0000644 0001762 0000144 00000000626 13753072406 016106 0 ustar ligges users RN1-, (^|ņxmjvMەxntWkM=BMBjp Fڰ:wa?r'Z(K0f11\
0(IS%Ydj5a* vuFq") X]V(yBmJrIRn` Al-^,s
>, 2ˢ+Zm}r3$V g{o7IbWyʄĠ fS!yПRWvK;Y34{` gL8tX1
\K aVBÊ;$a&l}Vܔ` N,e: ?םTp*bX7(v أĐZ{}|=6 rstudioapi/vignettes/ 0000755 0001762 0000144 00000000000 13753072406 014454 5 ustar ligges users rstudioapi/vignettes/terminal.Rmd 0000644 0001762 0000144 00000011165 13535525640 016740 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/r-session.Rmd 0000644 0001762 0000144 00000002645 13535525640 017052 0 ustar ligges users ---
title: "Interacting with the R Session"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Interact with the R Session}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```
## Session Interaction
The `rstudioapi` package allows you to interact with the running R session in a couple useful ways: you can send code to the R console, or restart the R session.
```{r}
# restart R, then run some code after
rstudioapi::restartSession(command = "print('Welcome back!')")
# send some code to the console and execute it immediately
rstudioapi::sendToConsole("1 + 1", execute = TRUE)
```
## Running at Startup
Typically, code that you want to run at the start of an R session is placed into an `.Rprofile` file (see [Initialization at the Start of a Session](https://stat.ethz.ch/R-manual/R-devel/library/base/html/Startup.html) for details). However, RStudio's API hooks are not available until RStudio has fully started up, so most `rstudioapi` methods will not work inside `.Rprofile`.
If you want to invoke `rstudioapi` methods on session startup, use the `rstudio.sessionInit` hook. For example, to print the RStudio version to the R console when the session begins:
```{r}
setHook("rstudio.sessionInit", function(newSession) {
if (newSession)
message("Welcome to RStudio ", rstudioapi::getVersion())
}, action = "append")
```
rstudioapi/vignettes/dialogs.Rmd 0000644 0001762 0000144 00000003166 13535525640 016551 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 13535525640 017636 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/visual-mode.Rmd 0000644 0001762 0000144 00000004746 13752324312 017353 0 ustar ligges users ---
title: "Interfacing with RStudio in Visual Mode"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Interfacing with RStudio in Visual Mode}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
```{r setup}
library(rstudioapi)
```
RStudio v1.4 includes a new [visual editing mode](https://rstudio.github.io/visual-markdown-editing/#/), which provides a [WYSIWYM](https://en.wikipedia.org/wiki/WYSIWYM)-style editing interface for R Markdown documents. This vignette describes how `rstudioapi` can be used to interface with the RStudio visual mode editor.
Most of the pre-existing `rstudioapi` functions used for interacting with a document (e.g. `rstudioapi::getSourceEditorContext()`) consume and / or produce objects which describe the position of the current selection in terms of row + column offsets into the document. Unfortunately, this abstraction does not neatly map into visual editing mode, as there is no notion of a "global" cursor position -- rather, a cursor might be placed into a particular cell, and could have an offset somewhere into that cell.
If you are an [RStudio Addin](https://rstudio.github.io/rstudioaddins/) author, then you may want to ensure your addins are visual-mode-aware, so that they can function regardless of whether the user has enabled visual mode. To that end, we've introduced a small set of functions, which are more narrow in scope but can function in both source and visual mode:
- `rstudioapi::documentId()`: Retrieve the ID associated with the document currently open and being edited in the RStudio IDE.
- `rstudioapi::documentPath()`: Retrieve the path on disk for a file currently open in the RStudio IDE.
- `rstudioapi::selectionGet()`: Get the contents of the user's selection.
- `rstudioapi::selectionSet()`: Set the contents of the user's selection.
In addition, the `rstudioapi::insertText()` function will function in both source and visual mode, as long as only the `text` argument is supplied.
Using this, you can build addins that modify the user's selected text. For example, a function that uses `rstudioapi` to reformat the user's current selection might look like this:
```{r eval=FALSE}
reformat <- function() {
id <- rstudioapi::documentId(allowConsole = TRUE)
selection <- rstudioapi::selectionGet(id = id)
formatted <- styler::style_text(text = selection$value)
rstudioapi::selectionSet(value = formatted, id = id)
}
```
rstudioapi/vignettes/projects.Rmd 0000644 0001762 0000144 00000001202 13535525640 016745 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/document-manipulation.Rmd 0000644 0001762 0000144 00000004074 13535525640 021442 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/R/ 0000755 0001762 0000144 00000000000 13752334444 012647 5 ustar ligges users rstudioapi/R/dialogs.R 0000644 0001762 0000144 00000006076 13752575342 014431 0 ustar ligges users #' Show Dialog Box
#'
#' Shows a dialog box with a given title and contents.
#'
#' \preformatted{ showDialog("A dialog", "Showing bold text in the
#' message.") }
#'
#' @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 An optional url to display under the \code{message}.
#' @note The \code{showDialog} function was added in version 1.1.67 of RStudio.
#' @export showDialog
showDialog <- function(title, message, url = "") {
callFun("showDialog", title, message, url)
}
#' Updates a Dialog Box
#'
#' Updates specific properties from the current dialog box.
#'
#' 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") }
#'
#' @param ... Named parameters and values to update a dialog box.
#' @note The \code{updateDialog} function was added in version 1.1.67 of
#' RStudio.
#' @export updateDialog
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
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
showQuestion <- function(title, message, ok = NULL, cancel = NULL) {
callFun("showQuestion", title, message, ok, cancel)
}
#' Prompt user for secret
#'
#' Request a secret from the user. If the `keyring` package is installed, it
#' will be used to cache requested secrets.
#'
#'
#' @param name The name of the secret.
#'
#' @param message A character vector with the contents to display in the main
#' dialog area.
#'
#' @param title The title to display in the dialog box.
#'
#' @note The \code{askForSecret} function was added in version 1.1.419 of
#' RStudio.
#'
#' @export
askForSecret <- function(
name,
message = paste(name, ":", sep = ""),
title = paste(name, "Secret")) {
if (hasFun("askForSecret")) {
callFun("askForSecret", name, title, message)
} else {
askForPassword(message)
}
}
rstudioapi/R/stubs.R 0000644 0001762 0000144 00000040043 13753072117 014130 0 ustar ligges users #' RStudio version information
#'
#' Query information about the currently running instance of RStudio.
#'
#' @return
#'
#' An \R list with the following elements:
#'
#' \tabular{ll}{
#' \code{version} \tab The version of RStudio. \cr
#' \code{mode} \tab `"desktop"` for RStudio Desktop, or `"server"` for RStudio Server. \cr
#' \code{citation} \tab Information on how RStudio can be cited in academic publications. \cr
#' }
#'
#' @note The \code{versionInfo} function was added in version 0.97.124 of
#' RStudio.
#'
#' @examples
#'
#' \dontrun{
#' 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
#'
#' }
#'
#' @export
versionInfo <- function() {
callFun("versionInfo")
}
#' Preview an Rd topic in the Help pane
#'
#' Preview an Rd topic in the Help pane.
#'
#' @param rdFile The path to an `.Rd` file.
#'
#' @note The \code{previewRd} function was added in version 0.98.191 of
#' RStudio.
#'
#' @examples
#'
#' \dontrun{
#' rstudioapi::previewRd("~/MyPackage/man/foo.Rd")
#' }
#'
#' @export previewRd
previewRd <- function(rdFile) {
callFun("previewRd", rdFile)
}
#' View local web content within RStudio
#'
#' 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.
#'
#' 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.
#'
#' @param 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
#' [tempfile()]).
#'
#' @param 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.
#'
#' @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)
#'
#' # 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)
#'
#' }
#'
#'
#' @export viewer
viewer <- function(url, height = NULL) {
callFun("viewer", url, height = height)
}
#' Display source markers
#'
#' Display user navigable source markers in a pane within RStudio.
#'
#' 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 The marker type ("error", "warning", "info", "style", or "usage"). \cr
#' \code{file} \tab The path to the associated source file. \cr
#' \code{line} \tab The line number for the associated marker. \cr
#' \code{column} \tab The column number for the associated marker. \cr
#' \code{message} \tab A message associated with the marker at this location. \cr
#' }
#'
#' Note that if the \code{message} field is of class "html" (i.e.
#' \code{inherits(message, "html") == TRUE}) then its contents will be treated
#' as HTML.
#'
#' @param name The name of marker set. If there is a market set with this name
#' already being shown, those markers will be replaced.
#'
#' @param markers An \R list, or data.frame, of source markers. See **details**
#' for more details on the expected format.
#'
#' @param 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.
#'
#' @param autoSelect Auto-select a marker after displaying the marker set?
#'
#' @note The \code{sourceMarkers} function was added in version 0.99.225 of
#' RStudio.
#'
#' @export
sourceMarkers <- function(name, markers, basePath = NULL,
autoSelect = c("none", "first", "error")) {
callFun("sourceMarkers", name, markers, basePath, autoSelect)
}
#' Navigate to file
#'
#' Open a file in RStudio, optionally at a specified location.
#'
#' 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{file} argument is empty (the default), then the file is the file
#' currently in view if one exists. 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. Alternatively,
#' \code{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
#' \code{\link[utils]{View}} on the function, which has the advantage of
#' falling back on deparsing if the file is not available.
#'
#' @param file The file to be opened.
#'
#' @param line The line number where the cursor should be placed. When `-1L`
#' (the default), the cursor will not be moved.
#'
#' @param column The column number where the cursour should be placed. When
#' `-1L` (the default), the cursor will not be moved.
#'
#' @param moveCursor Boolean; should the cursor be moved to the requested
#' (`line`, `column`) position? Set this to `FALSE` to preserve the existing
#' cursor position in the document.
#'
#' @note The \code{navigateToFile} function was added in version 0.99.719 of
#' RStudio.
#'
#' @export
navigateToFile <- function(file = character(0),
line = -1L,
column = -1L,
moveCursor = TRUE)
{
callFun("navigateToFile",
file,
as.integer(line),
as.integer(column),
as.logical(moveCursor))
}
#' Ask the user for a password interactively
#'
#' Ask the user for a password interactively.
#'
#' 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.
#'
#' @param prompt The prompt to be shown to the user.
#'
#' @note The \code{askForPassword} function was added in version 0.99.853 of
#' RStudio.
#'
#' @examples
#'
#' \dontrun{
#' rstudioapi::askForPassword("Please enter your password")
#' }
#'
#' @export askForPassword
askForPassword <- function(prompt = "Please enter your password") {
callFun("askForPassword", prompt)
}
#' Retrieve path to active RStudio project
#'
#' Get the path to the active RStudio project (if any). If the path contains
#' non-ASCII characters, it will be UTF-8 encoded.
#'
#' @return The path to the current project, or \code{NULL} if no project is
#' currently open.
#'
#' @note The \code{getActiveProject} function was added in version 0.99.854 of
#' RStudio.
#'
#' @export
getActiveProject <- function() {
path <- callFun("getActiveProject")
# path is NULL iff there is no open project
if (is.null(path))
return(path)
# ... otherwise path is UTF-8 encoded
Encoding(path) <- "UTF-8"
path
}
#' Save active RStudio plot image
#'
#' Save the plot currently displayed in the Plots pane as an image.
#'
#' @param file The target file path.
#'
#' @param format The Image format.
#' Must be one of ("png", "jpeg", "bmp", "tiff", "emf", "svg", or "eps").
#'
#' @param width The image width, in pixels.
#'
#' @param height The image height, in pixels.
#'
#' @note The \code{savePlotAsImage} function was introduced in RStudio 1.1.57.
#'
#' @export savePlotAsImage
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 The \R code to be executed, as a character vector.
#'
#' @param execute Boolean; execute the code immediately or just enter the text
#' into the console?
#'
#' @param echo Boolean; echo the code in the console as it is executed?
#'
#' @param focus Boolean; focus the console after sending code?
#'
#' @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, echo = TRUE, focus = TRUE) {
callFun("sendToConsole",
code = code,
echo = echo,
execute = execute,
focus = focus)
}
#' 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 The key name.
#' @param value The 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.
#'
#' Check if the RStudio console supports ANSI color escapes.
#'
#'
#' @return `TRUE` if ANSI color escapes are supported; `FALSE` otherwise.
#'
#' @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.")
#' }
#'
#' }
#'
#'
#' @export hasColorConsole
hasColorConsole <- function() {
callFun("getConsoleHasColor")
}
#' Restart the R Session
#'
#' Restart the RStudio session.
#'
#'
#' @param command A command (as a string) to be run after restarting.
#'
#' @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 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. 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 = getActiveProject(),
filter = "All Files (*)",
existing = TRUE)
{
out <- callFun("selectFile", caption, label, path, filter, existing)
if (is.character(out))
Encoding(out) <- "UTF-8"
out
}
#' @name file-dialogs
#' @export
selectDirectory <- function(caption = "Select Directory",
label = "Select",
path = getActiveProject())
{
callFun("selectDirectory", 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 [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/user.R 0000644 0001762 0000144 00000000542 13752325404 013745 0 ustar ligges users #' Get User Identity
#'
#' Returns the identity (displayed name) of the current user.
#'
#'
#' @export userIdentity
userIdentity <- function()
{
callFun("userIdentity")
}
#' Get System Username
#'
#' Returns the system username of the current user.
#'
#'
#' @export systemUsername
systemUsername <- function()
{
callFun("systemUsername")
}
rstudioapi/R/utils.R 0000644 0001762 0000144 00000000475 13752342251 014133 0 ustar ligges users
`%||%` <- function(x, y) {
if (is.null(x)) y else x
}
renderTemplate <- function(template, data) {
rendered <- template
for (i in seq_along(data)) {
key <- names(data)[[i]]
val <- data[[i]]
fkey <- sprintf("${%s}", key)
rendered <- gsub(fkey, val, rendered, fixed = TRUE)
}
rendered
}
rstudioapi/R/urls.R 0000644 0001762 0000144 00000001714 13752325404 013756 0 ustar ligges users #' Translate Local URL
#'
#' Translates a local URL into an externally accessible URL on RStudio Server.
#'
#' On RStudio Server, URLs which refer to the local host network address (such
#' as \code{http://localhost:1234/} and \code{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.
#'
#' @param url The fully qualified URL to translate; for example,
#' \code{http://localhost:1234/service/page.html}.
#' @param absolute Whether to return a relative path URL (the default) or an
#' absolute URL.
#' @return The translated URL.
#' @export translateLocalUrl
translateLocalUrl <- function(url, absolute = FALSE)
{
callFun("translateLocalUrl", url = url, absolute = absolute)
}
rstudioapi/R/preview.R 0000644 0001762 0000144 00000001166 13752325403 014452 0 ustar ligges users #' Preview SQL statement
#'
#' Makes use of 'DBI' and \code{dbGetQuery()} to preview a SQL statement for a
#' given 'DBI' connection.
#'
#'
#' @param conn The 'DBI' connection to be used to execute this statement.
#' @param statement The SQL statement to execute. Either a path to a file
#' containing a SQL statement or the SQL statement itself.
#' @param ... Additional arguments to be used in \code{dbGetQuery()}.
#' @note The \code{previewSql} function was introduced in RStudio 1.2.600
#' @export previewSql
previewSql <- function(conn, statement, ...) {
callFun("previewSql", conn = conn, statement = statement, ...)
}
rstudioapi/R/commands.R 0000644 0001762 0000144 00000002011 13752325402 014557 0 ustar ligges users #' Execute Command
#'
#' Executes an arbitrary RStudio command.
#'
#' Most menu commands and many buttons in RStudio can be invoked from the API
#' using this method.
#'
#' The \code{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 \code{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 appendix for a list
#' of supported command IDs.
#'
#' @param commandId The ID of the command to execute.
#' @param quiet Whether to show an error if the command does not exist.
#' @note The \code{executeCommand} function was introduced in RStudio 1.2.1261.
#' @export executeCommand
executeCommand <- function(commandId, quiet = FALSE) {
callFun("executeCommand", commandId = commandId, quiet = quiet)
}
rstudioapi/R/chunk.R 0000644 0001762 0000144 00000002046 13730200374 014072 0 ustar ligges users #' Register and Unregister a Chunk Callback
#'
#' Register a callback function to be executed after a chunk within an R
#' Markdown document is run.
#'
#' @section 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.
#'
#' @param id A unique identifier.
#'
#' @param callback A callback function. See **Chunk Callbacks** for more details.
#'
#' @return For `registerChunkCallback()`, a unique identifier. That identifier
#' can be passed to `unreigsterChunkCallback()` to de-register a
#' previously-registered callback.
#'
#' @name chunk-callbacks
NULL
#' @name chunk-callbacks
#' @export
registerChunkCallback <- function(callback) {
callFun("registerChunkCallback", callback)
}
#' @name chunk-callbacks
#' @export
unregisterChunkCallback <- function(id = NULL) {
callFun("unregisterChunkCallback", id)
}
rstudioapi/R/terminal.R 0000644 0001762 0000144 00000025361 13752325404 014610 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
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
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.
#' @param shellType Shell type for the terminal: NULL or "default" to use the
#' shell selected in Global Options. For Microsoft Windows, alternatives are
#' "win-cmd" for 64-bit Command Prompt, "win-ps" for 64-bit PowerShell,
#' "win-git-bash" for Git Bash, or "win-wsl-bash" for Bash on Windows Subsystem
#' for Linux. On Linux, Mac, and RStudio Server "custom" will use the custom
#' terminal defined in Global Options. If the requested shell type is not
#' available, the default shell will be used, instead.
#' @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 and the ability to specify shellType was added in version 1.2.696.
#' @examples
#'
#' \dontrun{
#' termId <- rstudioapi::terminalCreate('My Terminal')
#' }
#'
#'
#' @export terminalCreate
terminalCreate <- function(caption = NULL, show = TRUE, shellType = NULL) {
if (rstudioapi::getVersion() < "1.2.696") {
if (!is.null(shellType)) {
warning('shellType parameter ignored: not supported in this version of RStudio')
}
callFun("terminalCreate", caption, show)
} else {
callFun("terminalCreate", caption, show, shellType)
}
}
#' Is Terminal Busy
#'
#' Are terminals reporting that they are busy?
#'
#' This feature is only supported on RStudio Desktop for Mac and Linux, and
#' RStudio Server. It always returns \code{FALSE} on RStudio Desktop for
#' Microsoft Windows.
#'
#' @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
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
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
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
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
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
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
terminalKill<- function(id) {
callFun("terminalKill", id)
}
#' Get Visible Terminal
#'
#' 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
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
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
terminalExitCode <- function(id) {
callFun("terminalExitCode", id)
}
rstudioapi/R/selections.R 0000644 0001762 0000144 00000001210 13731214117 015123 0 ustar ligges users
#' Manipulate User Selections in the RStudio IDE
#'
#' These functions allow users of the `rstudioapi` package to read and write
#' the user's current selection within the RStudio IDE.
#'
#' @param id The document ID. When `NULL` (the default), the active, or
#' most-recently edited, document will be used.
#'
#' @param value The text contents to set for the selection.
#'
#' @name selections
NULL
#' @name selections
#' @export
selectionGet <- function(id = NULL) {
callFun("selectionGet", id = id)
}
#' @name selections
#' @export
selectionSet <- function(value = NULL, id = NULL) {
callFun("selectionSet", value = value, id = id)
}
rstudioapi/R/document-api.R 0000644 0001762 0000144 00000016433 13753021777 015371 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 requested operation
#' will apply to the currently open, or last focused, RStudio 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}()}.
#'
#' @param type The type of document to be created.
#'
#' @param execute Should the code be executed after the document
#' is created?
#'
#' @param allowConsole Allow the pseudo-id `#console` to be returned, if the \R
#' console is currently focused? Set this to `FALSE` if you'd always like to
#' target the currently-active or last-active editor in the Source pane.
#'
#' @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.
#'
#' The \code{documentId} and \code{documentPath} functions were added with
#' version 1.4.843 of RStudio.
#'
#' @name rstudio-documents
NULL
#' @name rstudio-documents
#' @export
insertText <- function(location = NULL,
text = NULL,
id = NULL)
{
# unfortunate gymnastics needed for older versions of RStudio
if (getVersion() < "1.4")
{
if (is.null(location) && is.null(text))
{
callFun("insertText",
id = id)
}
else if (is.null(location))
{
callFun("insertText",
text = text,
id = id)
}
else if (is.null(text))
{
callFun("insertText",
location = location,
id = id)
}
else
{
callFun("insertText",
location = location,
text = text,
id = id)
}
}
else
{
callFun("insertText",
location = location,
text = text,
id = 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
documentId <- function(allowConsole = TRUE) {
callFun("documentId", allowConsole = allowConsole)
}
#' @name rstudio-documents
#' @export
documentPath <- function(id = NULL) {
callFun("documentPath", id = 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")
}
#' @note The \code{documentNew} function was introduced in RStudio 1.2.640.
#'
#' @name rstudio-documents
#' @export
documentNew <- function(
text,
type = c("r", "rmarkdown", "sql"),
position = document_position(0, 0),
execute = FALSE)
{
type <- match.arg(type)
callFun("documentNew", type, text, position[1], position[2], execute)
}
#' @param save Whether to commit unsaved changes to the document before closing it.
#'
#' @note The \code{documentClose} function was introduced in RStudio 1.2.1255
#'
#' @details
#'
#' \code{documentClose} accepts an ID of an open document rather than a path.
#' You can retrieve the ID of the active document using the \code{documentId()}
#' function.
#'
#' Closing is always done non-interactively; that is, no prompts are given to
#' the user. If the user has made changes to the document but not saved them,
#' then the \code{save} parameter governs the behavior: when \code{TRUE},
#' unsaved changes are committed, and when \code{FALSE} they are discarded.
#'
#' @name rstudio-documents
#' @export
documentClose <- function(id = NULL, save = TRUE) {
callFun("documentClose", id, save)
}
rstudioapi/R/launcher-functions.R 0000644 0001762 0000144 00000036550 13752342246 016611 0 ustar ligges users #' Retrieve Launcher Information
#'
#' Retrieve information about the launcher, as well as the different clusters
#' that the launcher has been configured to use.
#'
#' @name launcher
#' @export
launcherGetInfo <- function() {
callLauncherFun("launcher.getInfo")
}
#' Check if Launcher is Available
#'
#' Check if the RStudio launcher is available and configured to support
#' 'ad-hoc' jobs; that is, jobs normally launched by the user through
#' the RStudio IDE's user interface.
#'
#' @name launcher
#' @export
launcherAvailable <- function() {
callLauncherFun("launcher.jobsFeatureAvailable")
}
#' Retrieve Job Information
#'
#' Retrieve information on launcher jobs.
#'
#' @param statuses Return only jobs whose status matches one of `statuses`.
#' Valid statuses are: Pending, Running, Suspended, Failed, Finished, Killed,
#' Canceled. When `NULL`, all jobs are returned.
#'
#' @param fields Return a subset of fields associated with each job object.
#' When `NULL`, all fields associated with a particular job are returned.
#'
#' @param includeSessions Boolean; include jobs which are also operating
#' as RStudio R sessions?
#'
#' @param tags An optional set of tags. Only jobs that have been assigned one
#' of these requested tags will be returned.
#'
#' @name launcher
#' @export
launcherGetJobs <- function(statuses = NULL,
fields = NULL,
tags = NULL,
includeSessions = FALSE)
{
callLauncherFun("launcher.getJobs",
statuses = statuses,
fields = fields,
tags = tags,
includeSessions = includeSessions)
}
#' Retrieve Job Information
#'
#' Retrieve information on a job with id \code{jobId}.
#'
#'
#' @param jobId The id of a launcher job.
#' @export launcherGetJob
launcherGetJob <- function(jobId) {
callLauncherFun("launcher.getJob",
jobId = jobId)
}
#' Define a Launcher Configuration
#'
#' Define a launcher configuration, suitable for use with the \code{config}
#' argument to \code{\link[=launcherSubmitJob]{launcherSubmitJob()}}.
#'
#'
#' @param name The name of the launcher configuration.
#' @param value The configuration value. Must either be an integer, float, or
#' string.
#' @seealso Other job submission: \code{\link{launcherContainer}()},
#' \code{\link{launcherHostMount}()}, \code{\link{launcherNfsMount}()},
#' \code{\link{launcherPlacementConstraint}()},
#' \code{\link{launcherResourceLimit}()}, \code{\link{launcherSubmitJob}()},
#' \code{\link{launcherSubmitR}()}
#' @export launcherConfig
launcherConfig <- function(name, value = NULL)
{
valueType <- if (is.integer(value))
"int"
else if (is.double(value))
"float"
else if (is.character(value))
"string"
value <- format(value)
callLauncherFun("launcher.newConfig",
name = name,
value = value,
valueType = valueType)
}
#' Define a Launcher Container
#'
#' Define a launcher container, suitable for use with the \code{container}
#' argument to \code{\link[=launcherSubmitJob]{launcherSubmitJob()}}.
#'
#'
#' @param image The container image to use.
#' @param runAsUserId The user id to run as within the container. Defaults to
#' the container-specified user.
#' @param runAsGroupId The group id to run as within the container. Defaults to
#' the container-specified group.
#' @seealso Other job submission: \code{\link{launcherConfig}()},
#' \code{\link{launcherHostMount}()}, \code{\link{launcherNfsMount}()},
#' \code{\link{launcherPlacementConstraint}()},
#' \code{\link{launcherResourceLimit}()}, \code{\link{launcherSubmitJob}()},
#' \code{\link{launcherSubmitR}()}
#' @export launcherContainer
launcherContainer <- function(image,
runAsUserId = NULL,
runAsGroupId = NULL)
{
if (is.numeric(runAsUserId))
runAsUserId <- as.integer(runAsUserId)
if (is.null(runAsGroupId))
runAsGroupId <- as.integer(runAsGroupId)
callLauncherFun("launcher.newContainer",
image = image,
runAsUserId = runAsUserId,
runAsGroupId = runAsGroupId)
}
#' Define a Launcher Placement Constraint
#'
#' Define a launcher placement constraint, suitable for use with the
#' \code{placementConstraints} argument to
#' \code{\link[=launcherSubmitJob]{launcherSubmitJob()}}.
#'
#'
#' @param name The name of this placement constraint.
#' @param value The value of the constraint. A job will only be placed on a
#' requested node if the requested placement constraint is present.
#' @seealso Other job submission: \code{\link{launcherConfig}()},
#' \code{\link{launcherContainer}()}, \code{\link{launcherHostMount}()},
#' \code{\link{launcherNfsMount}()}, \code{\link{launcherResourceLimit}()},
#' \code{\link{launcherSubmitJob}()}, \code{\link{launcherSubmitR}()}
#' @export launcherPlacementConstraint
launcherPlacementConstraint <- function(name,
value = NULL)
{
callLauncherFun("launcher.newPlacementConstraint",
name = name,
value = value)
}
#' Define a Launcher Resource Limit
#'
#' Define a launcher resource limit, suitable for use with the
#' \code{resourceLimits} argument to
#' \code{\link[=launcherSubmitJob]{launcherSubmitJob()}}.
#'
#'
#' @param type The resource limit type. Must be one of cpuCount, cpuFrequency,
#' cpuSet, cpuTime, memory, memorySwap. Different launcher plugins may support
#' different subsets of these resource limit types; please consult the plugin
#' documentation to learn which limits are supported.
#' @param value The formatted value of the requested limit.
#' @seealso Other job submission: \code{\link{launcherConfig}()},
#' \code{\link{launcherContainer}()}, \code{\link{launcherHostMount}()},
#' \code{\link{launcherNfsMount}()},
#' \code{\link{launcherPlacementConstraint}()},
#' \code{\link{launcherSubmitJob}()}, \code{\link{launcherSubmitR}()}
#' @export launcherResourceLimit
launcherResourceLimit <- function(type, value) {
callLauncherFun("launcher.newResourceLimit",
type = type,
value = value)
}
#' Define a Launcher Host Mount
#'
#' Define a launcher host mount, suitable for use with the \code{mounts}
#' argument to \code{\link[=launcherSubmitJob]{launcherSubmitJob()}}. This can
#' be used to mount a path from the host into the generated container.
#'
#'
#' @param path The host path to be mounted.
#' @param mountPath The destination path for the mount in the container.
#' @param readOnly Boolean; should the path be mounted read-only?
#' @seealso Other job submission: \code{\link{launcherConfig}()},
#' \code{\link{launcherContainer}()}, \code{\link{launcherNfsMount}()},
#' \code{\link{launcherPlacementConstraint}()},
#' \code{\link{launcherResourceLimit}()}, \code{\link{launcherSubmitJob}()},
#' \code{\link{launcherSubmitR}()}
#' @export launcherHostMount
launcherHostMount <- function(path,
mountPath,
readOnly = TRUE)
{
callLauncherFun("launcher.newHostMount",
path = path,
mountPath = mountPath,
readOnly = readOnly)
}
#' Define a Launcher NFS Mount
#'
#' Define a launcher NFS mount, suitable for use with the \code{mounts}
#' argument to \code{\link[=launcherSubmitJob]{launcherSubmitJob()}}. This can
#' be used to mount a path from a networked filesystem into a newly generated
#' container.
#'
#'
#' @param host The host name, or IP address, of the NFS server.
#' @param path The NFS path to be mounted.
#' @param mountPath The destination path for the mount in the container.
#' @param readOnly Boolean; should the path be mounted read-only?
#' @seealso Other job submission: \code{\link{launcherConfig}()},
#' \code{\link{launcherContainer}()}, \code{\link{launcherHostMount}()},
#' \code{\link{launcherPlacementConstraint}()},
#' \code{\link{launcherResourceLimit}()}, \code{\link{launcherSubmitJob}()},
#' \code{\link{launcherSubmitR}()}
#' @export launcherNfsMount
launcherNfsMount <- function(host,
path,
mountPath,
readOnly = TRUE)
{
callLauncherFun("launcher.newNfsMount",
host = host,
path = path,
mountPath = mountPath,
readOnly = readOnly)
}
#' Submit a Launcher Job
#'
#' Submit a launcher job. See
#' https://docs.rstudio.com/job-launcher/latest/index.html for more
#' information.
#'
#'
#' @param name A descriptive name to assign to the job.
#' @param cluster The name of the cluster this job should be submitted to.
#' @param tags A set of user-defined tags, used for searching and querying
#' jobs.
#' @param command The command to run within the job. This is executed via the
#' system shell. Only one of command or exe should be specified.
#' @param exe The (fully pathed) executable to run within the job. Only one of
#' \code{command} or \code{exe} should be specified.
#' @param args An array of arguments to pass to the command / executable.
#' @param environment A list of environment variables to be set for processes
#' launched with this job.
#' @param stdin Data to be written to stdin when the job process is launched.
#' @param stdoutFile The file used for the job's generated standard output. Not
#' all launcher plugins support this parameter.
#' @param stderrFile The file used for the job's generated standard error. Not
#' all launcher plugins support this parameter.
#' @param workingDirectory The working directory to be used by the command /
#' executable associated with this job.
#' @param host The host that the job is running on, or the desired host during
#' job submission.
#' @param container The container to be used for launched jobs.
#' @param exposedPorts The ports that are exposed by services running on a
#' container. Only applicable to systems that support containers.
#' @param mounts A list of mount points. See
#' \code{\link[=launcherHostMount]{launcherHostMount()}} and
#' \code{\link[=launcherNfsMount]{launcherNfsMount()}} for more information.
#' @param placementConstraints A list of placement constraints. See
#' \code{\link[=launcherPlacementConstraint]{launcherPlacementConstraint()}}
#' for more information.
#' @param resourceLimits A list of resource limits. See
#' \code{\link[=launcherResourceLimit]{launcherResourceLimit()}} for more
#' information.
#' @param queues A list of available submission queues for the cluster. Only
#' applicable to batch systems like LSF.
#' @param config A list of cluster-specific configuration options. See
#' \code{\link[=launcherConfig]{launcherConfig()}} for more information.
#' @param user The user-name of the job owner.
#' @param applyConfigSettings Apply server-configured mounts, exposedPorts, and
#' environment, in addition to any specified in this call.
#' @seealso Other job submission: \code{\link{launcherConfig}()},
#' \code{\link{launcherContainer}()}, \code{\link{launcherHostMount}()},
#' \code{\link{launcherNfsMount}()},
#' \code{\link{launcherPlacementConstraint}()},
#' \code{\link{launcherResourceLimit}()}, \code{\link{launcherSubmitR}()}
#' @export launcherSubmitJob
launcherSubmitJob <- function(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)
{
callLauncherFun("launcher.submitJob",
args = args,
cluster = cluster,
command = command,
config = config,
container = container,
environment = environment,
exe = exe,
exposedPorts = exposedPorts,
host = host,
mounts = mounts,
name = name,
placementConstraints = placementConstraints,
queues = queues,
resourceLimits = resourceLimits,
stderrFile = stderrFile,
stdin = stdin,
stdoutFile = stdoutFile,
tags = tags,
user = user,
workingDirectory = workingDirectory,
applyConfigSettings = applyConfigSettings)
}
#' Execute an R Script as a Launcher Job
#'
#' Convenience function for running an R script as a launcher job using
#' whichever R is found on the path in the launcher cluster.
#'
#' See \code{\link[=launcherSubmitJob]{launcherSubmitJob()}} for running jobs
#' with full control over command, environment, and so forth.
#'
#' @param script Fully qualified path of R script. Must be a path that is
#' available in the job container (if using containerized job cluster such as
#' Kubernetes).
#' @param cluster The name of the cluster this job should be submitted to.
#' @param container The container to be used for launched jobs.
#' @seealso Other job submission: \code{\link{launcherConfig}()},
#' \code{\link{launcherContainer}()}, \code{\link{launcherHostMount}()},
#' \code{\link{launcherNfsMount}()},
#' \code{\link{launcherPlacementConstraint}()},
#' \code{\link{launcherResourceLimit}()}, \code{\link{launcherSubmitJob}()}
#' @export launcherSubmitR
launcherSubmitR <- function(script,
cluster = "Local",
container = NULL)
{
# don't proactively check for existence of the script; possible the supplied
# path only resolves correctly in the job cluster
scriptPath <- path.expand(script)
scriptFile <- basename(scriptPath)
scriptArg <- paste("-f", scriptPath)
jobTag <- paste("rstudio-r-script-job", scriptFile, sep = ":")
callLauncherFun("launcher.submitJob",
args = c("--slave", "--no-save", "--no-restore", scriptArg),
cluster = cluster,
command = "R",
container = container,
name = scriptFile,
tags = c(jobTag),
applyConfigSettings = TRUE)
}
#' Interact with (Control) a Job
#'
#' Interact with a job.
#'
#'
#' @param jobId The job id.
#' @param operation The operation to execute. The operation should be one of
#' \code{c("suspend", "resume", "stop", "kill", "cancel")}. Note that different
#' launcher plugins support different subsets of these operations -- consult
#' your launcher plugin documentation to see which operations are supported.
#' @export launcherControlJob
launcherControlJob <- function(jobId,
operation = c("suspend", "resume", "stop", "kill", "cancel"))
{
callLauncherFun("launcher.controlJob",
jobId = jobId,
operation = operation)
}
rstudioapi/R/files-pane.R 0000644 0001762 0000144 00000000517 13752325402 015012 0 ustar ligges users #' Navigate to a Directory in the Files Pane
#'
#' Navigate to a directory in the Files pane. The contents of that directory
#' will be listed and shown in the Files pane.
#'
#'
#' @param path The filesystem path to be shown.
#' @export filesPaneNavigate
filesPaneNavigate <- function(path) {
callFun("filesPaneNavigate", path)
}
rstudioapi/R/jobs.R 0000644 0001762 0000144 00000016466 13752325403 013737 0 ustar ligges users #' Add a Job
#'
#' Inform RStudio's Jobs pane that a job has been added.
#'
#'
#' @param name The job's name.
#' @param status The initial status text for the job; optional.
#' @param progressUnits The integer number of units of work in the job; for
#' example, \code{100L} if the job's progress is expressed in percentages. Use
#' \code{0L} if the number of units of work is unknown.
#' @param actions A list of actions that can be performed on the job (see
#' Actions).
#' @param running Whether the job is currently running.
#' @param autoRemove Whether to remove the job from the Jobs pane when it's
#' complete.
#' @param show Whether to show the job in the Jobs pane.
#' @return An ID representing the newly added job, used as a handle to provide
#' further updates of the job's status.
#' @section Actions:
#'
#' The \code{actions} parameter is a named list of functions that the user can
#' invoke on the job; for example: \code{actions = list(stop = function(id) {
#' ... })}. The function will be passed a parameter named \code{id} with the
#' job ID that invoked it.
#'
#' There are two special action names: \describe{ \item{stop}{If there is an
#' action named \code{stop}, then the job will have a Stop button in in the
#' Jobs pane, and pressing that button will invoke the \code{stop} action.}
#' \item{info}{If there is an action named \code{info}, then the job will have
#' an informational link in the Jobs pane rather than an output display, and
#' clicking the link will invoke the \code{info} action.} }
#' @seealso Other jobs: \code{\link{jobAddOutput}()},
#' \code{\link{jobAddProgress}()}, \code{\link{jobRemove}()},
#' \code{\link{jobRunScript}()}, \code{\link{jobSetProgress}()},
#' \code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
#' @export jobAdd
jobAdd <- function(name, status = "", progressUnits = 0L, actions = NULL, running = FALSE,
autoRemove = TRUE, show = TRUE) {
callFun("addJob", name = name,
status = status,
progressUnits = progressUnits,
actions = actions,
running = running,
autoRemove = autoRemove,
show = show)
}
#' Remove a Job
#'
#' Remove a job from RStudio's Jobs pane.
#'
#'
#' @param job The ID of the job to remove.
#' @seealso Other jobs: \code{\link{jobAddOutput}()},
#' \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
#' \code{\link{jobRunScript}()}, \code{\link{jobSetProgress}()},
#' \code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
#' @export jobRemove
jobRemove <- function(job) {
callFun("removeJob", job = job)
}
#' Set Job Progress
#'
#' Updates the progress for a job.
#'
#'
#' @param job The ID of the job to set progress for.
#' @param units The integer number of total units of work completed so far.
#' @seealso Other jobs: \code{\link{jobAddOutput}()},
#' \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
#' \code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
#' \code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
#' @export jobSetProgress
jobSetProgress <- function(job, units) {
callFun("setJobProgress", job = job, units = units)
}
#' Add Job Progress
#'
#' Adds incremental progress units to a job.
#'
#'
#' @param job The ID of the job to update progress for.
#' @param units The integer number of new progress units completed.
#' @seealso Other jobs: \code{\link{jobAddOutput}()}, \code{\link{jobAdd}()},
#' \code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
#' \code{\link{jobSetProgress}()}, \code{\link{jobSetState}()},
#' \code{\link{jobSetStatus}()}
#' @export jobAddProgress
jobAddProgress <- function(job, units) {
callFun("addJobProgress", job = job, units = units)
}
#' Set Job Status
#'
#' Update a job's informational status text.
#'
#'
#' @param job The ID of the job to update.
#' @param status Text describing job's new status.
#' @seealso Other jobs: \code{\link{jobAddOutput}()},
#' \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
#' \code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
#' \code{\link{jobSetProgress}()}, \code{\link{jobSetState}()}
#' @export jobSetStatus
jobSetStatus <- function(job, status) {
callFun("setJobStatus", job = job, status = status)
}
#' Set Job State
#'
#' Changes the state of a job.
#'
#'
#' @param job The ID of the job on which to change state.
#' @param state The new job state.
#' @section States:
#'
#' The following states are supported: \describe{ \item{idle}{The job is
#' waiting to run.} \item{running}{The job is actively running.}
#' \item{succeeded}{The job has finished successfully.} \item{cancelled}{The
#' job was cancelled.} \item{failed}{The job finished but did not succeed.} }
#' @seealso Other jobs: \code{\link{jobAddOutput}()},
#' \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
#' \code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
#' \code{\link{jobSetProgress}()}, \code{\link{jobSetStatus}()}
#' @export jobSetState
jobSetState <- function(job, state = c("idle", "running", "succeeded", "cancelled", "failed")) {
callFun("setJobState", job = job, state = state)
}
#' Add Job Output
#'
#' Adds text output to a job.
#'
#'
#' @param job The ID of the job that has emitted text.
#' @param output The text output emitted by the job.
#' @param error Whether the output represents an error.
#' @seealso Other jobs: \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
#' \code{\link{jobRemove}()}, \code{\link{jobRunScript}()},
#' \code{\link{jobSetProgress}()}, \code{\link{jobSetState}()},
#' \code{\link{jobSetStatus}()}
#' @export jobAddOutput
jobAddOutput <- function(job, output, error = FALSE) {
callFun("addJobOutput", job = job, output = output, error = error)
}
#' Run R Script As Job
#'
#' Starts an R script as a background job.
#'
#'
#' @param path The path to the R script to be run.
#' @param name A name for the background job. When \code{NULL} (the default),
#' the filename of the script is used as the job name.
#' @param encoding The text encoding of the script, if known.
#' @param workingDir The working directory in which to run the job. When
#' \code{NULL} (the default), the parent directory of the R script is used.
#' @param importEnv Whether to import the global environment into the job.
#' @param exportEnv The name of the environment in which to export the R
#' objects created by the job. Use \code{""} (the default) to skip export,
#' \code{"R_GlobalEnv"}` to export to the global environment, or the name of an
#' environment object to create an object with that name.
#' @seealso Other jobs: \code{\link{jobAddOutput}()},
#' \code{\link{jobAddProgress}()}, \code{\link{jobAdd}()},
#' \code{\link{jobRemove}()}, \code{\link{jobSetProgress}()},
#' \code{\link{jobSetState}()}, \code{\link{jobSetStatus}()}
#' @export jobRunScript
jobRunScript <- function(path, name = NULL, encoding = "unknown", workingDir = NULL,
importEnv = FALSE, exportEnv = "") {
path <- normalizePath(path, winslash = "/", mustWork = TRUE)
callFun("runScriptJob", path = path,
name = name,
encoding = encoding,
workingDir = workingDir,
importEnv = importEnv,
exportEnv = exportEnv)
}
rstudioapi/R/document-methods.R 0000644 0001762 0000144 00000012546 13752325403 016254 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.
#'
#'
#' @aliases document_position is.document_position as.document_position
#' @param row The row (using 1-based indexing).
#' @param column The column (using 1-based indexing).
#' @param x An object coercable to \code{document_position}.
#' @export document_position
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.
#'
#'
#' @aliases document_range is.document_range as.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.
#' @param x An object coercable to \code{document_range}.
#' @return An \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 }
#' @export document_range
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
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)
if (is.null(context)) return(NULL)
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 13535525640 013716 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/R/launcher.R 0000644 0001762 0000144 00000001357 13535525640 014600 0 ustar ligges users
callLauncherFun <- function(fname, ...) {
verifyAvailable()
if (hasFun(fname))
return(callFun(fname, ...))
if (!exists("RStudio.Version", envir = globalenv()))
stop("RStudio is not available.", call. = FALSE)
RStudio.Version <- get("RStudio.Version", envir = globalenv())
version <- RStudio.Version()
if (is.null(version$edition)) {
fmt <- "Launcher API '%s' is not available in the open-source edition of RStudio."
stop(sprintf(fmt, fname))
}
if (identical(version$mode, "desktop")) {
fmt <- "Launcher API '%s' is not yet available in the Desktop edition of RStudio."
stop(sprintf(fmt, fname))
}
fmt <- "Launcher API '%s' is not available in this version of RStudio."
stop(sprintf(fmt, fname))
}
rstudioapi/R/prefs.R 0000644 0001762 0000144 00000006661 13752325404 014116 0 ustar ligges users #' Read Preference
#'
#' Reads a user preference, useful to remember preferences across different R
#' sessions for the same user.
#'
#' User preferences can have arbitrary names and values. You must write the
#' preference with \code{\link{writePreference}} before it can be read
#' (otherwise its default value will be returned).
#'
#' @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.
#' @seealso \code{\link{readRStudioPreference}}, which reads RStudio IDE
#' preferences.
#' @export readPreference
readPreference <- function(name, default) {
callFun("readPreference", name, default)
}
#' Write Preference
#'
#' Writes a user 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.
#' @seealso \code{\link{writeRStudioPreference}}, which changes RStudio IDE
#' preferences.
#' @export writePreference
writePreference <- function(name, value) {
callFun("writePreference", name, value)
}
#' Write RStudio Preference
#'
#' Writes an internal RStudio IDE preference for the current user.
#'
#' 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.
#'
#' @param name The name of the preference.
#' @param value The value of the preference.
#' @note The \code{writeRStudioPreference} function was added in version
#' 1.3.387 of RStudio.
#' @seealso \code{\link{writePreference}}, which can be used to store arbitrary
#' user (non-RStudio) preferences.
#'
#' \code{\link{readRStudioPreference}}, which reads internal RStudio IDE
#' preferences.
#' @examples
#'
#' \dontrun{
#' # Hide RStudio's toolbar.
#' rstudioapi::writeRStudioPreference("toolbar_visible", FALSE)
#' }
#'
#'
#' @export writeRStudioPreference
writeRStudioPreference <- function(name, value) {
callFun("writeRStudioPreference", name, value)
}
#' Read RStudio Preference
#'
#' Reads an internal RStudio IDE preference for the current user.
#'
#' RStudio IDE internal preferences include the values displayed in RStudio's
#' Global Options dialog as well as a number of additional settings.
#'
#' @param name The name of the preference.
#' @param default The default value of the preference, returned if the
#' preference is not found.
#' @note The \code{readRStudioPreference} function was added in version 1.3.387
#' of RStudio.
#' @seealso \code{\link{readPreference}}, which can be used to read arbitrary
#' user (non-RStudio) preferences set with \code{\link{writePreference}}.
#'
#' \code{link{writeRStudioPreference}}, which can be used to write internal
#' RStudio IDE preferences.
#' @examples
#'
#' \dontrun{
#' # Get indentation settings
#' spaces <- rstudioapi::readRStudioPreference("num_spaces_for_tab", FALSE)
#' message("Using ", spaces, " per tab.")
#' }
#'
#'
#' @export readRStudioPreference
readRStudioPreference <- function(name, default) {
callFun("readRStudioPreference", name, default)
}
rstudioapi/R/bug-report.R 0000644 0001762 0000144 00000003362 13752325402 015056 0 ustar ligges users #' File an RStudio Bug Report
#'
#' 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.
#'
#'
#' @export bugReport
bugReport <- function() {
verifyAvailable()
rstudioInfo <- versionInfo()
rstudioVersion <- format(rstudioInfo$version)
rstudioEdition <- sprintf(
"%s [%s]",
if (rstudioInfo$mode == "desktop") "Desktop" else "Server",
if (is.null(rstudioInfo$edition)) "Open Source" else toupper(rstudioInfo$edition)
)
rInfo <- utils::sessionInfo()
rVersion <- rInfo$R.version$version.string
rVersion <- sub("^R version", "", rVersion, fixed = TRUE)
osVersion <- rInfo$running
templateFile <- system.file("resources/bug-report.md", package = "rstudioapi")
template <- readLines(templateFile)
rendered <- renderTemplate(template, list(
RSTUDIO_VERSION = rstudioVersion,
RSTUDIO_EDITION = rstudioEdition,
OS_VERSION = osVersion,
R_VERSION = rVersion
))
if (rstudioInfo$mode == "desktop" && requireNamespace("clipr", quietly = TRUE)) {
clipr::write_clip(rendered)
writeLines("* The bug report template has been written to the clipboard.")
writeLines("* Please paste the clipboard contents into the issue comment section,")
writeLines("* and then fill out the rest of the issue details.")
} else {
header <- ""
text <- c(header, rendered)
file <- tempfile("rstudio-bug-report-", fileext = ".html")
on.exit(unlink(file), add = TRUE)
writeLines(text, con = file)
utils::file.edit(file)
}
url <- "https://github.com/rstudio/rstudio/issues/new"
utils::browseURL(url)
}
rstudioapi/R/dependencies.R 0000644 0001762 0000144 00000001516 13752325402 015415 0 ustar ligges users #' Get RStudio Package Dependencies
#'
#' Gets a list of the all the R packages that RStudio depends on in some way.
#'
#' The data frame of package dependencies contains the following columns:
#' \describe{ \item{name}{The name of the R package.} \item{version}{The
#' required minimum version of the R package.} \item{location}{Where RStudio
#' expects the package to be, \code{cran} for a CRAN-like repository or
#' \code{embedded} for development packages embedded in RStudio itself.}
#' \item{source}{Whether the package should be installed from source.} }
#'
#' @return A data frame containing a row per R package.
#' @note The \code{getRStudioPackageDependencies} function was introduced in
#' RStudio 1.3.525.
#' @export getRStudioPackageDependencies
getRStudioPackageDependencies <- function() {
callFun("getPackageDependencies")
}
rstudioapi/R/dictionaries.R 0000644 0001762 0000144 00000001526 13535525640 015452 0 ustar ligges users
#' Interact with RStudio's Dictionaries
#'
#' Interact with the [hunspell](https://hunspell.github.io/) dictionaries
#' used by RStudio for spell checking.
#'
#' `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. See:
#'
#' \url{https://support.rstudio.com/hc/en-us/articles/200551916-Spelling-Dictionaries}
#'
#' for more information.
#'
#' @note The `dictionariesPath()` and `userDictionariesPath()` functions were
#' introduced with RStudio 1.2.1202.
#'
#' @name dictionaries
NULL
#' @name dictionaries
#' @export
dictionariesPath <- function() {
callFun("dictionariesPath")
}
#' @name dictionaries
#' @export
userDictionariesPath <- function() {
callFun("userDictionariesPath")
}
rstudioapi/R/build-tools.R 0000644 0001762 0000144 00000002675 13535525640 015240 0 ustar ligges users #' Build Tools
#'
#' Check, install, and use build tools as required.
#'
#' 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:
#'
#' ```R
#' 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.
#'
#' @param action The action (as a string) being taken that will require
#' installation of build tools.
#'
#' @param expr An \R expression (unquoted) to be executed with build tools
#' available and on the `PATH`.
#'
#' @note The `buildToolsCheck()`, `buildToolsInstall()`, and `buildToolsExec()`
#' functions were added with version 1.2.962 of RStudio.
#'
#' @name build-tools
NULL
#' @name build-tools
#' @export
buildToolsCheck <- function() {
callFun("buildToolsCheck")
}
#' @name build-tools
#' @export
buildToolsInstall <- function(action) {
callFun("buildToolsInstall", action)
}
#' @name build-tools
#' @export
buildToolsExec <- function(expr) {
callFun("buildToolsExec", expr)
}
rstudioapi/R/tutorial.R 0000644 0001762 0000144 00000000124 13617331207 014624 0 ustar ligges users
tutorialLaunchBrowser <- function(url) {
callFun("tutorialLaunchBrowser", url)
}
rstudioapi/R/highlight-ui.R 0000644 0001762 0000144 00000005100 13752325403 015343 0 ustar ligges users #' Highlight UI Elements within the RStudio IDE
#'
#' 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.
#'
#' The tool at:\preformatted{Help -> Diagnostics -> Show DOM Elements }
#'
#' can be useful for identifying the classes and IDs assigned to the different
#' elements within RStudio.
#'
#' @param queries A list of "query" objects. Each query should be a list with
#' entries \code{"query"} and \code{"parent"}. See \strong{Queries} for more
#' details.
#' @note The \code{highlightUi} function was introduced in RStudio 1.3.658.
#' @section Queries:
#'
#' Elements are selected using the same queries as through the web
#' \code{querySelectorAll()} API. See
#' \url{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:\preformatted{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 \verb{From Text
#' (readr)} command, you might use:\preformatted{rstudioapi::highlightUi( list(
#' list(query = "#rstudio_mb_import_dataset", parent = 0L), list(query =
#' "#rstudio_label_from_text_readr_command", parent = 1L) ) ) }
#' @examples
#'
#' \dontrun{rstudioapi::highlightUi("#rstudio_workbench_panel_git")}
#'
#' # clear current highlights
#' \dontrun{rstudioapi::highlightUi("")}
#'
#' # highlight within an RMD
#' \dontrun{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.
#' \dontrun{rstudioapi::highlightUi(
#' list(
#' list(
#' query="#rstudio_workbench_panel_git",
#' callback="rstudioapi::highlightUi('')"
#' )
#' )
#' )}
#'
#' @export highlightUi
highlightUi <- function(queries) {
queries <- lapply(queries, function(data) {
if (is.character(data))
data <- list(query = data, parent = 0L)
if (is.null(data$query))
stop("missing 'query' in highlight request")
data$highlight <- as.integer(data$highlight %||% 0)
data
})
invisible(callFun("highlightUi", queries))
}
rstudioapi/R/themes.R 0000644 0001762 0000144 00000013331 13752325403 014253 0 ustar ligges users #' Retrieve Themes
#'
#' Retrieves a list with information about the current color theme used by
#' RStudio.
#'
#' A list is returned with the following elements: \describe{ \item{editor}{The
#' name of the current editor theme, such as \code{Textmate}.}
#' \item{global}{The name of the current global theme. One of \code{Modern},
#' \code{Classic}, or \code{Sky}.} \item{dark}{\code{TRUE} if the editor theme
#' is dark, \code{FALSE} otherwise.} \item{foreground}{The current editor
#' theme's default text foreground color, formatted as a CSS-compatible color
#' string, such as \code{rgb(1, 22, 39)}. Supported since RStudio 1.2.1214.}
#' \item{background}{The current editor theme's default text background color,
#' formatted as a CSS-compatible color string. Supported since RStudio
#' 1.2.1214.} }
#'
#' @export getThemeInfo
getThemeInfo <- function() {
callFun("getThemeInfo")
}
#' Add a Custom Editor Theme
#'
#' Adds a custom editor theme to RStudio and returns the name of the newly
#' added theme.
#'
#'
#' @param themePath A full or relative path or URL to an \code{rstheme} or
#' \code{tmtheme} to be added.
#' @param apply Whether to immediately apply the newly added theme. Setting
#' this to \code{TRUE} has the same impact as running \code{{
#' rstudioapi::addTheme(); rstudioapi::applyTheme()
#' }}.\cr Default: \code{FALSE}.
#' @param force Whether to force the operation and overwrite an existing file
#' with the same name.\cr Default: \code{FALSE}.
#' @param globally Whether to install this theme for the current user or all
#' users. If set to \code{TRUE} this will attempt to install the theme for all
#' users, which may require administrator privileges.\cr Default: \code{FALSE}.
#' @note The \code{addTheme} function was introduced in RStudio 1.2.879.
#' @export addTheme
addTheme <- function(themePath,
apply = FALSE,
force = FALSE,
globally = FALSE)
{
path <- themePath
# Ensure path looks like something we can use
ext <- tolower(tools::file_ext(path))
if (!identical(ext, "rstheme") && !identical(ext, "tmtheme")) {
stop("Invalid path ", path, ". ",
"Please supply a path or URL to an .rstheme or .tmtheme file to add.")
}
# If the path appears to be a URL, download it.
if (grepl("^https?:", themePath)) {
# Give the downloaded filename the same name and extension as the original.
path <- file.path(tempdir(), utils::URLdecode(basename(themePath)))
if (file.exists(path)) {
# It's unlikely that the theme file will exist in the temp dir, but move it out
# of the way if it does.
unlink(path)
}
# Perform the download
utils::download.file(themePath, path)
}
if (identical(ext, "tmtheme")) {
# needs conversion first
convertTheme(path, add = TRUE, apply = apply, force = force, globally = globally)
} else if (identical(ext, "rstheme")) {
# no conversion necessary
callFun("addTheme", path, apply, force, globally)
}
}
#' Apply an Editor Theme to RStudio
#'
#' Applies the specified editor theme to RStudio.
#'
#'
#' @param name The unique name of the theme to apply.
#' @note The \code{applyTheme} function was introduced in RStudio 1.2.879.
#' @export applyTheme
applyTheme <- function(name)
{
callFun("applyTheme", name)
}
#' Convert a tmTheme to an RStudio Theme
#'
#' Converts a \code{tmTheme} to an \code{rstheme} and optionally adds and
#' applies it to RStudio and returns the name of the theme.
#'
#'
#' @param themePath A full or relative path to the \code{tmTheme} file to be
#' converted.
#' @param add Whether to add the newly converted theme to RStudio. Setting this
#' to true will have the same impact as running \code{{
#' rstudioapi::convertTheme(, outputLocation =
#' ); rstudioapi::addTheme() }}.\cr
#' Default: \code{TRUE}.
#' @param outputLocation A full or relative path where a copy of the converted
#' theme will be saved. If this value is \code{NULL}, no copy will be saved.\cr
#' Default: \code{NULL}.
#' @param apply Whether to immediately apply the newly added theme. This
#' paramater cannot be set to \code{TRUE} if \code{add} is set to \code{FALSE}.
#' Setting this and \code{add} to \code{TRUE} has the same impact as running
#' \code{{ rstudioapi::convertTheme(, outputLocation =
#' ); rstudioapi::addTheme();
#' rstudioapi::applyTheme() }}.\cr Default: \code{FALSE}.
#' @param force Whether to force the operation and overwrite an existing file
#' with the same name.\cr Default: \code{FALSE}.
#' @param globally Whether to install this theme for the current user or all
#' users. If set to \code{TRUE} this will attempt to install the theme for all
#' users, which may require administrator privileges. Only applies when
#' \code{add} is \code{TRUE}. \cr Default: \code{FALSE}.
#' @note The \code{convertTheme} function was introduced in RStudio 1.2.879.
#' @export convertTheme
convertTheme <- function(themePath, add = TRUE, outputLocation = NULL, apply = FALSE, force = FALSE, globally = FALSE)
{
callFun("convertTheme", themePath, add, outputLocation, apply, force, globally)
}
#' Get Theme List
#'
#' Retrieves a list of the names of all the editor themes installed for
#' RStudio.
#'
#'
#' @note The \code{getThemes} function was introduced in RStudio 1.2.879.
#' @export getThemes
getThemes <- function()
{
callFun("getThemes")
}
#' Remove a custom theme from RStudio.
#'
#' Remove a custom theme from RStudio.
#'
#'
#' @param name The unique name of the theme to remove.
#' @note The \code{removeTheme} function was introduced in RStudio 1.2.879.
#' @export removeTheme
removeTheme <- function(name)
{
callFun("removeTheme", name)
}
rstudioapi/R/remote.R 0000644 0001762 0000144 00000003557 13724224715 014275 0 ustar ligges users
isChildProcess <- function() {
!is.na(Sys.getenv("RSTUDIOAPI_IPC_REQUESTS_FILE", unset = NA))
}
callRemote <- function(call, frame) {
# check for active request / response
requestFile <- Sys.getenv("RSTUDIOAPI_IPC_REQUESTS_FILE", unset = NA)
responseFile <- Sys.getenv("RSTUDIOAPI_IPC_RESPONSE_FILE", unset = NA)
secret <- Sys.getenv("RSTUDIOAPI_IPC_SHARED_SECRET", unset = NA)
if (is.na(requestFile) || is.na(responseFile) || is.na(secret))
stop("internal error: callRemote() called without remote connection")
# clean up on exit
on.exit(unlink(c(requestFile, responseFile)), add = TRUE)
# remove srcrefs (un-needed for serialization here)
attr(call, "srcref") <- NULL
# ensure rstudioapi functions get appropriate prefix
if (is.name(call[[1L]])) {
call_fun <- call("::", as.name("rstudioapi"), call[[1L]])
} else {
call_fun <- call[[1L]]
}
# ensure arguments are evaluated before sending request
call[[1L]] <- quote(base::list)
args <- eval(call, envir = frame)
call <- as.call(c(call_fun, args))
# write to tempfile and rename, to ensure atomicity
data <- list(secret = secret, call = call)
tmp <- tempfile(tmpdir = dirname(requestFile))
saveRDS(data, file = tmp)
file.rename(tmp, requestFile)
# loop until response is ready (poll)
# in theory we'd just do a blocking read but there isn't really a good
# way to do this in a cross-platform way without additional dependencies
now <- Sys.time()
repeat {
# check for response
if (file.exists(responseFile))
break
# check for lack of response
diff <- difftime(Sys.time(), now, units = "secs")
if (diff > 10)
stop("RStudio did not respond to rstudioapi IPC request")
# wait a bit
Sys.sleep(0.1)
}
# read response
response <- readRDS(responseFile)
if (inherits(response, "error"))
stop(response)
response
}
rstudioapi/R/templates.R 0000644 0001762 0000144 00000006407 13752325402 014771 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 package sources.
#' @param binding The 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
createProjectTemplate <- function(package = ".",
binding,
title,
subtitle = paste("Create a new", title),
caption = paste("Create", title),
icon = NULL,
open_files = NULL,
overwrite = FALSE,
edit = TRUE)
{
package <- normalizePath(package, winslash = "/", mustWork = TRUE)
# construct metadata
metadata <- list(
Binding = binding,
Title = title,
Subtitle = subtitle,
Caption = caption,
Icon = icon,
OpenFiles = open_files
)
# drop nulls
metadata <-
metadata[vapply(metadata, Negate(is.null), FUN.VALUE = logical(1))]
# create templates directory
templates_dir <- file.path(package, "inst/rstudio/templates/project")
if (!file.exists(templates_dir))
if (!dir.create(templates_dir, recursive = TRUE))
stop(sprintf("failed to create '%s' directory", templates_dir))
# construct DCF metadata contents
dcf <- paste(names(metadata), ": ", metadata, sep = "")
# add header linking to online documentation
header <- c(
"# This file provides the metadata necessary for RStudio to",
"# use the '%s()' function when initializing a project. See",
"# the documentation online at: ",
"#",
"# https://rstudio.github.io/rstudio-extensions/rstudio_project_templates.html",
"#",
"# for more details.",
""
)
header <- sprintf(header, binding)
dcf <- c(header, dcf)
# construct path to file
name <- gsub("[^a-zA-Z0-9_.]", "_", binding)
path <- file.path(templates_dir, paste(name, "dcf", sep = "."))
if (file.exists(path) && !overwrite)
stop(sprintf("a skeleton function already exists at path '%s'", path))
# write out
writeLines(dcf, con = path)
if (edit)
utils::file.edit(path)
TRUE
}
rstudioapi/R/code.R 0000644 0001762 0000144 00000010411 13752575704 013707 0 ustar ligges users #' Check if RStudio is running
#'
#' Check if RStudio is running.
#'
#' @aliases isAvailable verifyAvailable
#'
#' @param version_needed An optional version specification. If supplied, ensures
#' that RStudio is at least that version.
#'
#' @param child_ok Boolean; check if the current R process is a child process of
#' the main RStudio session? This can be useful for e.g. RStudio Jobs, where
#' you'd like to communicate back with the main R session from a child process
#' through \code{rstudioapi}.
#'
#' @return \code{isAvailable} a boolean; \code{verifyAvailable} an error message
#' if RStudio is not running
#'
#' @examples
#'
#' rstudioapi::isAvailable()
#' \dontrun{rstudioapi::verifyAvailable()}
#'
#' @export
isAvailable <- function(version_needed = NULL, child_ok = FALSE) {
if (child_ok && isChildProcess())
return(callRemote(sys.call(), parent.frame()))
identical(.Platform$GUI, "RStudio") && version_ok(version_needed)
}
version_ok <- function(version = NULL) {
if (is.null(version)) return(TRUE)
getVersion() >= version
}
#' @rdname isAvailable
#' @export
verifyAvailable <- function(version_needed = NULL) {
if (!isAvailable()) stop("RStudio not running", call. = FALSE)
if (!version_ok(version_needed)) {
stop("Need at least version ", version_needed, " of RStudio. ",
"Currently running ", getVersion(), call. = FALSE)
}
invisible(TRUE)
}
#' Return the current version of the RStudio API
#'
#' Return the current version of the RStudio API
#'
#'
#' @return A \code{\link{numeric_version}} which you can compare to a string
#' and get correct results.
#' @examples
#'
#' \dontrun{
#' if (rstudioapi::getVersion() < "0.98.100") {
#' message("Your version of RStudio is quite old")
#' }
#' }
#'
#' @export getVersion
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
#' @examples
#'
#' if (rstudioapi::isAvailable()) {
#' rstudioapi::callFun("versionInfo")
#' }
#'
#' @export callFun
callFun <- function(fname, ...) {
if (isChildProcess())
return(callRemote(sys.call(), parent.frame()))
verifyAvailable()
if (usingTools())
found <- exists(toolsName(fname), envir = toolsEnv(), mode = "function")
else
found <- exists(fname, envir = asNamespace("rstudio"), mode = "function")
if (!found)
stop("Function ", fname, " not found in RStudio", call. = FALSE)
f <- findFun(fname, mode = "function")
args <- list(...)
if (!"..." %in% names(formals(f)))
{
while (length(args) > length(formals(f)))
args <- args[-length(args)]
}
do.call(f, args)
}
#' 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}.
#'
#'
#' @aliases hasFun findFun
#' @param name name of object to look for
#' @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.
#' @param ... other arguments passed on to \code{\link[base]{exists}} and
#' \code{\link[base]{get}}
#' @examples
#'
#' rstudioapi::hasFun("viewer")
#'
#' @export hasFun
hasFun <- function(name, version_needed = NULL, ...) {
if (!isAvailable(version_needed)) return(FALSE)
if (usingTools())
exists(toolsName(name), toolsEnv(), ...)
else
exists(name, envir = asNamespace("rstudio"), ...)
}
#' @export
#' @rdname hasFun
findFun <- function(name, version_needed = NULL, ...) {
verifyAvailable(version_needed)
if (usingTools())
get(toolsName(name), toolsEnv(), ...)
else
get(name, envir = asNamespace("rstudio"), ...)
}
usingTools <- function() {
exists(toolsName("versionInfo"), envir = toolsEnv())
}
toolsName <- function(name) {
paste(".rs.api.", name, sep="")
}
toolsEnv <- function() {
as.environment(match("tools:rstudio", search()))
}
rstudioapi/NEWS.md 0000644 0001762 0000144 00000006505 13753072370 013550 0 ustar ligges users
# rstudioapi 0.13
* Fixed an issue where `rstudioapi::insertText()` would fail. (#208)
# rstudioapi 0.12
* Fixed an issue where remote `rstudioapi` calls would erroneously use
a previous response in some cases.
* Allow `navigateToFile` to accept an empty file. This file will default to the file
currently in view in the active column.
* Added `registerChunkExecCallback` and `unregisterChunkExecCallback`, used to execute a callback after a chunk is ran.
# rstudioapi 0.11
* `rstudioapi::launcherResourceLimit()` now properly delegates the type
and memory arguments. (#164)
* `rstudioapi` gains the function `highlightUi()`, used to highlight UI
elements in newer versions of RStudio.
* Paths returned from `selectFile()` are now properly marked with
UTF-8 encoding.
* It is now possible for `rstudioapi` to communicate with a parent RStudio
session, for R sessions launched as RStudio jobs. Use
`rstudioapi::isAvailable(child_ok = TRUE)` to assert that it's okay to check
that `rstudioapi` is available and is running within an RStudio job.
* Added `bugReport()`, a helper function for reporting RStudio bugs
on the GitHub issue tracker with an issue template pre-populated
with some helpful diagnostic information.
* Added `userIdentity` and `systemUsername`, used to retrieve information about
the current user.
# rstudioapi 0.10
* Added the parameters `echo` and `focus` to `sendToConsole()`.
# rstudioapi 0.9
* Added functions for displaying jobs in RStudio's Jobs pane: `jobAdd()`, `jobRemove()`, etc.
* Added `translateLocalUrl()`, for translating localhost URLs to externally addressable ones on RStudio Server.
# rstudioapi 0.8
* Added functions for installing + using build tools:
`buildToolsCheck()`, `buildToolsInstall()`, `buildToolsExec()`
* Added functions for installing + using themes: `addTheme()`, `applyTheme()`,
`convertTheme()`, `getThemes()`, `getThemeInfo()`.
* Added `previewSql()`, for previewing output from executing a SQL query.
* Added `askForSecret()`, for prompting the user to enter a password or otherwise privileged information.
* Fixed an issue where `getActiveProject()` failed for non-ASCII paths. (#86)
# rstudioapi 0.7
* Added methods for prompting the user for file paths: `selectFile()`,
`selectDirectory()`.
* `askForPassword()` gains a default prompt (#41)
* Add `createProjectTemplate()` function
* Add `setPersistentValue()` / `getPersistentValue()` functions
* Add methods for interacting with Terminal tab:
`terminalActivate()`, `terminalClear()`, `terminalCreate()`, `terminalList()`,
`terminalBuffer()`, `terminalContext()`, `terminalVisible()`, `terminalBusy()`,
`terminalRunning()`, `terminalKill()`, `terminalSend()`, `terminalExecute()`,
and `terminalExitCode()`.
# rstudioapi 0.6
* Add sendToConsole function
* Add APIs for setting cursor position in document
# rstudioapi 0.5
* Add askForPassword function
* Add getActiveProject function
# rstudioapi 0.4
* Add API methods for interacting with a document open in RStudio: 'insertText()', 'modifyRange()' and 'getActiveDocumentContext()'.
# rstudioapi 0.3
* Add stub and documentation for sourceMarker function
# rstudioapi 0.2
* Compatibility with calling conventions for RStudio v0.99
* Stubs and documentation for versionInfo, previewRd, and viewer functions
# rstudioapi 0.1
Initial release to CRAN
rstudioapi/MD5 0000644 0001762 0000144 00000017452 13753327012 012761 0 ustar ligges users 4435cf65bf2b2c0114dbc99bdd7f3afb *DESCRIPTION
2491c4039e00be047cce99c452d3fd00 *LICENSE
0701501404c5c98ae0aa61ff0e37f1c5 *NAMESPACE
49ffa7f155a8215e22ae17e238314db1 *NEWS.md
f83576d37d5baddf71282939bce78f17 *R/bug-report.R
55173aca0882afbde1f0255d458bc4d1 *R/build-tools.R
5cc2cf64daa77f5d691a99cd5b297a91 *R/chunk.R
a2e9c4610c9d0d2e1a12e0c3ccc3fdf6 *R/code.R
85232f0d1f5aad32492847c5aa62bec5 *R/commands.R
27164947d053ce9107a674f564214180 *R/dependencies.R
82b99789003eb6ee2cf63dd94ed60f8c *R/dialogs.R
d3b7b1360801c205e6217adc8c8a5d3d *R/dictionaries.R
eb3c61db4200b2cd3d9cbf1307a4d1c7 *R/document-api.R
9dea1a8223091d62ccf7e3e774930eef *R/document-methods.R
bb6fd76d24b0f8b1c1f3e51de1e0ad49 *R/files-pane.R
eaf30ede3ad997cd4ad6e2aafb1b3d8e *R/highlight-ui.R
9de094f78ed196cf6dd0c0acb4aac4dd *R/jobs.R
69cdf02cacc0f6da18f29767f53aa539 *R/launcher-functions.R
a6b30acdc0bba6b16108033aee980ba6 *R/launcher.R
627c1993928ca912b11e33ee38fd7e15 *R/misc.R
3eeb5a0bd99758ad2f95af5f3650ad7b *R/prefs.R
02b10f6b86c32d5ef51bb837215f3cff *R/preview.R
9f2c65786f2e301385d8997060cd0e96 *R/remote.R
a54fcf01b4c73ce8bd5eea720485212b *R/selections.R
4064932c41e853730ce258ab7b38ae1c *R/stubs.R
1754d5d801354fcae0a9917e81d9bcdb *R/templates.R
bb4d4636f7dc73b11c63fb42fa7b4070 *R/terminal.R
ca8879b4099009e74eeb258890b2f3e7 *R/themes.R
803dd0ced443c56b0a3457007b52f89c *R/tutorial.R
a38d11d8201877bb6bbcaa24cb4fc80a *R/urls.R
8117d88e3d261880f23701726df1bc2b *R/user.R
1219c514fd50cdd826fe436c25d006e0 *R/utils.R
64597cb769ca0191f87adbf1191abd80 *build/vignette.rds
bd533fab67709a0c98a10338d39ee679 *inst/doc/dialogs.R
01f5841a3d3d9249f0b6509697189d5e *inst/doc/dialogs.Rmd
0fbf58eb59dee86ed132375e3c975e20 *inst/doc/dialogs.html
462250065182d40e516e44efddc7dc36 *inst/doc/document-manipulation.R
0a81e2595fc31915b1c6ec77cdbc8fe2 *inst/doc/document-manipulation.Rmd
1fb54279602e31f480314a10125beda8 *inst/doc/document-manipulation.html
4eb7f4d912f65f74a951b41ca1ab859d *inst/doc/introduction.Rmd
48b1f3a475c9b1dfc2c5f489297c327e *inst/doc/introduction.html
0ed95f3ce75ac90c6e6948d13c746b8e *inst/doc/projects.R
b3f763976fc12d073ef5f4cf610589db *inst/doc/projects.Rmd
dc3463b9aa0ab94d442f2a5717e8d9ef *inst/doc/projects.html
26da07b8e9e5d3e5986c75a8444ca0ca *inst/doc/r-session.R
3d38c4910650dbcb09439a1a17f585ca *inst/doc/r-session.Rmd
4f3336d5c992374c7e99538898585186 *inst/doc/r-session.html
41a4c559971972d6d9dcd58bfff08ae1 *inst/doc/terminal.R
2ba016fe1aab495668b3409636332aa3 *inst/doc/terminal.Rmd
448d7a5328824d039cf4e4f8395801db *inst/doc/terminal.html
0c8f00021a5ff52f04c03d8c6c76ca4d *inst/doc/visual-mode.R
8c43fae2c9ebca97036dc318a69f5487 *inst/doc/visual-mode.Rmd
1de42876b82ad58341b4490862d01890 *inst/doc/visual-mode.html
5ce8c65f8c31f69388f565ac5489d6fc *inst/resources/bug-report.md
0a3f0746185f36f8b4b59b4b890aeb11 *man/addTheme.Rd
a1cf55bd498336bae467889235fc3a69 *man/applyTheme.Rd
0c5d5807b395945bf929c9ef0b268ab6 *man/askForPassword.Rd
0b11c9c827e05e76ea22f49e75ea6405 *man/askForSecret.Rd
1b13b1ee4795ab97ac1e72447d6cc68b *man/bugReport.Rd
131ed40ec1f2c247de1daca8d61987da *man/build-tools.Rd
b52171c4f9e3ac9be7b52ba50541df9f *man/callFun.Rd
5063f553ec36db9e4e7c212f970e26f9 *man/chunk-callbacks.Rd
c139c32e6b8efdb443f8e0839b1b3a86 *man/convertTheme.Rd
38232bcd1f0d79a40684c267996d3cd0 *man/createProjectTemplate.Rd
21c99823cf7f079015c90598ec9dd0fa *man/dictionaries.Rd
5a815a59461d3949444a7f93901a0f0e *man/document_position.Rd
00e6a39555080c8109179127ee4de883 *man/document_range.Rd
59be05a6ce4115f9bdcef2d4006b1841 *man/executeCommand.Rd
4c3047e389c08697fe6c69c223dffeb1 *man/figures/logo.png
29380004b7af0ba5beb88a78a6632b81 *man/figures/logo.svg
e9e7e9a47bbc314ae4ab132674cab164 *man/file-dialogs.Rd
8c12da5457e21beaeaba00367ccb6a73 *man/filesPaneNavigate.Rd
dad63d947fd2cda17bd71a2723cb9bfc *man/getActiveProject.Rd
6c474fd4ff22c8f5ad1ad8c38dc342ae *man/getRStudioPackageDependencies.Rd
93d5c67ef034efb66ac76139ce7401c7 *man/getThemeInfo.Rd
f1ac035f86ed13483176411fde218705 *man/getThemes.Rd
c3538f6f2ad3d094ad6e02a5db3cc58f *man/getVersion.Rd
a2ac388d2c095a326862e5e2953412d2 *man/hasColorConsole.Rd
327c7314797942325c0c6ec1f29a83f0 *man/hasFun.Rd
65db3a95d2cecaed260b6fdcc084f377 *man/highlightUi.Rd
591e5b6971859f03464ab8ebe23019ad *man/isAvailable.Rd
f687486138d81bcd236cda47b9d70b08 *man/jobAdd.Rd
19adb867e1a6367f0125fc366b110aae *man/jobAddOutput.Rd
659d3266264bdbb55c867bfc18322707 *man/jobAddProgress.Rd
acf5a9b7b4849b59324d30b8289ba872 *man/jobRemove.Rd
8303be68eae7fb01a376541f787f897b *man/jobRunScript.Rd
2a2c85956210d6fdcb363b817d2dd4e5 *man/jobSetProgress.Rd
eff74857462ce30a65ef1bae3812e8da *man/jobSetState.Rd
e2a37ce88f219b6236c666e3678398a6 *man/jobSetStatus.Rd
b592071a8f1e3592bf32b7ea78b17d91 *man/launcher.Rd
526980fb42eef1f603b6932b4e598efd *man/launcherConfig.Rd
908ea23dab86f8130ba025c00147bd74 *man/launcherContainer.Rd
6c584fbee9c32f076d3f69c84dba1a3d *man/launcherControlJob.Rd
0f7079f75e81c404d4a205f8fdd89c87 *man/launcherGetJob.Rd
4a59621a2a710590b0d6805ec2b4b9cc *man/launcherHostMount.Rd
193e3657ce7b594b49353a950294dee8 *man/launcherNfsMount.Rd
1e962fde1d295a069cd56aa999bcbbbb *man/launcherPlacementConstraint.Rd
1409a7018105724d7c5ea40ddbf3dbc7 *man/launcherResourceLimit.Rd
88a886779a0730773d9d1615f8916a1c *man/launcherSubmitJob.Rd
f6fe41e28d49972a8689abd3b6d266df *man/launcherSubmitR.Rd
b9b06310fa01f5465f0d0450aa4fd392 *man/navigateToFile.Rd
3258087faf4f8e4713163d463483d625 *man/persistent-values.Rd
83b0ac45962984e167e57f550a05914d *man/previewRd.Rd
f808e3d0bd2774e2e84f27d7d1df7947 *man/previewSql.Rd
81bb2b1792943c221022684a0d482a8e *man/primary_selection.Rd
a5bc70d553da36bda84230472a0bd43e *man/projects.Rd
e1eb52e247799e43f4f46bd19651f1e3 *man/readPreference.Rd
1a91ef4c25575988746ced151f7edd76 *man/readRStudioPreference.Rd
f6fdc4654fd43e7e8051b137a57b9920 *man/removeTheme.Rd
a9b87af21687d2c074e62ce9325cfa04 *man/restartSession.Rd
730654d623b4b647029db5a4584d7230 *man/rstudio-documents.Rd
45f4ac0bee6c6b5b45094fbaf38fffc8 *man/rstudio-editors.Rd
b321e07723b3bcee950ed93297deea6a *man/savePlotAsImage.Rd
5342b3344bf56f8a7b586e36e9f4a292 *man/selections.Rd
3541b88b833f82be1147f9ed2e3dc8fa *man/sendToConsole.Rd
17de61f21f828407d113e4eb2e2ed8ee *man/showDialog.Rd
c710cead266371aead9cdb2ac12a764a *man/showPrompt.Rd
a150ce038873c8b67a6b3d65334bd43a *man/showQuestion.Rd
a5211d26465d0b023b4d24feeaebbc3b *man/sourceMarkers.Rd
c64d52cabb74dc47ddb6f03a7aa42dd7 *man/systemUsername.Rd
077c236bf337d759cbff405db92a841b *man/terminalActivate.Rd
76226dfbe091e73e47b7ff20f1ca9815 *man/terminalBuffer.Rd
b2fee934c9f1be20884d889b92226a43 *man/terminalBusy.Rd
c3d6b4a1e7e44fa07c07417d8583403f *man/terminalClear.Rd
db62c2064ec1b1f87ff022e3d3005932 *man/terminalContext.Rd
a1b19ac4cf975c4710d40b60f45e53e5 *man/terminalCreate.Rd
de09a551862aadfe79c9226a58caba34 *man/terminalExecute.Rd
75fb4425bee91608daa72303d71f3114 *man/terminalExitCode.Rd
85ffc689ebfb70c4e343ec82e6bd42be *man/terminalKill.Rd
45eb66e8a5b6b04334cdc4eb18231108 *man/terminalList.Rd
1c7a96689f86d954c5267ee4e01c3ce6 *man/terminalRunning.Rd
bd98a27c50935b0055c381c58114fe12 *man/terminalSend.Rd
c5ac2c4c3e59f027356790bcdd059a6b *man/terminalVisible.Rd
06c3a15a76e214d091b9238921f62419 *man/translateLocalUrl.Rd
0049081fc806fc15ea5fa7c64330ed5f *man/updateDialog.Rd
838bfa3b11a19467a2f607749c532105 *man/userIdentity.Rd
461afa8dc80205d5bdbe5447f219f725 *man/versionInfo.Rd
3405bebd5a68ce3fe2d7cbb48e655199 *man/viewer.Rd
54f1ec85c00d8a6421e5d6fc1cf6f810 *man/writePreference.Rd
8a7bf3eef91e035537cc9be4ed0029ac *man/writeRStudioPreference.Rd
01f5841a3d3d9249f0b6509697189d5e *vignettes/dialogs.Rmd
0a81e2595fc31915b1c6ec77cdbc8fe2 *vignettes/document-manipulation.Rmd
4eb7f4d912f65f74a951b41ca1ab859d *vignettes/introduction.Rmd
b3f763976fc12d073ef5f4cf610589db *vignettes/projects.Rmd
3d38c4910650dbcb09439a1a17f585ca *vignettes/r-session.Rmd
2ba016fe1aab495668b3409636332aa3 *vignettes/terminal.Rmd
8c43fae2c9ebca97036dc318a69f5487 *vignettes/visual-mode.Rmd
rstudioapi/inst/ 0000755 0001762 0000144 00000000000 13753072406 013421 5 ustar ligges users rstudioapi/inst/doc/ 0000755 0001762 0000144 00000000000 13753072406 014166 5 ustar ligges users rstudioapi/inst/doc/terminal.Rmd 0000644 0001762 0000144 00000011165 13535525640 016452 0 ustar ligges users ---
title: "Interacting with Terminals"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Interacting with Terminals}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```
The `rstudioapi` package provides a collection of functions that can be used to interact with the [RStudio terminal tab](https://support.rstudio.com/hc/en-us/articles/115010737148-Using-the-RStudio-Terminal).
There are two primary approaches to using these functions.
1. Use `terminalExecute()` to run a specific process with the output shown in a new terminal buffer, without blocking the current R session.
2. Create, query, and manipulate interactive terminals. This might be used to develop custom terminal behavior via an [RStudio addin](https://rstudio.github.io/rstudioaddins/).
## TerminalExecute Scenario
```{r}
# Start a command with results displayed in a terminal buffer
termId <- rstudioapi::terminalExecute("ping rstudio.com")
# If viewing the result in the terminal buffer is sufficient,
# then no need to do anything else. The command will continue
# running and displaying its results without blocking the R session.
# To obtain the results programmatically, wait for it to finish.
while (is.null(rstudioapi::terminalExitCode(termId))) {
Sys.sleep(0.1)
}
result <- rstudioapi::terminalBuffer(termId)
# Delete the buffer and close the session in the IDE
rstudioapi::terminalKill(termId)
```
## Interative Terminal Scenario
Several concepts are important to understand to make full use of these functions.
### Terminal Identifier
Each terminal session has a unique **terminal identifier**, a required argument for most of the functions. A terminal identifier is generated and returned when a terminal is created via `terminalCreate()` or `terminalExecute()`, and identifiers of existing terminals can be obtained via `terminalList()` or `terminalVisible()`.
### Terminal Session
A **terminal session** is an instance of a terminal that can be displayed in the RStudio terminal tab. A terminal session consists of:
* a unique terminal identifier
* a unique caption shown in the RStudio terminal dropdown (e.g. "Terminal 1")
* a shell process (e.g. bash) running as a child process of the R session
* zero or more processes running as children of the shell (e.g. commands)
* an xterm-compatible terminal emulator in the terminal tab
* a buffer of output shown in the terminal emulator (can be cleared via `terminalClear()`)
### Busy Terminal
A terminal session with child processes running (excluding the shell), is considered **busy** and this is reflected in the IDE UI and can be queried with `terminalBusy()`.
### Terminal States
In the most common situation, a terminal session has all the above features; however, it is possible for terminals to be in other states.
**No shell process or child processes**: This happens if the associated R session has been closed (or suspended in the case of an inactive RStudio Server session).
The `terminalRunning()` function returns `TRUE` if a terminal is in this state.
If a terminal is not running, it can be started via interacting with it in the RStudio IDE, or via `terminalActivate()`.
```{r}
# start an interactive terminal using the shell selected in
# RStudio global options
myTerm <- rstudioapi::terminalCreate()
# ....
# sometime later
# ....
if (!rstudioapi::terminalRunning(myTerm)) {
# start the terminal shell back up, but don't bring to front
rstudioapi::terminalActivate(myTerm, show = FALSE)
# wait for it to start
while (!rstudioapi::terminalRunning(myTerm)) {
Sys.sleep(0.1)
}
# send a new command
rstudioapi::terminalSend(myTerm, "echo Hello\n")
}
```
**Running but not loaded in the IDE**: On RStudio Server, the web browser can be closed but the R session and any associated terminal sessions keep running. If the web browser is reconnected, each terminal will be redisplayed in the IDE when it is selected. The `rstudioapi` functions may be used on a terminal in this state; for example, the buffer may still be fetched with `terminalBuffer()` even if the terminal isn't loaded in the IDE (so long as the R session is still alive).
**Terminated but still visible**: Normally the terminal emulator for a given terminal session will close when the shell exits. If the option **Close Terminal When Shell Exits** is turned off, then the terminal buffer will remain loaded in the RStudio IDE until closed by the user or `terminalKill()`. Terminals started with `terminalExecute()` will always remain loaded when they finish running. To test a terminal for this state, `terminalExitCode()` will return a non-NULL value.
rstudioapi/inst/doc/dialogs.R 0000644 0001762 0000144 00000002421 13753072404 015730 0 ustar ligges users ## ----setup, include=FALSE-----------------------------------------------------
knitr::opts_chunk$set(eval = FALSE)
## -----------------------------------------------------------------------------
# # request the path to an existing .csv file on disk
# path <- rstudioapi::selectFile(caption = "Select CSV File",
# filter = "CSV Files (*.csv)",
# existing = TRUE)
#
# # now, you could read the data using e.g. 'readr::read_csv()'
# data <- readr::read_csv(path)
#
# # request a file path (e.g. where you would like to save a new file)
# target <- rstudioapi::selectFile(caption = "Save File",
# label = "Save",
# existing = FALSE)
#
# # save data to the path provided by the user
# saveRDS(data, file = target)
## -----------------------------------------------------------------------------
# token <- rstudioapi::askForPassword(
# prompt = "Please provide your GitHub access token."
# )
## -----------------------------------------------------------------------------
# rstudioapi::showDialog(title = "Hello, world!",
# message = "You're awesome!",
# url = "http://www.example.com")
rstudioapi/inst/doc/r-session.R 0000644 0001762 0000144 00000001244 13753072405 016233 0 ustar ligges users ## ----setup, include=FALSE-----------------------------------------------------
knitr::opts_chunk$set(eval = FALSE)
## -----------------------------------------------------------------------------
# # restart R, then run some code after
# rstudioapi::restartSession(command = "print('Welcome back!')")
#
# # send some code to the console and execute it immediately
# rstudioapi::sendToConsole("1 + 1", execute = TRUE)
## -----------------------------------------------------------------------------
# setHook("rstudio.sessionInit", function(newSession) {
# if (newSession)
# message("Welcome to RStudio ", rstudioapi::getVersion())
# }, action = "append")
rstudioapi/inst/doc/r-session.Rmd 0000644 0001762 0000144 00000002645 13535525640 016564 0 ustar ligges users ---
title: "Interacting with the R Session"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Interact with the R Session}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```
## Session Interaction
The `rstudioapi` package allows you to interact with the running R session in a couple useful ways: you can send code to the R console, or restart the R session.
```{r}
# restart R, then run some code after
rstudioapi::restartSession(command = "print('Welcome back!')")
# send some code to the console and execute it immediately
rstudioapi::sendToConsole("1 + 1", execute = TRUE)
```
## Running at Startup
Typically, code that you want to run at the start of an R session is placed into an `.Rprofile` file (see [Initialization at the Start of a Session](https://stat.ethz.ch/R-manual/R-devel/library/base/html/Startup.html) for details). However, RStudio's API hooks are not available until RStudio has fully started up, so most `rstudioapi` methods will not work inside `.Rprofile`.
If you want to invoke `rstudioapi` methods on session startup, use the `rstudio.sessionInit` hook. For example, to print the RStudio version to the R console when the session begins:
```{r}
setHook("rstudio.sessionInit", function(newSession) {
if (newSession)
message("Welcome to RStudio ", rstudioapi::getVersion())
}, action = "append")
```
rstudioapi/inst/doc/terminal.R 0000644 0001762 0000144 00000002672 13753072405 016132 0 ustar ligges users ## ----setup, include=FALSE-----------------------------------------------------
knitr::opts_chunk$set(eval = FALSE)
## -----------------------------------------------------------------------------
# # Start a command with results displayed in a terminal buffer
# termId <- rstudioapi::terminalExecute("ping rstudio.com")
#
# # If viewing the result in the terminal buffer is sufficient,
# # then no need to do anything else. The command will continue
# # running and displaying its results without blocking the R session.
#
# # To obtain the results programmatically, wait for it to finish.
# while (is.null(rstudioapi::terminalExitCode(termId))) {
# Sys.sleep(0.1)
# }
#
# result <- rstudioapi::terminalBuffer(termId)
#
# # Delete the buffer and close the session in the IDE
# rstudioapi::terminalKill(termId)
## -----------------------------------------------------------------------------
# # start an interactive terminal using the shell selected in
# # RStudio global options
# myTerm <- rstudioapi::terminalCreate()
#
# # ....
# # sometime later
# # ....
# if (!rstudioapi::terminalRunning(myTerm)) {
# # start the terminal shell back up, but don't bring to front
# rstudioapi::terminalActivate(myTerm, show = FALSE)
#
# # wait for it to start
# while (!rstudioapi::terminalRunning(myTerm)) {
# Sys.sleep(0.1)
# }
#
# # send a new command
# rstudioapi::terminalSend(myTerm, "echo Hello\n")
# }
rstudioapi/inst/doc/document-manipulation.html 0000644 0001762 0000144 00000037571 13753072405 021404 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 insertedfmt <-"# 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 rowrange <- 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 idcontext <- rstudioapi::getConsoleEditorContext()id <- context$id# send some R code to the consolerstudioapi::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# documentrstudioapi::setCursorPosition(Inf)# select the first 10 even lines in the documentranges <-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.
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 diskpath <- 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.
Users can create and open RStudio projects using the rstudioapi package.
# open a project in another directoryrstudioapi::openProject("~/projects/t-sne-gene-expression-2017")# re-open the current projectrstudioapi::openProject()# initialize an RStudio project (without opening it)rstudioapi::initializeProject("~/scratch/testbed")
rstudioapi/inst/doc/dialogs.Rmd 0000644 0001762 0000144 00000003166 13535525640 016263 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 13535525640 017350 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/projects.R 0000644 0001762 0000144 00000000751 13753072405 016144 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/visual-mode.html 0000644 0001762 0000144 00000032373 13753072406 017311 0 ustar ligges users
Interfacing with RStudio in Visual Mode
Interfacing with RStudio in Visual Mode
library(rstudioapi)
RStudio v1.4 includes a new visual editing mode, which provides a WYSIWYM-style editing interface for R Markdown documents. This vignette describes how rstudioapi can be used to interface with the RStudio visual mode editor.
Most of the pre-existing rstudioapi functions used for interacting with a document (e.g. rstudioapi::getSourceEditorContext()) consume and / or produce objects which describe the position of the current selection in terms of row + column offsets into the document. Unfortunately, this abstraction does not neatly map into visual editing mode, as there is no notion of a “global” cursor position – rather, a cursor might be placed into a particular cell, and could have an offset somewhere into that cell.
If you are an RStudio Addin author, then you may want to ensure your addins are visual-mode-aware, so that they can function regardless of whether the user has enabled visual mode. To that end, we’ve introduced a small set of functions, which are more narrow in scope but can function in both source and visual mode:
rstudioapi::documentId(): Retrieve the ID associated with the document currently open and being edited in the RStudio IDE.
rstudioapi::documentPath(): Retrieve the path on disk for a file currently open in the RStudio IDE.
rstudioapi::selectionGet(): Get the contents of the user’s selection.
rstudioapi::selectionSet(): Set the contents of the user’s selection.
In addition, the rstudioapi::insertText() function will function in both source and visual mode, as long as only the text argument is supplied.
Using this, you can build addins that modify the user’s selected text. For example, a function that uses rstudioapi to reformat the user’s current selection might look like this:
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/visual-mode.R 0000644 0001762 0000144 00000001112 13753072406 016531 0 ustar ligges users ## ---- include = FALSE---------------------------------------------------------
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
## ----setup--------------------------------------------------------------------
library(rstudioapi)
## ----eval=FALSE---------------------------------------------------------------
# reformat <- function() {
# id <- rstudioapi::documentId(allowConsole = TRUE)
# selection <- rstudioapi::selectionGet(id = id)
# formatted <- styler::style_text(text = selection$value)
# rstudioapi::selectionSet(value = formatted, id = id)
# }
rstudioapi/inst/doc/visual-mode.Rmd 0000644 0001762 0000144 00000004746 13752324312 017065 0 ustar ligges users ---
title: "Interfacing with RStudio in Visual Mode"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Interfacing with RStudio in Visual Mode}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```
```{r setup}
library(rstudioapi)
```
RStudio v1.4 includes a new [visual editing mode](https://rstudio.github.io/visual-markdown-editing/#/), which provides a [WYSIWYM](https://en.wikipedia.org/wiki/WYSIWYM)-style editing interface for R Markdown documents. This vignette describes how `rstudioapi` can be used to interface with the RStudio visual mode editor.
Most of the pre-existing `rstudioapi` functions used for interacting with a document (e.g. `rstudioapi::getSourceEditorContext()`) consume and / or produce objects which describe the position of the current selection in terms of row + column offsets into the document. Unfortunately, this abstraction does not neatly map into visual editing mode, as there is no notion of a "global" cursor position -- rather, a cursor might be placed into a particular cell, and could have an offset somewhere into that cell.
If you are an [RStudio Addin](https://rstudio.github.io/rstudioaddins/) author, then you may want to ensure your addins are visual-mode-aware, so that they can function regardless of whether the user has enabled visual mode. To that end, we've introduced a small set of functions, which are more narrow in scope but can function in both source and visual mode:
- `rstudioapi::documentId()`: Retrieve the ID associated with the document currently open and being edited in the RStudio IDE.
- `rstudioapi::documentPath()`: Retrieve the path on disk for a file currently open in the RStudio IDE.
- `rstudioapi::selectionGet()`: Get the contents of the user's selection.
- `rstudioapi::selectionSet()`: Set the contents of the user's selection.
In addition, the `rstudioapi::insertText()` function will function in both source and visual mode, as long as only the `text` argument is supplied.
Using this, you can build addins that modify the user's selected text. For example, a function that uses `rstudioapi` to reformat the user's current selection might look like this:
```{r eval=FALSE}
reformat <- function() {
id <- rstudioapi::documentId(allowConsole = TRUE)
selection <- rstudioapi::selectionGet(id = id)
formatted <- styler::style_text(text = selection$value)
rstudioapi::selectionSet(value = formatted, id = id)
}
```
rstudioapi/inst/doc/terminal.html 0000644 0001762 0000144 00000045722 13753072406 016701 0 ustar ligges users
Interacting with Terminals
Interacting with Terminals
The rstudioapi package provides a collection of functions that can be used to interact with the RStudio terminal tab.
There are two primary approaches to using these functions.
Use terminalExecute() to run a specific process with the output shown in a new terminal buffer, without blocking the current R session.
Create, query, and manipulate interactive terminals. This might be used to develop custom terminal behavior via an RStudio addin.
TerminalExecute Scenario
# Start a command with results displayed in a terminal buffertermId <- 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 IDErstudioapi::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 optionsmyTerm <- 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/r-session.html 0000644 0001762 0000144 00000030657 13753072405 017010 0 ustar ligges users
Interacting with the R Session
Interacting with the R Session
Session Interaction
The rstudioapi package allows you to interact with the running R session in a couple useful ways: you can send code to the R console, or restart the R session.
# restart R, then run some code afterrstudioapi::restartSession(command ="print('Welcome back!')")# send some code to the console and execute it immediatelyrstudioapi::sendToConsole("1 + 1", execute =TRUE)
Running at Startup
Typically, code that you want to run at the start of an R session is placed into an .Rprofile file (see Initialization at the Start of a Session for details). However, RStudio’s API hooks are not available until RStudio has fully started up, so most rstudioapi methods will not work inside .Rprofile.
If you want to invoke rstudioapi methods on session startup, use the rstudio.sessionInit hook. For example, to print the RStudio version to the R console when the session begins:
setHook("rstudio.sessionInit", function(newSession) {if (newSession)message("Welcome to RStudio ", rstudioapi::getVersion())}, action ="append")
rstudioapi/inst/doc/projects.Rmd 0000644 0001762 0000144 00000001202 13535525640 016457 0 ustar ligges users ---
title: "Interacting with RStudio Projects"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Interacting with RStudio Projects}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```
Users can create and open RStudio projects using the `rstudioapi` package.
```{r}
# open a project in another directory
rstudioapi::openProject("~/projects/t-sne-gene-expression-2017")
# re-open the current project
rstudioapi::openProject()
# initialize an RStudio project (without opening it)
rstudioapi::initializeProject("~/scratch/testbed")
```
rstudioapi/inst/doc/document-manipulation.Rmd 0000644 0001762 0000144 00000004074 13535525640 021154 0 ustar ligges users ---
title: "Document Manipulation"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Document Manipulation}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup}
knitr::opts_chunk$set(eval = FALSE)
```
The `rstudioapi` package provides a small family of functions that can be used to interact with documents open in an RStudio session. For example, the following code could be used to insert a 'last modified' comment at the start of a document:
```{r}
# construct the text to be inserted
fmt <- "# This document was last modified on %s.\n"
text <- sprintf(fmt, Sys.Date())
# specify a range where this text should be inserted; here,
# we use the first line; that is, the 'range' between the start
# of the first row, and the start of the second row
range <- rstudioapi::document_range(c(1, 0), c(2, 0))
rstudioapi::insertText(range, text)
```
By default, these APIs target the editor instance either currently focused by the user, or when no such editor is currently focused, the last focused editor. If you need to target a specific editor instance (for example, you want to write code that inserts text into the console), you can use `getConsoleEditorContext()` to get the `id` for the console editor:
```{r}
# get console editor id
context <- rstudioapi::getConsoleEditorContext()
id <- context$id
# send some R code to the console
rstudioapi::insertText(text = "print(1 + 1)", id = id)
# see also: `getActiveEditorContext()`, `getSourceEditorContext()`
```
You can also modify the cursor position through the use of the `setCursorPosition()` and `setSelectionRanges()` APIs.
```{r}
# put the cursor at the end of the document -- note that here,
# `Inf` is automatically truncated to the actual length of the
# document
rstudioapi::setCursorPosition(Inf)
# select the first 10 even lines in the document
ranges <- lapply(seq(2, by = 2, length.out = 10), function(start) {
rstudioapi::document_range(
c(start, 0),
c(start, Inf)
)
})
rstudioapi::setSelectionRanges(ranges)
```
See the `?"rstudio-documents"` help page for more details.
rstudioapi/inst/doc/document-manipulation.R 0000644 0001762 0000144 00000002723 13753072404 020627 0 ustar ligges users ## ----setup--------------------------------------------------------------------
knitr::opts_chunk$set(eval = FALSE)
## -----------------------------------------------------------------------------
# # construct the text to be inserted
# fmt <- "# This document was last modified on %s.\n"
# text <- sprintf(fmt, Sys.Date())
#
# # specify a range where this text should be inserted; here,
# # we use the first line; that is, the 'range' between the start
# # of the first row, and the start of the second row
# range <- rstudioapi::document_range(c(1, 0), c(2, 0))
# rstudioapi::insertText(range, text)
## -----------------------------------------------------------------------------
# # get console editor id
# context <- rstudioapi::getConsoleEditorContext()
# id <- context$id
#
# # send some R code to the console
# rstudioapi::insertText(text = "print(1 + 1)", id = id)
#
# # see also: `getActiveEditorContext()`, `getSourceEditorContext()`
## -----------------------------------------------------------------------------
# # put the cursor at the end of the document -- note that here,
# # `Inf` is automatically truncated to the actual length of the
# # document
# rstudioapi::setCursorPosition(Inf)
#
# # select the first 10 even lines in the document
# ranges <- lapply(seq(2, by = 2, length.out = 10), function(start) {
# rstudioapi::document_range(
# c(start, 0),
# c(start, Inf)
# )
# })
# rstudioapi::setSelectionRanges(ranges)
rstudioapi/inst/resources/ 0000755 0001762 0000144 00000000000 13535525640 015434 5 ustar ligges users rstudioapi/inst/resources/bug-report.md 0000644 0001762 0000144 00000001104 13535525640 020040 0 ustar ligges users
### System details
RStudio Edition : ${RSTUDIO_EDITION}
RStudio Version : ${RSTUDIO_VERSION}
OS Version : ${OS_VERSION}
R Version : ${R_VERSION}
### Steps to reproduce the problem
### Describe the problem in detail
### Describe the behavior you expected