Check for and fix common mistakes in .Rprofile

Description

Check for and fix common mistakes in ‘.Rprofile’ files.

Usage

check(all = FALSE, fix = TRUE, backup = TRUE, debug = FALSE)

Arguments

Value

Returns invisibly a character vector of files that were "fixed" (modified), if any. If no files needed to be fixed, or fix = TRUE, then an empty vector is returned.

References

1. R-devel thread 'Last line in .Rprofile must have newline (PR#4056)', 2003-09-03, https://stat.ethz.ch/pipermail/r-devel/2003-September/027457.html

Gets the pathname of the currently running startup script

Description

Gets the pathname of the currently running startup script

Usage

current_script()

Value

A character string

Locates the .Rprofile and .Renviron files used during the startup of R

Description

Locates the .Rprofile and .Renviron files used during the startup of R

Usage

find_rprofile(all = FALSE)

find_renviron(all = FALSE)

Functions

• find_rprofile(): Locates the ‘.Rprofile’ file used during R startup.

• find_renviron(): Locates the ‘.Renviron’ file used during R startup.

Locates the .Rprofile.d and .Renviron.d directories used during the startup of R

Description

Locates the .Rprofile.d and .Renviron.d directories used during the startup of R

Usage

find_rprofile_d(sibling = FALSE, all = FALSE)

find_renviron_d(sibling = FALSE, all = FALSE)

Functions

• find_rprofile_d(): Locates the ‘.Rprofile.d’ directory used during R startup.

• find_renviron_d(): Locates the ‘.Renviron.d’ directory used during R startup.

Install and uninstall support for .Renviron.d and .Rprofile.d startup directories

Description

Install and uninstall support for ‘.Renviron.d’ and ‘.Rprofile.d’ startup directories by appending / removing one line of code to the ‘~/.Rprofile’ file.

Usage

install(
  file = rprofile_user(),
  backup = TRUE,
  overwrite = FALSE,
  path = dirname(file),
  make_dirs = TRUE,
  quiet = FALSE
)

uninstall(file = rprofile_user(), backup = TRUE, quiet = FALSE)

Arguments

Value

The pathname of the R startup file modified.

Functions

• install(): injects a tryCatch(startup::startup(), ...) call to the ‘.Rprofile’ file, which is created if missing.

• uninstall(): Remove calls to startup::startup() and similar.

Checks if running R via Ark (An R Kernel)

Description

Checks if running R via Ark (An R Kernel)

Usage

is_ark()

Value

A logical

Checks whether startup debug is on or not

Description

Checks whether startup debug is on or not

Usage

is_debug_on()

Details

The debug mode is when startup() is called, either explicitly via argument debug or via environment variable R_STARTUP_DEBUG.

Value

Returns TRUE is debug is enabled and FALSE otherwise.

Check if running R via Emacs Speaks Statistics (ESS)

Description

Check if running R via Emacs Speaks Statistics (ESS)

Usage

is_ess()

Value

A logical

Checks if running R via Jupyter

Description

Checks if running R via Jupyter

Usage

is_jupyter()

Value

A logical

Check if running R via Microsoft R Open

Description

Check if running R via Microsoft R Open

Usage

is_microsoftr()

Value

A logical

Checks if running R via Positron

Description

Checks if running R via Positron

Usage

is_positron()

Value

A logical

Check if running a Pretty Quick Version of R (pqR)

Description

Check if running a Pretty Quick Version of R (pqR)

Usage

is_pqr()

Value

A logical

References

1. pqR - a pretty quick version of R, http://www.pqr-project.org/

2. GitHub repository for 'pqR' https://github.com/radfordneal/pqR

Check if running R via radian (formerly known as rtichoke and rice)

Description

Check if running R via radian (formerly known as rtichoke and rice)

Usage

is_radian()

Value

A logical

References

1. radian - A 21 century R console (previously known as rtichoke and rice), https://github.com/randy3k/radian

Checks if running R in RStudio Console or RStudio Terminal

Description

Checks if running R in RStudio Console or RStudio Terminal

Usage

is_rstudio_console()

Value

A logical

References

1. Kevin Ushey (RStudio), Check if R is running in RStudio, Stackoverflow, 2016-09-23, https://stackoverflow.com/questions/12389158/check-if-r-is-running-in-rstudio#comment66636507_35849779

