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

