eval                  package:base                  R Documentation

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())
     evalq(expr, envir, enclos)
     eval.parent(expr, n = 1)
     local(expr, envir = new.env())

Arguments:

    expr: object of mode 'expression' or 'call' or an "unevaluated
          expression".

   envir: the 'environment' in which 'expr' is to be evaluated.  May
          also be a list, a data frame, or an integer as in 'sys.call'.

  enclos: Relevant when 'envir' is a list or a data frame. Specifies
          the enclosure, i.e., where R looks for objects not found in
          'envir'.

       n: parent generations to go back

Details:

     'eval' evaluates the expression 'expr' argument in the environment
     specified by 'envir' and returns the computed value. If 'envir' is
     not specified, then 'sys.frame(sys.parent())', the environment
     where the call to 'eval' was made is used.

     The 'evalq' form is equivalent to 'eval(quote(expr), ...)'.

     As 'eval' evaluates its first argument before passing it to the
     evaluator, it allows you to assign complicated expressions to
     symbols and then evaluate them.  'evalq' avoids this.

     'eval.parent(expr, n)' is a shorthand for 'eval(expr,
     parent.frame(n))'.

     'local' evaluates an expression in a local environment.  It is
     equivalent to 'evalq' except the 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.

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 data frames that has been passed as
     argument to a function, the relevant enclosure is often the
     caller's environment, i.e., one needs 'eval(x, data,
     parent.frame())'.

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole. ('eval' only.)

See Also:

     'expression', 'quote', 'sys.frame', 'parent.frame', 'environment'.

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

     ##
     ## Uses of local()
     ##

     # Mutual recursives.
     # 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))))