2. Jonathan McPherson (RStudio), Programmatically detect RStudio Terminal vs RStudio Console?, RStudio Community - RStudio IDE, 2018-01-10, https://forum.posit.co/t/programmatically-detect-rstudio-terminal-vs-rstudio-console/4107

Checks if running R via Visual Studio Code (VSCode)

Description

Checks if running R via Visual Studio Code (VSCode)

Usage

is_vscode()

Value

A logical

Checks if running R via webR

Description

Checks if running R via webR

Usage

is_webr()

Value

A logical

References

1. webR - R in the Browser, https://docs.r-wasm.org/webr/latest/

Check if running R on Windows using Wine

Description

Check if running R on Windows using Wine

Usage

is_wine()

Value

A logical

References

1. Wine Developer FAQ, How can I detect Wine?, https://gitlab.winehq.org/wine/wine/-/wikis/Developer-FAQ#How_can_I_detect_Wine.3F

2. Jeff Zaroyko, Detecting Wine, Wine Devel mailing list, 2008-09-29, https://list.winehq.org/mailman3/hyperkitty/list/wine-devel@winehq.org/thread/TVQIRXMLJZYTTCMABIIVG7VIP46TQLLX/

Register functions to be evaluated at the beginning or end of the R session

Description

Register functions to be evaluated at the beginning or end of the R session

Usage

on_session_enter(fcn = NULL, append = TRUE, replace = FALSE)

on_session_exit(fcn = NULL, append = TRUE, replace = FALSE)

Arguments

Details

These functions register one or more functions to be called when the current R session begins or ends. The functions are evaluated in a local environment and without exception handlers, which means that if one produces an error, then none of the succeeding functions will be called.

To list currently registered functions, use fcns <- on_session_enter() or fcns <- on_session_exit(). To remove all registered functions, use on_session_enter(replace = TRUE) or on_session_exit(replace = TRUE).

The on_session_enter() function works by recording all fcn:s in an internal list which will be evaluated via a custom .First() function created in the global environment. Any other .First() function on the search path, including a pre-existing .First() function in the global environment, is called at the end after registered functions have been called.

The on_session_exit() function works by recording all fcn:s in an internal list which will be evaluated via a custom function that is called when the global environment is garbage collected, which happens at the very end of the R shutdown process. Contrary to a .Last() function, which is not be called if quit(runLast = FALSE) is used, functions registered via on_session_exit() are always processed. Registered on_session_exit() functions are called after quit() saves any workspace image to file (./.RData), and after any .Last() has been called.

Value

(invisible) the list of registered functions.

Examples

## Not run: 
## Summarize interactive session upon termination
if (interactive()) {
  startup::on_session_exit(local({
    t0 <- Sys.time()
    function(...) {
      dt <- difftime(Sys.time(), t0, units = "auto")
      msg <- c(
        "Session summary:",
        sprintf(" * R version: %s", getRversion()),
        sprintf(" * Process ID: %d", Sys.getpid()),
        sprintf(" * Wall time: %.2f %s", dt, attr(dt, "units"))
      )
      msg <- paste(msg, collapse = "\n")
      message(msg)
    }
  }))
}

## End(Not run)

Load .Renviron.d and .Rprofile.d directories during the R startup process

Description

Initiates R using all files under ‘.Renviron.d/’ and / or ‘.Rprofile.d/’ directories (or in subdirectories thereof).

Usage

renviron_d(
  sibling = FALSE,
  all = FALSE,
  unload = FALSE,
  skip = NA,
  dryrun = NA,
  debug = NA,
  paths = NULL
)

rprofile_d(
  sibling = FALSE,
  all = FALSE,
  check = NA,
  unload = FALSE,
  skip = NA,
  on_error = c("error", "warning", "immediate.warning", "message", "ignore"),
  dryrun = NA,
  debug = NA,
  paths = NULL
)

startup(
  sibling = FALSE,
  all = FALSE,
  on_error = c("error", "warning", "immediate.warning", "message", "ignore"),
  keep = c("options"),
  check = NA,
  unload = TRUE,
  skip = NA,
  encoding = getOption("encoding"),
  dryrun = NA,
  debug = dryrun
)

Arguments

Details

The above is done in addition the ‘.Renviron’ and ‘.Rprofile’ files that are supported by the built-in startup process of R.

