\Header{eval}{Evaluate an (Unevaluated) Expression}
\alias{evalq}{eval}
\keyword{data}{eval}
\keyword{programming}{eval}
\begin{Usage}
\begin{verbatim}
eval(expr, envir=sys.frame(sys.parent()), 
   enclos=if(is.list(envir) || is.pairlist(envir)) 
             sys.frame(sys.parent()))

evalq(expr, envir, enclos)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{expr}] object of mode \texttt{\Link{expression}} or an ``unevaluated
expression''.
\item[\texttt{envir}] the \texttt{\Link{environment}} in which \texttt{expr} is to be
evaluated. May also be a list or an integer as in \texttt{sys.call}.
\item[\texttt{enclos}] Only relevant if \texttt{envir} is a list. Specifies the
enclosure, i.e. where R looks for objects not found in \texttt{envir}.
\end{ldescription}
\end{Arguments}
\begin{Description}
This function evaluates the expression \texttt{expr} argument in the
environment specified by \texttt{envir} and returns the computed value.  If
\texttt{envir} is not specified, then
\texttt{\Link{sys.frame}(\Link{sys.parent}())}, the environment where the
call to \texttt{eval} was made is used. The \texttt{eval} form evaluates its first
argument before passing it to the evaluator.
This allows you to assign complicated expressions to symbols and then
evaluate them. The \texttt{evalq} form is equivalent to
\texttt{eval(quote(expression), ...)}\end{Description}
\begin{Note}
Due to the difference in scoping rules, there are some differences
between R and S in this area. In particular, the default enclosure
in S is the global environment.

When evaluating expressions in dataframes that has been passed as
argument to a function, the relevant enclosure is often the caller's
environment, i.e. one needs 
\texttt{eval(x, data, sys.frame(sys.parent()))}.\end{Note}
\begin{SeeAlso}
\texttt{\Link{expression}}, \texttt{quote}, \texttt{\Link{sys.frame}},
\texttt{\Link{environment}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
eval(2 ^ 2 ^ 3)
mEx <- expression(2^2^3); mEx; 1 + eval(mEx)
eval({ xx <- pi; xx^2}) ; xx

a <- 3 ; aa <- 4 ; evalq(evalq(a+b+aa, list(a=1)), list(b=5)) # == 10
a <- 3 ; aa <- 4 ; evalq(evalq(a+b+aa, 1), list(b=5))         # == 12

ev <- function() {
	e1 <- sys.frame(sys.parent())
	## Evaluate a in e1
	aa <- eval(expression(a),e1)
	## evaluate the expression bound to a in e1
	a <- expression(x+y)
	list(aa = aa, eval = eval(a, e1))
}
tst.ev <- function(a = 7) { x <- pi; y <- 1; ev() }
tst.ev()#-> aa : 7,  eval : 4.14
\end{ExampleCode}
\end{Examples}

