\HeaderA{source}{Read R Code from a File or a Connection}{source}
\keyword{file}{source}
\keyword{programming}{source}
\keyword{connection}{source}
\begin{Description}\relax
\code{source} causes \R{} to accept its input from the named file or URL
(the name must be quoted) or connection.  Input is read and
\code{\LinkA{parse}{parse}}d by from that file until the end of the file is
reached, then the parsed expressions are evaluated sequentially in the
chosen environment.
\end{Description}
\begin{Usage}
\begin{verbatim}
source(file, local = FALSE, echo = verbose, print.eval = echo,
       verbose = getOption("verbose"),
       prompt.echo = getOption("prompt"),
       max.deparse.length = 150, chdir = FALSE,
       encoding = getOption("encoding"),
       continue.echo = getOption("continue"),
       skip.echo = 0)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{file}] a connection or a character string giving the pathname
of the file or URL to read from.
\item[\code{local}] if \code{local} is \code{FALSE}, the statements scanned
are evaluated in the user's workspace (the global environment),
otherwise in the environment calling \code{source}.
\item[\code{echo}] logical; if \code{TRUE}, each expression is printed
after parsing, before evaluation.
\item[\code{print.eval}] logical; if \code{TRUE}, the result of
\code{eval(i)} is printed for each expression \code{i}; defaults
to \code{echo}.
\item[\code{verbose}] if \code{TRUE}, more diagnostics (than just
\code{echo = TRUE}) are printed during parsing and evaluation of
input, including extra info for \bold{each} expression.
\item[\code{prompt.echo}] character; gives the prompt to be used if
\code{echo = TRUE}.
\item[\code{max.deparse.length}] integer; is used only if \code{echo} is
\code{TRUE} and gives the maximal number of characters output for
the deparse of a single expression.
\item[\code{chdir}] logical; if \code{TRUE} and \code{file} is a pathname,
the \R{} working directory is temporarily changed to the directory
containing \code{file} for evaluating.
\item[\code{encoding}] character vector.  The encoding(x) to be assumed when
\code{file} is a character string: see \code{\LinkA{file}{file}}.  A
possible value is \code{"unknown"}: see the \sQuote{Details}.
\item[\code{continue.echo}] character; gives the prompt to use on
continuation lines if \code{echo = TRUE}.
\item[\code{skip.echo}] integer; how many comment lines at the start of the
file to skip if \code{echo = TRUE}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
All versions of \R{} accept input from a connection with end of line
marked by LF (as used on Unix), CRLF (as used on DOS/Windows)
or CR (as used on classic MacOS).  The final line can be incomplete, that
is missing the final end-of-line marker.

If \code{\LinkA{options}{options}}("keep.source") is true (the default), the
source of functions is kept so they can be listed exactly as input.
This imposes a limit of 128K bytes on the function size and a nesting
limit of 265.  Use \code{option(keep.source = FALSE)} when these
limits might take effect: if exceeded they generate an error.

This paragraph applies if \code{file} is a filename (rather than a
connection).  If \code{encoding = "unknown"}, an attempt is made to
guess the encoding.  The result of \code{\LinkA{localeToCharset}{localeToCharset}()} is
used as a guide.  If \code{encoding} has two or more elements, they are
tried in turn until the file/URL can be read without error in the
trial encoding.

Unlike input from a console, lines in the file or on a connection can
contain an unlimited number of characters.  However, there is a limit
of 8192 bytes on the size of character strings.

When \code{skip.echo > 0}, that many comment lines at the start of
the file will not be echoed.  This does not affect the execution of
the code at all.  If there are executable lines within the first
\code{skip.echo} lines, echoing will start with the first of them.

If \code{echo} is true and a deparsed expression exceeds
\code{max.deparse.length}, that many characters are output followed by
\code{ .... [TRUNCATED] }.
\end{Details}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{demo}{demo}} which uses \code{source};
\code{\LinkA{eval}{eval}}, \code{\LinkA{parse}{parse}} and \code{\LinkA{scan}{scan}};
\code{\LinkA{options}{options}("keep.source")}.

\code{\LinkA{sys.source}{sys.source}} which is a streamlined version to source a
file into an environment.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## If you want to source() a bunch of files, something like
## the following may be useful:
 sourceDir <- function(path, trace = TRUE, ...) {
    for (nm in list.files(path, pattern = "\\.[RrSsQq]$")) {
       if(trace) cat(nm,":")           
       source(file.path(path, nm), ...)
       if(trace) cat("\n")
    }
 }
\end{ExampleCode}
\end{Examples}