Functions

• renviron_d(): Initiate using ‘.Renviron.d/’ files

• rprofile_d(): Initiate using ‘.Rprofile.d/’ files

• startup(): renviron_d() followed by rprofile_d() and then the package is unloaded

User-specific installation

In order for ‘.Rprofile.d’ and ‘.Renviron.d’ directories to be included during the R startup process, a user needs to add startup::startup() to ‘~/.Rprofile’. Adding this can also be done by calling install() once.

Site-wide installation

An alternative to having each user add startup::startup() in their own ‘~/.Rprofile’ file, is to add it to the site-wide ‘Rprofile.site’ file (see ?Startup). The advantage of such a site-wide installation, is that the users do not have to have a ‘.Rprofile’ file for ‘.Rprofile.d’ and ‘.Renviron.d’ directories to work. For this to work for all users automatically, the startup package should also be installed in the site-wide library.

Examples

## Not run: 
# The most common way to use the package is to add
# the following call to the ~/.Rprofile file.
startup::startup()

# To process ~/.Renviron.d/ files, and then any ./.Renviron.d/ files,
# followed by  ~/.Rprofile.d/ files, and then any ./.Rprofile.d/ files,
# add the following call to the ~/.Rprofile file.
startup::startup(all = TRUE)

# For finer control of on exactly what files are used
# functions renviron_d() and rprofile_d() are also available:

# Initiate first .Renviron.d/ found on search path
startup::renviron_d()

# Initiate all .Rprofile.d/ directories found on the startup search path
startup::rprofile_d(all = TRUE)

## End(Not run)

Reset all or parts of the "when" cache

Description

Reset all or parts of the "when" cache

Usage

reset_when_cache(
  when = c("once", "hourly", "daily", "weekly", "fortnightly", "monthly")
)

Arguments

Value

(invisible) The pathnames of the "when" cache files removed.

Restarts R

Description

Restarts R by quitting the current R session and launching a new one.

Usage

restart(
  status = 0L,
  workdir = NULL,
  rcmd = NULL,
  args = NULL,
  envvars = NULL,
  as = c("current", "specified", "R CMD build", "R CMD check", "R CMD INSTALL"),
  quiet = FALSE,
  debug = NA
)

Arguments

Predefined setups

Argument as may take the following values:

"current":

(Default) A setup that emulates the setup of the current R session as far as possible by relaunching R with the same command-line call (= base::commandArgs()).

"specified":

According to rcmd, args, and envvars.

"R CMD build":

A setup that emulates ⁠R CMD build⁠ as far as possible.

"R CMD check":

A setup that emulates ⁠R CMD check⁠ as far as possible, which happens to be identical to the "R CMD build" setup.

"R CMD INSTALL":

A setup that emulates ⁠R CMD INSTALL⁠ as far as possible.

If specified, command-line arguments in args and environment variables in envvars are appended accordingly.

Known limitations

It is not possible to restart an R session running in RGui on Microsoft Windows using this function.

It is not possible to restart an R session in the RStudio Console using this function. However, it does work when running R in the RStudio Terminal.

RStudio provides rstudioapi::restartSession() which will indeed restart the RStudio Console. However, it does not let you control how R is restarted, e.g. with what command-line options and what environment variables. Importantly, the new R session will have the same set of packages loaded as before, the same variables in the global environment, and so on.

Examples

## Not run: 
  ## Relaunch R with debugging of startup::startup() enabled
  startup::restart(envvars = c(R_STARTUP_DEBUG = TRUE))

  ## Relaunch R without loading user Rprofile files
  startup::restart(args = "--no-init-file")

  ## Mimic 'R CMD build' and 'R CMD check'
  startup::restart(as = "R CMD build")
  startup::restart(as = "R CMD check")
  ## ... which are both short for
  startup::restart(args = c("--no-restore"),
                   envvars = c(R_DEFAULT_PACKAGES="", LC_COLLATE="C"))

## End(Not run)

Options and environment variables used by the 'startup' package

Description

Below are environment variables and R options that are used by the startup package. The R_STARTUP_*** environment variables must be set before calling the startup::startup() function, that is, either (i) prior to launching R or (ii) in the ‘.Renviron’ file.

Controls whether startup is used or not

R_STARTUP_DISABLE / startup.disable:

