eval                  package:base                  R Documentation

_E_v_a_l_u_a_t_e _a_n (_U_n_e_v_a_l_u_a_t_e_d) _E_x_p_r_e_s_s_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     Evaluate an R expression in a specified environment.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

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

   envir: the 'environment' in which 'expr' is to be evaluated.  May
          also be, 'NULL', 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

_D_e_t_a_i_l_s:

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

     If 'envir' is a data frame or list, it is copied into a temporary
     environment, and the copy is used for evaluation.  So if 'expr'
     changes any of the components named in the data frame/list, the
     changes are lost.

     If 'envir' is 'NULL' it is treated as an empty list or data frame:
     no values will be found in 'envir', so look-up goes directly to
     'enclos'.

     A value of 'NULL' for 'enclos' is interpreted as the environment
     of the base package.

     '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.

_N_o_t_e:

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

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

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

     Further, 'force' to _force_ evaluation, typically of function
     arguments.

_E_x_a_m_p_l_e_s:

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

