sourceTo               package:R.utils               R Documentation

_P_a_r_s_e_s _a_n_d _e_v_a_l_u_a_t_e_s _c_o_d_e _f_r_o_m _a _f_i_l_e _o_r _a _c_o_n_n_e_c_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

     ## Default S3 method:
     sourceTo(file, chdir=FALSE, ..., local=TRUE, envir=parent.frame(), modifiedOnly=FALSE)

_A_r_g_u_m_e_n_t_s:

    file: A 'connection' or a 'character' string giving the pathname of
          the file or URL to read from.

   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.

_V_a_l_u_e:

     Return the result of 'source'().

_H_o_o_k_s:

     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.

_A_u_t_h_o_r(_s):

     Henrik Bengtsson (<URL: http://www.braju.com/R/>)

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

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

