R.utils (version 2.3.0)

sourceTo: Parses and evaluates code from a file or a connection

Description

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.

Usage

"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.

See Also

sourceDirectory(). sys.source() and source().

Examples

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

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")
lsBefore <- NA
lsBefore <- ls()
foo(file=textConnection(c('a <- 1', 'b <- 2')))

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


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

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)
setHook("sourceTo/onPreprocess", oldHooks, action="replace")