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

sourceTo {R.utils} | R Documentation

## 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

    ## Default S3 method:
    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(s)

Henrik Bengtsson

### 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")

[Package R.utils version 2.7.0 Index]