Parses and evaluates code from a file or a connection

Parses and evaluates code from a file or a connection. This has the same effect as if source(..., local=TRUE) would have been called from within the given environment. This is useful when setting up a new local working environment.

# S3 method for default
sourceTo(file, path=NULL, chdir=FALSE, ..., local=TRUE, envir=parent.frame(),
  modifiedOnly=FALSE)

Arguments

file: A connection or a character string giving the pathname of the file or URL to read from.
path: An optional character string giving the path to the file. Ignored if file is a connection.
chdir: If TRUE and file is a pathname, the R working directory is temporarily changed to the directory containing file for evaluating.
...: Arguments to source(). If argument file is not explicitly given, the first argument is assumed to be the file argument. This argument is converted into a string by as.character().
local: If FALSE, evaluation is done in the global environment, otherwise in the calling environment.
envir: An environment in which source() should be called. If NULL, the global environment is used.
modifiedOnly: If TRUE, the file is sourced only if modified since the last time it was sourced, otherwise regardless.

Value

Return the result of source().

Hooks

This methods recognizes the hook sourceTo/onPreprocess, which is called after the lines in file has been read, but before they have been parsed by the R parser, cf. parse(). An onPreprocess hook function should take a character vector of code lines and return a character vector of code lines. This can for instance be used to pre-process R source code with special directives such as VComments.

Note that only one hook function can be used for this function, otherwise an error is generated.

Author

Henrik Bengtsson

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Example 1
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cat("=== Example 1 ================================================\n")
#> === Example 1 ================================================

foo <- function(file, ...) {
  cat("Local objects before calling sourceTo():\n")
  print(ls())

  res <- sourceTo(file, ...)

  cat("Local objects after calling sourceTo():\n")
  print(ls())
}

cat("Global objects before calling foo():\n")
#> Global objects before calling foo():
lsBefore <- NA
lsBefore <- ls()
foo(file=textConnection(c('a <- 1', 'b <- 2')))
#> Local objects before calling sourceTo():
#> [1] "file"
#> Local objects after calling sourceTo():
#> [1] "a"    "b"    "file" "res" 

cat("Global objects after calling foo():\n")
#> Global objects after calling foo():
stopifnot(length(setdiff(ls(), lsBefore)) == 0)


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Example 2 - with VComments preprocessor
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
cat("=== Example 2 ================================================\n")
#> === Example 2 ================================================

preprocessor <- function(lines, ...) {
  cat("-----------------------------------------\n")
  cat("Source code before preprocessing:\n")
  displayCode(code=lines, pager="console")
  cat("-----------------------------------------\n")
  cat("Source code after preprocessing:\n")
  lines <- VComments$compile(lines)
  displayCode(code=lines, pager="console")
  cat("-----------------------------------------\n")
  lines
}

oldHooks <- getHook("sourceTo/onPreprocess")
setHook("sourceTo/onPreprocess", preprocessor, action="replace")
code <- c(
 'x <- 2',
 '#V1# threshold=-1',
 '#Vc# A v-comment log message',
 'print("Hello world")'
)
fh <- textConnection(code)
sourceTo(fh)
#> -----------------------------------------
#> Source code before preprocessing:
#> Warning: error in running command
#> -----------------------------------------
#> Source code after preprocessing:
#> Warning: error in running command
#> -----------------------------------------
#> [1] "Hello world"
setHook("sourceTo/onPreprocess", oldHooks, action="replace")