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 dataframes 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())'.

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))))

