| % File src/library/base/man/eval.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2011 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{eval} |
| \alias{eval} |
| \alias{evalq} |
| \alias{eval.parent} |
| \alias{local} |
| \title{Evaluate an (Unevaluated) Expression} |
| \description{ |
| Evaluate an \R expression in a specified environment. |
| } |
| \usage{ |
| eval(expr, envir = parent.frame(), |
| enclos = if(is.list(envir) || is.pairlist(envir)) |
| parent.frame() else baseenv()) |
| evalq(expr, envir, enclos) |
| eval.parent(expr, n = 1) |
| local(expr, envir = new.env()) |
| } |
| \arguments{ |
| \item{expr}{an object to be evaluated. See \sQuote{Details}.} |
| \item{envir}{the \code{\link{environment}} in which \code{expr} is to |
| be evaluated. May also be \code{NULL}, a list, a data frame, |
| a pairlist or an integer as specified to \code{\link{sys.call}}.} |
| \item{enclos}{Relevant when \code{envir} is a (pair)list or a data frame. |
| Specifies the enclosure, i.e., where \R looks for objects not found |
| in \code{envir}. This can be \code{NULL} (interpreted as the base |
| package environment, \code{\link{baseenv}()}) or an environment.} |
| \item{n}{number of parent generations to go back} |
| } |
| \details{ |
| \code{eval} evaluates the \code{expr} argument in the |
| environment specified by \code{envir} and returns the computed value. |
| If \code{envir} is not specified, then the default is |
| \code{\link{parent.frame}()} (the environment where the call to |
| \code{eval} was made). |
| |
| Objects to be evaluated can be of types \code{\link{call}} or |
| \code{\link{expression}} or \link{name} (when the name is looked |
| up in the current scope and its binding is evaluated), a \link{promise} |
| or any of the basic types such as vectors, functions and environments |
| (which are returned unchanged). |
| |
| The \code{evalq} form is equivalent to \code{eval(quote(expr), \dots)}. |
| \code{eval} evaluates its first argument in the current scope |
| before passing it to the evaluator: \code{evalq} avoids this. |
| |
| \code{eval.parent(expr, n)} is a shorthand for |
| \code{eval(expr, parent.frame(n))}. |
| |
| If \code{envir} is a list (such as a data frame) or pairlist, it is |
| copied into a temporary environment (with enclosure \code{enclos}), |
| and the temporary environment is used for evaluation. So if |
| \code{expr} changes any of the components named in the (pair)list, the |
| changes are lost. |
| |
| If \code{envir} is \code{NULL} it is interpreted as an empty list so |
| no values could be found in \code{envir} and look-up goes directly to |
| \code{enclos}. |
| |
| \code{local} evaluates an expression in a local environment. It is |
| equivalent to \code{evalq} except that its default argument creates a |
| new, empty environment. This is useful to create anonymous recursive |
| functions and as a kind of limited namespace feature since variables |
| defined in the environment are not visible from the outside. |
| } |
| \value{ |
| The result of evaluating the object: for an expression vector this is |
| the result of evaluating the last element. |
| } |
| \references{ |
| Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) |
| \emph{The New S Language}. |
| Wadsworth & Brooks/Cole. (\code{eval} only.) |
| } |
| \seealso{ |
| \code{\link{expression}}, \code{\link{quote}}, \code{\link{sys.frame}}, |
| \code{\link{parent.frame}}, \code{\link{environment}}. |
| |
| Further, \code{\link{force}} to \emph{force} evaluation, typically of |
| function arguments. |
| } |
| \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 a data frame that has been passed as an |
| argument to a function, the relevant enclosure is often the caller's |
| environment, i.e., one needs |
| \code{eval(x, data, parent.frame())}. |
| } |
| \examples{ |
| 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 <- parent.frame() |
| ## 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 |
| |
| a <- list(a = 3, b = 4) |
| with(a, a <- 5) # alters the copy of a from the list, discarded. |
| |
| ## |
| ## Example of evalq() |
| ## |
| |
| N <- 3 |
| env <- new.env() |
| assign("N", 27, envir = env) |
| ## this version changes the visible copy of N only, since the argument |
| ## passed to eval is '4'. |
| eval(N <- 4, env) |
| N |
| get("N", envir = env) |
| ## this version does the assignment in env, and changes N only there. |
| evalq(N <- 5, env) |
| N |
| get("N", envir = env) |
| |
| |
| ## |
| ## Uses of local() |
| ## |
| |
| # Mutually recursive. |
| # gg gets value of last assignment, an anonymous version of f. |
| |
| gg <- local({ |
| k <- function(y)f(y) |
| f <- function(x) if(x) x*k(x-1) else 1 |
| }) |
| gg(10) |
| sapply(1:5, gg) |
| |
| # Nesting locals: a is private storage accessible to k |
| gg <- local({ |
| k <- local({ |
| a <- 1 |
| function(y){print(a <<- a+1);f(y)} |
| }) |
| f <- function(x) if(x) x*k(x-1) else 1 |
| }) |
| sapply(1:5, gg) |
| |
| ls(envir = environment(gg)) |
| ls(envir = environment(get("k", envir = environment(gg)))) |
| } |
| \keyword{data} |
| \keyword{programming} |