| Title: | Friendly R Startup Configuration |
|---|---|
| Description: | Adds support for R startup configuration via '.Renviron.d' and '.Rprofile.d' directories in addition to '.Renviron' and '.Rprofile' files. This makes it possible to keep private / secret environment variables separate from other environment variables. It also makes it easier to share specific startup settings by simply copying a file to a directory. |
| Authors: | Henrik Bengtsson [aut, cre, cph] |
| Maintainer: | Henrik Bengtsson <[email protected]> |
| License: | LGPL (>= 2.1) |
| Version: | 0.20.0 |
| Built: | 2023-08-31 04:52:44 UTC |
| Source: | https://github.com/HenrikBengtsson/startup |
Check for and fix common mistakes in ‘.Rprofile’ files.
check(all = FALSE, fix = TRUE, backup = TRUE, debug = FALSE)all |
Should all or only the first entry on the R startup search path be checked? |
fix |
If |
backup |
If |
debug |
If |
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.
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
current_script()A character string
Install and uninstall support for ‘.Renviron.d’ and ‘.Rprofile.d’ startup directories by appending / removing one line of code to the ‘~/.Rprofile’ file.
install(
path = "~",
backup = TRUE,
overwrite = FALSE,
make_dirs = TRUE,
quiet = FALSE
)
uninstall(path = "~", backup = TRUE, quiet = FALSE)path |
The path where to create / update the ‘.Rprofile’ file. |
backup |
If |
overwrite |
If the R startup file already exist, then |
make_dirs |
If |
quiet |
If |
The pathname of the R startup file modified.
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 whether running R via Emacs Spekas Statistics (ESS) or not
is_ess()A logical
Checks if running R in Microsoft R Open
is_microsoftr()A logical
Checks if running pqR (A Pretty Quick Version of R)
is_pqr()A logical
pqR - a pretty quick version of R, http://www.pqr-project.org/
GitHub repository for 'pqR' https://github.com/radfordneal/pqR
Checks whether running R via radian (formerly known as rtichoke and rice) or not
is_radian()A logical
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
is_rstudio_console()A logical
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
Jonathan McPherson (RStudio), Programmatically detect RStudio Terminal vs RStudio Console?, RStudio Community - RStudio IDE, 2018-01-10, https://community.rstudio.com/t/programmatically-detect-rstudio-terminal-vs-rstudio-console/4107
Checks whether running R on Windows using Wine or not
is_wine()A logical
Wine Developer FAQ, How can I detect Wine?, https://wiki.winehq.org/Developer_FAQ#How_can_I_detect_Wine.3F
Jeff Zaroyko, Detecting Wine, Wine Devel mailing list, 2008-09-29, https://www.winehq.org/pipermail/wine-devel/2008-September/069387.html
Register functions to be evaluated at the beginning or end of the R session
on_session_enter(fcn = NULL, append = TRUE, replace = FALSE)
on_session_exit(fcn = NULL, append = TRUE, replace = FALSE)fcn |
A function or an R expression. The function must accept zero or more arguments (currently not used). If an expression, it will automatically we wrapped up in an anonymous function. |
append |
If TRUE (default), the function will be evaluated after previously registered ones, otherwise prepended. |
replace |
if TRUE, the function replaces any previously registered ones, otherwise it will be added (default). |
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.
(invisible) the list of registered functions.
## 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)Initiates R using all files under ‘.Renviron.d/’ and / or ‘.Rprofile.d/’ directories (or in subdirectories thereof).
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,
dryrun = NA,
debug = dryrun
)sibling |
If |
all |
If |
unload |
If |
skip |
If |
dryrun |
If |
debug |
If |
paths |
(internal) character vector of directories. |
check |
If |
on_error |
Action taken when an error is detected when sourcing an Rprofile file. It is not possible to detect error in Renviron files; they are always ignored with a message that cannot be captured. |
keep |
Specify what information should remain after this function
complete. The default is to keep |
The above is done in addition the ‘.Renviron’ and ‘.Rprofile’ files that are supported by the built-in startup process of R.
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
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.
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.
## 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
reset_when_cache(
when = c("once", "hourly", "daily", "weekly", "fortnightly", "monthly")
)when |
(character vector) Specifies for which "when" frequencies the cache should be reset. The default is to reset all of them. |
(invisible) The pathnames of the "when" cache files removed.
Restarts R by quitting the current R session and launching a new one.
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
)status |
An integer specifying the exit code of the current R session. |
workdir |
The working directory where the new R session should
be launched from. If |
rcmd |
A character string specifying the command for launching R.
The default is the same as used to launch the current R session, i.e.
|
args |
A character vector specifying zero or more command-line
arguments to be appended to the system call of |
envvars |
A named character vector of environment variables to be set when calling R. |
as |
A character string specifying a predefined setups of |
quiet |
Should the restart be quiet or not?
If |
debug |
If |
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.
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.
## 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)Record R session information as options
startup_session_options(action = c("update", "overwrite", "erase"))action |
If |
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).
opts <- startup::startup_session_options()
optsBelow 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.
(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)
(logical)
Controls the default value of argument dryrun of startup().
(Default: FALSE)
(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 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)
(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".
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)
(logical)
Controls the default value of argument check of startup().
(Default: TRUE)
(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")
(logical)
Controls the default value of argument debug of startup().
(Default: FALSE)
(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())
(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)
Information on the current R session
sysinfo()A named list.
startup::sysinfo()Produce a warning
warn(..., call. = FALSE, immediate. = TRUE, domain = NULL)
..., domain
|
The message and optionally the domain used for translation. The ... arguments are passed to base::sprintf to create the message string. |
call. |
If base::TRUE, the call is included in the warning message, otherwise not. |
immediate. |
If base::TRUE, the warning is outputted immediately, otherwise not. |