\HeaderA{parse}{Parse Expressions}{parse}
\keyword{file}{parse}
\keyword{programming}{parse}
\keyword{connection}{parse}
\begin{Description}\relax
\code{parse} returns the parsed but unevaluated expressions in a
list.
\end{Description}
\begin{Usage}
\begin{verbatim}
parse(file = "", n = NULL, text = NULL, prompt = "?", srcfile,
      encoding = "unknown")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{file}] a connection, or a character string giving the name of a
file or a URL to read the expressions from.
If \code{file} is \code{""} and \code{text} is missing or \code{NULL}
then input is taken from the console.
\item[\code{n}] integer (or coerced to integer).  The maximum number of
expressions to parse.  If \code{n} is \code{NULL} or negative or
\code{NA} the input is parsed in its entirety.
\item[\code{text}] character vector.  The text to parse.  Elements are treated
as if they were lines of a file.  Other \R{} objects will be coerced
to character (without method dispatch) if possible.
\item[\code{prompt}] the prompt to print when parsing from the keyboard.
\code{NULL} means to use \R's prompt, \code{getOption("prompt")}.
\item[\code{srcfile}] \code{NULL}, or a \code{\LinkA{srcfile}{srcfile}} object.  See
the \sQuote{Details} section.
\item[\code{encoding}] encoding to be assumed for input strings.  If the
value is \code{"latin1"} or \code{"UTF-8"} it is used to mark
character strings as known to be in Latin-1 or UTF-8: it is not used
to re-encode the input.  To do the latter, specify the encoding as
part of the connection \code{con} or \emph{via}
\code{\LinkA{options}{options}(encoding=)}: see the example under
\code{\LinkA{file}{file}}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
If \code{text} has length greater than zero (after coercion) it is used in
preference to \code{file}.

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 Mac OS).  The final line can be incomplete,
that is missing the final EOL marker.

See \code{\LinkA{source}{source}} for the limits on the size of functions
that can be parsed (by default).

When input is taken from the console, \code{n = NULL} is equivalent to
\code{n = 1}, and \code{n < 0} will read until an EOF character is read.

The default for \code{srcfile} is set as follows.  If
\code{options("keep.source")} is \code{FALSE}, \code{srcfile}
defaults to \code{NULL}. Otherwise, if \code{text} is used,
\code{srcfile} will be set to a \code{\LinkA{srcfilecopy}{srcfilecopy}} containing
the text.  If a character string is used for \code{file}, a
\code{\LinkA{srcfile}{srcfile}} object referring to that file will be used.
\end{Details}
\begin{Value}
An object of type \code{"\LinkA{expression}{expression}"}, with up to \code{n}
elements if specified as a non-negative integer.

When \code{srcfile} is non-\code{NULL}, a \code{"srcref"} attribute
will be attached to the result containing a list of \code{\LinkA{srcref}{srcref}}
records corresponding to each element, and a \code{"srcfile"} attribute
will be attached containing a copy of \code{srcfile}.

A syntax error (including an incomplete expression) will throw an error.

Character strings in the result will have a declared encoding if
\code{encoding} is \code{"latin1"} or \code{"UTF-8"}, or if
\code{text} is supplied with every element of known encoding in a
Latin-1 or UTF-8 locale.
\end{Value}
\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{scan}{scan}}, \code{\LinkA{source}{source}}, \code{\LinkA{eval}{eval}},
\code{\LinkA{deparse}{deparse}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
cat("x <- c(1,4)\n  x ^ 3 -10 ; outer(1:7,5:9)\n", file="xyz.Rdmped")
# parse 3 statements from the file "xyz.Rdmped"
parse(file = "xyz.Rdmped", n = 3)
unlink("xyz.Rdmped")
\end{ExampleCode}
\end{Examples}

