src/library/base/man/sys.source.Rd

% File src/library/base/man/sys.source.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2022 R Core Team
% Distributed under GPL 2 or later

\name{sys.source}
\alias{sys.source}
\title{Parse and Evaluate Expressions from a File}
\description{
  Parses expressions in the given file, and then successively evaluates
  them in the specified environment.
}
\usage{
sys.source(file, envir = baseenv(), chdir = FALSE,
           keep.source = getOption("keep.source.pkgs"),
           keep.parse.data = getOption("keep.parse.data.pkgs"),
           toplevel.env = as.environment(envir))
}
\arguments{
  \item{file}{a character string naming the file to be read from}
  \item{envir}{an \R object specifying the environment in which the
    expressions are to be evaluated.  May also be a list or an integer.
    The default \code{\link{baseenv}()} corresponds to evaluation in the base
    environment.  This is probably not what you want; you should
    typically supply an explicit \code{envir} argument, see the
    \sQuote{Note}.}
  \item{chdir}{logical; if \code{TRUE}, the \R working directory is
    changed to the directory containing \code{file} for evaluating.}
  \item{keep.source}{logical.  If \code{TRUE}, functions keep
    their source including comments, see
    \code{\link{options}(keep.source = *)} for more details.}
  \item{keep.parse.data}{logical.  If \code{TRUE} and \code{keep.source} is
    also \code{TRUE}, functions keep parse data with their source, see
    \code{\link{options}(keep.parse.data = *)} for more details.}
  \item{toplevel.env}{an \R environment to be used as top level while
    evaluating the expressions.  This argument is useful for frameworks
    running package tests; the default should be used in other cases}
}
\details{
  For large files, \code{keep.source = FALSE} may save quite a bit of
  memory. Disabling only parse data via \code{keep.parse.data = FALSE}
  can already save a lot.
}
\section{Note on \code{envir}}{
  In order for the code being evaluated to use the correct environment
  (for example, in global assignments), source code in packages should
  call \code{\link{topenv}()}, which will return the namespace, if any,
  the environment set up by \code{sys.source}, or the global environment
  if a saved image is being used.
}
\seealso{\code{\link{source}}, and \code{\link{loadNamespace}} which
  is called from \code{\link{library}(.)} and uses \code{sys.source(.)}.
}
\examples{
## a simple way to put some objects in an environment
## high on the search path
tmp <- tempfile()
writeLines("aaa <- pi", tmp)
env <- attach(NULL, name = "myenv")
sys.source(tmp, env)
unlink(tmp)
search()
aaa
detach("myenv")
}
\keyword{file}
\keyword{utilities}