(logical) If TRUE, startup::startup() is fully disable such that no ‘.Renviron.d/’ or ‘.Rprofile.d/’ files are processed. Note: Files ‘.Renviron’ and ‘.Rprofile’ are still processed because these are out of control of the startup package. (Default: FALSE)

R_STARTUP_DRYRUN / startup.dryrun:

(logical) Controls the default value of argument dryrun of startup(). (Default: FALSE)

Additional customization of the startup process

R_STARTUP_FILE / startup.file:

(R script as a character string) Optional R script that is parsed and evaluated after ‘.Renviron.d/’ and ‘.Rprofile.d/’ files, and R_STARTUP_INIT code, have been processed, e.g. ⁠R_STARTUP_FILE="setup.R" R --quiet⁠. (Default: not specified)

R_STARTUP_INIT / startup.init:

(R code as a character string) Optional R code that is parsed and evaluated after ‘.Renviron.d/’ and ‘.Rprofile.d/’ files, but before R_STARTUP_FILE code, have been processed e.g. ⁠R_STARTUP_INIT="message('Hello world')" R --quiet⁠. The specified string must be parsable by base::parse(). (Default: not specified)

R_STARTUP_RDATA / startup.rdata:

(comma-separated values) Controls whether an existing ‘./.RData’ file should be processed or not. If "remove", it will be skipped by automatically removing it. If "rename", it will be renamed to ‘./.RData.YYYYMMDD_hhmmss’ where the timestamp is the last time the file was modified. If "prompt", the user is prompted whether they want to load the file or rename it. In non-interactive session, "prompt" will fallback to loading the content (default). To fallback to renaming the file, use "prompt,rename". If "warn", a warning will be produced, but content is still loaded. Note that in contrast to R and ⁠R CMD BATCH file.R⁠, Rscript does not load ‘.RData’ files unless command-line option --restore is specified. (Default: not specified)

Controls what validation checks are performed at startup

R_STARTUP_CHECK / startup.check:

(logical) Controls the default value of argument check of startup(). (Default: TRUE)

R_STARTUP_CHECK_OPTIONS_IGNORE / startup.check.options.ignore:

(character vector or comma-separated character string) Names of R options that should not be validated at the end of the startup() process. (Default: "error")

Settings useful for debugging and prototyping

R_STARTUP_DEBUG / startup.debug:

(logical) Controls the default value of argument debug of startup(). (Default: FALSE)

R_STARTUP_DEBUG_FILE / startup.debug.file:

(character string or NULL) Controls where startup() debug messages are outputted. If set, it specifies the file where debug messages are written to. If file already exists, it is overwritten. Unless an absolute filename is given, the location of the file is relative to the working directory where R was started. If the filename comprise the string {{pid}}, it is replaced by the R process' process identifier (PID) per Sys.getpid(). If NULL or ⁠<message>⁠, then debug is outputted using the message() function. (Default: not specified)

startup.commandArgs:

(character vector) Overrides the command-line arguments that startup() uses, which can be useful to prototype and test alternative ways that R might be launched. (Default: base::commandArgs())

R_STARTUP_TIME / startup.time:

(POSIX timestamp; character string) Overrides the current timestamp, which can be useful to prototype and test functionalities that depend on the current time, e.g. inclusion and exclusion of files based on ⁠when=<periodicity>⁠ tags. The specified string must be parsable by base::as.POSIXct(). (Default: not specified)

Record R session information as options

Description

Record R session information as options

Usage

startup_session_options(action = c("update", "overwrite", "erase"))

Arguments

Value

Returns invisibly a named list of the options prefixed "startup.session.":

startup.session.startdir

(character) the working directory when the startup was first loaded. If startup::startup() is called at the very beginning of the ‘.Rprofile’ file, this is also the directory that the current R session was launched from.

startup.session.starttime

(POSIXct) the time when the startup was first loaded.

startup.session.id

(character) a unique ID for the current R session.

startup.session.dumpto

(character) a session-specific name that can be used for argument dumpto of dump.frames() (also for dumping to file).

Examples

opts <- startup::startup_session_options()
opts

Information on the current R session

Description

Information on the current R session

Usage

sysinfo()

Value

A named list.

Examples

startup::sysinfo()

Produce a warning

Description

Produce a warning

Usage

warn(..., call. = FALSE, immediate. = TRUE, domain = NULL)

Arguments