set.sys.path.Rdsys.path() is implemented to work with these functions and
packages:
debugSource() in ‘RStudio’
box::use()
plumber::plumb()
set.sys.path() can be used to implement sys.path() for any
other source()-like functions.
set.env.path() and set.src.path() can be used alongside
set.sys.path() to implement env.path() and
src.path(), thereby fully implementing
this.path(). Note that set.env.path() only makes sense
if the code is being modularized, see Examples.
unset.sys.path() will undo a call to set.sys.path(). You will
need to use this if you wish to call set.sys.path() multiple times
within a function.
set.sys.path.function() is a special variant of set.sys.path()
to be called within callr::r() on a function with an appropriate
srcref.
with_sys.path() is a convenient way to evaluate code within the
context of a file. Whereas set.sys.path() can only be used within a
function, with_sys.path() can only be used outside a function.
See ?sys.path(local = TRUE) which returns the path of the
executing script, confining the search to the local environment in which
set.sys.path() was called.
wrap.source() should not be used, save for one specific use-case. See
details.
set.sys.path(file,
path.only = FALSE,
character.only = path.only,
file.only = path.only,
conv2utf8 = FALSE,
allow.blank.string = FALSE,
allow.clipboard = !file.only,
allow.stdin = !file.only,
allow.url = !file.only,
allow.file.uri = !path.only,
allow.unz = !path.only,
allow.pipe = !file.only,
allow.terminal = !file.only,
allow.textConnection = !file.only,
allow.rawConnection = !file.only,
allow.sockconn = !file.only,
allow.servsockconn = !file.only,
allow.customConnection = !file.only,
ignore.all = FALSE,
ignore.blank.string = ignore.all,
ignore.clipboard = ignore.all,
ignore.stdin = ignore.all,
ignore.url = ignore.all,
ignore.file.uri = ignore.all,
Function = NULL, ofile, delayed = FALSE)
set.env.path(envir, matchThisEnv = getOption("topLevelEnvironment"))
set.src.path(srcfile)
unset.sys.path()
set.sys.path.function(fun)
with_sys.path(file, expr, ...)
wrap.source(expr,
path.only = FALSE,
character.only = path.only,
file.only = path.only,
conv2utf8 = FALSE,
allow.blank.string = FALSE,
allow.clipboard = !file.only,
allow.stdin = !file.only,
allow.url = !file.only,
allow.file.uri = !path.only,
allow.unz = !path.only,
allow.pipe = !file.only,
allow.terminal = !file.only,
allow.textConnection = !file.only,
allow.rawConnection = !file.only,
allow.sockconn = !file.only,
allow.servsockconn = !file.only,
allow.customConnection = !file.only,
ignore.all = FALSE,
ignore.blank.string = ignore.all,
ignore.clipboard = ignore.all,
ignore.stdin = ignore.all,
ignore.url = ignore.all,
ignore.file.uri = ignore.all)for with_sys.path(), an expression to evaluate within the
context of a file.
for wrap.source(), an (unevaluated) call to a source()-like
function.
a
connection or a
character string giving the pathname of the file or URL to read from.
must file be an existing path? This implies
character.only and file.only are TRUE and implies
allow.file.uri and allow.unz are FALSE, though these
can be manually changed.
must file be a character string?
must file refer to an existing file?
if file is a character string, should it be converted
to UTF-8?
may file be a blank string, i.e.
""?
may file be "clipboard" or a clipboard
connection?
may file be "stdin"? Note that
"stdin" refers to the C-level ‘standard input’ of the
process, differing from stdin() which
refers to the R-level ‘standard input’.
may file be a URL pathname or a connection of class
"url-libcurl" / / "url-wininet"?
may file be a file:// URL?
may
file be a connection of class
"unz"
/ / "pipe" / / "terminal" / / "textConnection" / /
"rawConnection" / / "sockconn" / / "servsockconn"?
may file be a custom connection?
ignore the special meaning of these types of strings, treating it as a path instead?
character vector of length 1 or
2; the name of the function and package in which
set.sys.path() is called.
a
connection or a
character string specifying the original file argument. This overwrites the
value returned by sys.path(original = TRUE).
TRUE or FALSE; should the
normalizing of
the path be delayed? Mostly for use with make_fix_funs() and
similar.
arguments passed to
topenv() to determine the top level
environment in which to assign an associated path.
source file in which to assign a pathname.
function with a srcref.
further arguments passed to set.sys.path().
set.sys.path() should be added to the body of your source()-like
function before reading / / evaluating the expressions.
wrap.source(), unlike set.sys.path(), does not accept an
argument file. Instead, an attempt is made to extract the file from
expr, after which expr is evaluated. It is assumed that the
file is the first argument of the function, as is the case with most
source()-like functions. The function of the call is evaluated, its
formals() are retrieved,
and then the arguments of expr are searched for a name matching the
name of the first formal argument. If a match cannot be found by name, the
first unnamed argument is taken instead. If no such argument exists, the file
is assumed missing.
wrap.source() does non-standard evaluation and does some guess work to
determine the file. As such, it is less desirable than set.sys.path()
when the option is available. I can think of exactly one scenario in which
wrap.source() might be preferable: suppose there is a
source()-like function sourcelike() in a foreign package (a
package for which you do not have write permission). Suppose that you write
your own function in which the formals are (...) to wrap
sourcelike():
wrapper <- function (...)
{
## possibly more args to wrap.source()
wrap.source(sourcelike(...))
}This is the only scenario in which wrap.source() is preferable, since
extracting the file from the ... list would be a pain. Then again,
you could simply change the formals of wrapper() from (...)
to (file, ...). If this does not describe your exact scenario, use
set.sys.path() instead.
for set.sys.path(), if file is a path, then the normalized
path with the same attributes, otherwise file itself. The return value
of set.sys.path() should be assigned to a variable before use,
something like:
{
file <- set.sys.path(file, ...)
sourcelike(file)
}for set.env.path(), envir invisibly.
for set.src.path(), srcfile invisibly.
for unset.sys.path() and set.sys.path.function(), NULL
invisibly.
for with_sys.path() and wrap.source(), the result of evaluating
expr.
ofile can be used when the file argument supplied to
set.sys.path() is not the same as the file argument supplied to
the source()-like function:
sourcelike <- function (file)
{
ofile <- file
if (!is.character(ofile) || length(ofile) != 1)
stop(gettextf("'%s' must be a character string", "file"))
## if the file exists, do nothing
if (file.exists(file)) {
}
## look for the file in the home directory
## if it exists, do nothing
else if (file.exists(file <- @R_PACKAGE_NAME@::path.join("~", ofile))) {
}
## you could add other directories to look in,
## but this is good enough for an example
else stop(gettextf("'%s' is not an existing file", ofile))
file <- @R_PACKAGE_NAME@::set.sys.path(file, ofile = ofile)
exprs <- parse(n = -1, file = file)
for (i in seq_along(exprs)) eval(exprs[i], envir)
invisible()
}