The R Project SVN R

% 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}